DEV Community: Zhengxin

Meta Connect 2026 in 5 minutes: 7 products, prices, ship dates

Zhengxin — Thu, 24 Sep 2026 05:40:12 +0000

Meta Connect 2026 was a 55-minute keynote. Here is what actually shipped, with prices and dates, in the order it was announced. The full recap with timestamps into the keynote video is here: Meta Connect 2026: the 55-minute keynote in 5 minutes.

1. Muse gets computer use, email and shopping

Muse is the personal agent Meta launched a few weeks ago, and it was the center of the whole show. New today:

Computer use. With your permission Muse can drive any app on your Mac and keeps working on queued jobs after you walk away. The Mac app itself launched last week.
Its own email address. Add Muse to a thread or forward mail and it handles it for you. Launch connectors: Spotify, OpenTable, Plaid, Ticketmaster. The connector platform is open, with 1,500+ apps already.
Shopping. Deep partnerships with Stripe and Shopify: Muse browses the Shopify catalog and buys with Link and Shop Pay, PayPal coming. Walmart, Best Buy, Gap, Sephora and Wayfair are integrating.
Voice. You design your Muse's voice, and a real-time model animates its avatar while you talk.

Each Muse runs on its own Muse Secure VM. A Confidential VM is coming so nobody, including Meta, can read your data. Free for a large token allowance; Meta plans to take a small fee on transactions. Just rolled out in Canada.

2. Ray-Ban Meta Audio: glasses with no camera

A new category. Drop the camera and you get the thinnest, lightest Ray-Ban Meta yet with a full day of battery, built around Muse, music and calls. The reworked electronics fit classic shapes like the Clubmaster.

$349. Pre-order now, ships October 13.

3. Ray-Ban Meta Gen 3

The whole Ray-Ban Meta line moves to Gen 3: slimmer frame and temples, adjustable temple tips, better battery, Dolby Atmos spatial audio capture, and microphones that Meta says work on a jet ski. Two new shapes for the first time: Aviator and Zena, plus a 90th-anniversary launch edition Aviator.

$449. Available now.

4. Meta Glasses lineup: 51 styles, Adventurer from $249

The Meta Glasses line from June grows to 51 style combinations. New frames Capri (cat-eye) and Nova (panto), an ivory colorway with Kylie Jenner, and a LISA edition with a custom case and unlockable app features. By year end Meta will sell over 100 styles across Display, audio, Ray-Ban, Oakley and Meta Glasses.

From $249. Adventurer ships October 23.

5. Meta Ray-Ban Display is finally in stock

The Display glasses with the Neural Band sold out for most of the year. Supply has caught up: on sale online at meta.com in the US, Canada and UK, with France, Italy and Germany on October 13. Hologram video calls from the glasses are coming.

6. Meta VR Glasses: 100 grams, $1,299.99, spring 2027

The big reveal. About 100 grams on your face, a fifth of Quest 3, with compute and battery moved off the face into a tethered puck. Muse is built into the OS. Input is eyes, hands and voice, including typing on any flat surface (Meta's CFO reportedly hit 120 wpm).

Content: first IMAX Enhanced certified VR device with Dolby Vision and Atmos, 75 hands-only launch titles, the full Quest library with optional controllers, Xbox Cloud Gaming, a Disney+ 3D app, ESPN front-row 180-degree live games at no extra cost, and full-body hologram calling.

$1,299.99 (from the press release). Ships spring 2027.

7. Muse Charm: the agent on a keychain

The closer. The real-time voice and avatar stack squeezed into a keychain: tap the fingerprint sensor and talk, no phone needed. Materials are still being finalized.

Price not announced. Planned for the December holidays.

Three prices above ($349, $449 and the exact $1,299.99) came from Meta's newsroom posts, not the stage. Everything else is from the keynote, and the full recap links each claim to the exact second in the video, with a chapter list and FAQ. It was built by running the keynote through Summarize Video To Text and hand-checking the numbers.

ChatGPT Still Can't Read YouTube Links. Here's the Copy-Paste That Actually Works.

Zhengxin — Wed, 23 Sep 2026 08:01:21 +0000

Someone sends you a 45-minute video. You don't have 45 minutes.

So you paste the link into ChatGPT and ask what's in it. It answers immediately — five clean bullet points, confident, well organised. You skim them, feel caught up, and move on.

You just read the video's description. Not the video.

This is the most common way people waste time with AI and video, and it's invisible, because the wrong answer looks exactly like the right one. r/ChatGPT has been asking about it for three years straight:

ChatGPT can't watch a YouTube video. It reads the title and the description — the blurb the creator wrote to get you to click — and summarizes that. No prompt fixes it. It isn't your wording.

How to tell it happened to you

Three tells, ten seconds to check:

It's suspiciously even. Real talks ramble and spend nine minutes on one point. A summary where every section gets equal weight is a summary of an outline.
Nothing in it is specific. No numbers, no names, no "she argues that…". Just topics.
It matches the thumbnail. If it's a longer version of the promise on the thumbnail, you got the marketing copy.

The real test: take one claim from the summary and ask whether it could only have come from someone speaking. If nothing passes, you didn't get the video.

The fix: 15 seconds, no account

Go to SummarizeVideoToText, paste the same link, press the button.

What comes back is what you thought you were getting the first time:

The full transcript — every word actually spoken, as clean text you can search, copy, or keep.
A structured summary built from that transcript, so the specifics survive: the numbers, the names, the part where the argument actually turns.
Chapter timestamps, so when one section matters you jump straight to minute 31 instead of scrubbing for it.

No sign-up for any of that. Anonymous use covers two videos a day, up to 15 minutes each — enough to settle most "what's in this" questions on the spot. A free account raises it to an hour per video, which is where lectures, interviews and conference talks live.

It also works on the videos ChatGPT has no story for at all: upload a Zoom or Teams recording, a lecture file, a video off X or TikTok. Anything you can get to, you can get the words out of.

Then take it back to ChatGPT, if you want

The summary is usually where it ends. But if this is something you need to think with — a talk you're responding to, research you're going to cite — copy the transcript out and paste it into ChatGPT with a real prompt. Now it has the actual words, so it can do the thing it's good at:

Below is the transcript of a video.

Give me:
1. A 3-sentence summary of the actual argument
2. The 5 most specific claims made, with the
   reasoning given for each
3. Anything stated as fact that I should verify
4. What it does NOT cover that I'd expect it to

Skip the intro and the sponsor read.

Transcript:
[paste]

Asking for "the reasoning given" is what keeps it inside the transcript. Ask for "key points" and it starts filling in from general knowledge, and you're back where you started.

One thing to watch: an hour of video is around 10,000 words, and a very long paste can get quietly cut off — you'll get a summary of the first third with no warning. Attach it as a file instead of pasting, or do it in two halves.

If you'd rather not use anything

You can pull the transcript out of YouTube by hand: under the video, ... → Show transcript, then the three dots in that panel → turn off Toggle timestamps, select all, copy. It's free and it works.

It's also only available when the video has captions, it's missing on mobile web in places, and past about 30 minutes you're dragging a selection down a panel that keeps scrolling out from under you. Fine once. Not something you'll do twice.

The one-line version

ChatGPT isn't bad at summarizing videos. It's never seen one. Give it the words — or skip that step and get the summary directly.

Paste your link here. Transcript, summary and timestamps, no account, about fifteen seconds.

Comparing tools for this? We keep a rundown separately.

Studying a YouTube course in Obsidian: playlist in, notes and flashcards out

Zhengxin — Sun, 20 Sep 2026 11:01:03 +0000

A single conference talk is easy to deal with. A course is the thing that defeats me.

Forty videos in a playlist, and by video six the notes have stopped. The material isn't the problem. The bookkeeping is. Which ones have I done. What did video three establish that video nine now assumes I remember. Where did I put any of it.

I've spent the last few months building SummarizeVideoToText and its Obsidian plugin, and I wrote up the plugin internals a while back — markers, tokens, the review rules. This post is the other half. Not how it's built, but what the two halves are for when you point them at a whole course instead of one video. The annoying parts are still in.

The playlist becomes a queue, not a folder

Paste a YouTube playlist URL into the web app and it imports as a collection, up to 500 videos.

You get a preview step first: the title, the count, the first handful of videos, and then a confirm. That step exists because an import that silently grabs the wrong 200 videos is worse than no import at all, and you don't find out until you're three summaries deep.

Everything lands marked "to learn". Nothing is summarized yet.

That last part is the whole design. Summarizing 40 videos up front gives you 40 documents nobody opens. What you want is a queue with a cursor in it. The collection row on the dashboard carries one button — Continue · Part 7 — and that button is the only decision you have to make when you sit down.

One video becomes one note

From inside Obsidian: one command, one link, one note.

What lands in the vault is a TL;DR, key insights, timestamped chapters, frontmatter shaped for Dataview, and an embedded player at the top so a timestamp seeks in place instead of throwing you back to YouTube. Optional extras are the full transcript in a collapsed callout, a quiz, and a longer summary in one of several templates.

Two things about it that matter over a long course rather than a single video.

The note has a generated region between %% svt:start %% and %% svt:end %%, and a "My notes" section outside it. Re-running the command replaces the generated region and leaves your writing alone. On video nine, when you realise your frontmatter tags were wrong on all eight previous notes, you can re-run all of them without losing a word you wrote yourself.

And re-opening a video that's already been processed never costs a credit. Refreshing a note you made last week is free.

If you don't use Obsidian, the same note exports to Notion as a real page, or downloads as Markdown with the timestamps still clickable.

The quiz becomes cards

There's a command that turns the quiz in a video note into Spaced Repetition cards in a separate note.

Run it again after a refresh and it only appends the new questions. Cards you already have, cards you wrote by hand, and the  review scheduling the SR plugin writes back are all left untouched. This sounds like a detail and it is the reason the command is safe to press. A "regenerate my flashcards" button that resets three weeks of review intervals is a button you press exactly once.

A quiz across the whole collection

Per-video quizzes test whether you were awake. The thing I actually wanted was a quiz drawn across the collection, because that's where a course either connected for you or didn't — video three's definition showing up inside video nine's argument.

That one runs on the web side, not in the vault, and it's the feature I'd point at if you asked me what a "collection" is for beyond grouping.

Here's one of mine, published: 3Blue1Brown's neural network series — eight videos, eight notes, one page. That's the shape the vault ends up in too, minus the Obsidian chrome.

What it costs

No account at all: 2 summaries a day, videos up to 15 minutes, plus one TikTok / Instagram / X video a day up to 5 minutes. Transcripts are readable, copyable and downloadable without signing in, five a day. No email, no signup wall to get a look at the output.
Free, signed in: 10 credits a month, which is roughly ten videos, with videos up to an hour, plus saved history, collections, and the Obsidian and Notion exports. Playlist import needs this tier — 500 videos of state has to live somewhere.
Pro: $9/month (launch price, normally $12) or $54/year. Unlimited summaries under fair use, videos up to 6 hours, and 300 credits a month for the transcription cases. The 6 hours is the reason this tier exists at all: lecture recordings and conference livestreams are absurdly long.
Top-ups, if you don't want a subscription: $1 for 20 credits, once per account, or $5 for 100. Bought credits don't expire, and they're only spent once the monthly ones run out.

TikTok, Instagram, X and uploaded files cost more per video than YouTube does, because those have to be transcribed rather than read.

Output comes in 14 languages, and the output language is independent of the video's. Watching a Spanish lecture and keeping notes in English is the normal case, not a workaround.

What it doesn't do

Everything downstream is derived from the words. Captions when YouTube has them, speech-to-text when it doesn't. That means a lecture where the argument lives on the whiteboard and the speaker says "so this equals that" produces a summary that is technically accurate and completely useless. I have no good answer for that one yet. Diagram-heavy talks are where I still take notes by hand.

The plugin also holds no model keys and does no inference locally. It's a client for an account on the server, and it needs the network. If your requirement is that your vault never talks to anything, this is the wrong tool and I'd rather you know that from the third paragraph than from the settings screen.

It needs Obsidian 1.13.0 or newer. The declarative settings API the community review pushed me toward doesn't exist before that.

Links

Web app: summarizevideototext.com
A finished collection, if you want to see the output before installing anything: 3Blue1Brown, 8 chapters with notes
Obsidian plugin: community.obsidian.md/plugins/summarize-video-to-text
Source, MIT: github.com/diaozxin007/obsidian-summarize-video-to-text
Setup walkthrough: summarizevideototext.com/obsidian-plugin
If your material is lectures specifically: summarizevideototext.com/ai-lecture-summarizer

The playlist-as-a-queue idea is the part I'd keep if I rebuilt all of it. Summarizing everything up front feels productive and produces an archive. Summarizing the next one produces a course you finished.

Two years of pelicans on bicycles: 103 SVGs, 66 models, and what the guy who invented the benchmark says about it

Zhengxin — Thu, 17 Sep 2026 07:24:24 +0000

In October 2024, Simon Willison gave sixteen LLMs the same eight words:

Generate an SVG of a pelican riding a bicycle.

He has been running it on every new model since. Twenty-three months later there are 103 of these drawings scattered across dozens of his posts, and he has written a section explaining why you should not use his benchmark to compare models.

We pulled all of them into one page — pelicanzoo.ai — because reading them in order turns out to be a surprisingly good history of the last two years. This post is what we learned putting it together, and how the thing is built.

Everything here is Simon's work. The images, the commentary and the judgement calls are his; we mirrored and organised them, and every specimen links back to the post it came from.

The prompt is deliberately unfair

His stated reasons are mundane: he likes pelicans (he lives in Half Moon Bay, they're on the beach), and he was confident no SVG of a pelican on a bicycle existed in any training set.

The reasons it works are better. LLMs are text models that can't see, but they can write code, and SVG is code. So the task is to assemble a picture out of coordinates and radii with no feedback loop — the model never sees what it drew. Bicycles are hard for humans to draw from memory (try it: you'll get the frame wrong). And, in his words:

Pelicans can't ride bicycles. They don't have the right shape.

There's a bonus that matters more than it sounds: models leave comments in the SVG. , . You can read what it meant to draw and compare it against what came out. The gap is usually the joke.

2024: it's mostly shapes

The early attempts are bad in specific, funny ways. Claude 3.5 Sonnet produced two circles, a triangle, and a beak Simon described as a yellow banana smile. Llama 3.3 70B drew a small circle, a vertical line, and something shaped like a sink. Qwen2.5-Coder's bicycle is a pile of brown shapes that reads as a tractor. Mistral Small 3 delivered a squat white duck squatting on a barbell.

Then DeepSeek R1 landed in January 2025, and shortly afterwards Nvidia lost about $600bn in market cap. Simon later singled its pelican out as "the pelican that crashed the stock market" — the best one so far: a recognisable bicycle, a bird next to it that's arguably a pelican, not actually riding it.

For that first year the drawings tracked real capability fairly well. Models that drew better pelicans were better at writing code. A joke about how silly model comparisons are started behaving like a real benchmark.

The 560-match tournament that cost 18 cents

By June 2025 he had 34 pelicans and wanted a ranking without looking at 34 images himself.

So he had Claude write a tool that renders any two pelicans side by side and screenshots the pair. 34 images, every pairing, 560 matches. Each match went to GPT-4.1 mini with instructions to pick the better "pelican riding a bicycle" illustration and explain why. Elo scores out of the results.

Total judging cost: about 18 cents.

Winner was a Gemini 2.5 Pro preview; last place, Llama 3.3 70B. The judge's reasoning for that matchup: the left image clearly depicts a pelican riding a bicycle, the right is a few minimal shapes that don't read as anything.

The same talk includes the cost comparison that stuck with me. o1-pro: 88.755 cents for one pelican. Gemini 2.5 Pro: 4.77 cents. Gemini's was better.

The models start editorialising

August 2025, Simon runs Qwen3-4B-Thinking locally. It declines to draw a bicycle. It returns a blue circle with red text across it:

This is art - pelicans don't ride bikes!

He made that the headline of the post.

In November, Gemini 3 at low reasoning effort gave its pelican a little hat, with an SVG comment reading hat (optional fun detail). At high effort the frame geometry was finally correct.

He decided the task had gotten too easy and escalated: a California brown pelican, bicycle with spokes and a correct frame, large gular pouch, visible feather texture, unambiguously pedalling, in breeding plumage. He attached a photo he took himself.

Most models missed the detail that makes it a trick question — the California brown pelican isn't brown.

The laptop model that beat Opus

April 16, 2026: Qwen3.6-35B-A3B and Claude Opus 4.7 shipped the same day. Simon ran Qwen as a 20.9GB quantised model on his MacBook and Opus through the API.

He gave it to Qwen. Opus got the frame geometry wrong, and got it wrong again at maximum reasoning effort.

This result made him suspicious of his own benchmark. There's a persistent theory that labs train against his "stupid test", and he'd been keeping a spare prompt in reserve for exactly this moment. He burned it: a flamingo riding a unicycle.

Qwen's flamingo wears sunglasses and a bow tie, appears to be smoking, and is flanked by heart emoji and the caption "Flamingo on a Unicycle". The source comment says Give the flamingo sunglasses!. Opus drew a competent, entirely unremarkable flamingo. That one went to Qwen as well.

His own framing was careful: he has enormous respect for Qwen, and he does not believe a 21GB quantised model is more useful than Anthropic's latest flagship. But if the thing you want is an SVG of a pelican on a bicycle, the laptop won that day.

That's roughly where pelican quality and model capability stop tracking each other.

The inventor says don't use it

Kimi K3, July 2026. Its pelican burned 13,241 reasoning tokens and cost 25 cents. Simon used the post to write a section on what the benchmark is still good for.

His conclusion after 21 months: it was never a good benchmark. The correlation in year one was a surprise and it's basically gone now — GLM-5.2 draws a better pelican than GPT-5.6 or Claude Fable 5, and he doesn't think GLM is in that class. More importantly it tests nothing about what actually matters today, namely whether a model can hold a long conversation and call tools reliably. His words: don't use pelicans to compare models.

So why keep going? Two reasons, both practical:

It forces him to actually run each new model. Posting a pelican is proof he got the thing working, rather than just reading the launch post.
Even one prompt leaks information. On the Kimi K3 run he noticed his eight-word prompt was billed as 95 input tokens, and sending just "hi" cost 86 — implying about 85 tokens of hidden system prompt.

September 1, 2026: Claude Fable 5.1, across five reasoning levels. Low and medium barely think and finish in about twenty seconds. Maximum ran 13 minutes 54 seconds, emitted 65,927 tokens, cost $3.30, and produced a pelican in a blue cap with a fish in the basket. Best pelican he's seen from Anthropic.

The benchmark has become a ritual rather than a measurement. It won't tell you which model is strongest. One pelican's invoice and reasoning trace will still tell you a lot about how a model works, and whether it'll decide on its own to put a hat on your bird.

Building the zoo

The drawings live across two years of posts, which makes reading them in sequence tedious. So: one page, 103 specimens, 66 models, 12 vendors, October 2024 to now. Each one is tagged with model and date and links back to Simon's original post.

A few things that turned out to be more interesting than expected:

24 of them are still vector. Where the original SVG survives, the page serves the SVG — zoom in as far as you like, and four of them are animated (wheels turning, pelican bobbing). The rest exist only as screenshots from his conference slides, so they're labelled print rather than live. Making that distinction visible mattered more than we expected; a screenshot of an SVG and the SVG are not the same artifact, and the ones that are still code are the ones you can actually inspect.

The critic reads source, not pixels. There's a button under each specimen that asks a model to review the drawing — and it's given the SVG source, not an image. Half of that is cost. The other half is that it's funnier and more specific: it can complain that the body is an ellipse of radius 104, or that the rear wheel is out of proportion with the frame. Using models to review models closes a loop that probably shouldn't be closed.

Submissions have no backend. You can paste in an SVG a model drew for you. The page sanitises it in the browser, then generates a pre-filled GitHub pull request. No server, no database — one pelican is one file. It's a static site on Cloudflare.

The sanitiser is the part I'd actually defend in review. Model-generated SVG pasted in by strangers is untrusted markup, so it strips <script>, <foreignObject>, iframe/object/embed, inline on* handlers, javascript: URLs, @import, and any remote href/src/url() reference. Data URIs stay — they're self-contained. Remote references go because they leak the visitor's IP to whoever hosts them and let someone swap the picture out later.

Two design decisions in there I'd repeat:

// It reports what it removed instead of only returning a cleaned string.
// @returns {{ ok, svg, removed: string[], error }}

The same function runs in three places — the static build, the browser preview, and CI on incoming pull requests. Because the site strips before it builds the PR, a submission that still arrives dirty was hand-crafted, so CI stops it for a human to read rather than silently cleaning it. A sanitiser that returns a clean string and nothing else throws away the signal that someone was trying.

The other one is dull and bit us first:

// Percentages need something to be a percentage of; without a viewBox an SVG
// whose width/height we strip will stretch to fill whatever box it lands in.

We strip fixed width/height so specimens scale in a grid. Do that to an SVG with no viewBox and it stretches to fill its container. So the sanitiser synthesises one from the original dimensions when it's missing.

There's also a guessing game — you get a drawing and four model names, 73 rounds over 51 models. Distractors are picked from different vendors on purpose. Three Gemini variants side by side isn't difficult, it's just unfair. The 2024 ones are easy. The 2026 ones are basically a coin flip, which is its own kind of result.

Credit

The images and the original keeper's notes are Simon Willison's, collected from his posts, and the footer links back to his pelican-riding-a-bicycle tag. We built the cage, not the birds.

If you've got one that's especially good, or especially wrong, the submission box takes it.

pelicanzoo.ai

Sources

Pelicans on a bicycle (2024-10-25)
The last six months in LLMs, illustrated by pelicans on bicycles (2025-06-06)
Trying out Gemini 3 Pro with audio transcription and a new pelican benchmark (2025-11-18)
Qwen3.6-35B-A3B on my laptop drew me a better pelican than Claude Opus 4.7 (2026-04-16)
Kimi K3, and what we can still learn from the pelican benchmark (2026-07-16)
Claude Fable 5.1 made me a really nice animated pelican (2026-09-01)

Turning YouTube Videos Into Obsidian Notes — and What Shipping the Plugin Taught Me

Zhengxin — Mon, 14 Sep 2026 05:02:17 +0000

Every so often I'd watch a 90-minute conference talk, close the tab, and realise the only trace it left in my vault was a URL in a list called "watch later (again)".

So I built an Obsidian plugin that turns a video into an actual note. It's been in the community directory since September and is on 0.3.0 now. This is what it does, and — more usefully — the handful of decisions and review rules I'd want to know before building another one.

What lands in the vault

One command, one link, and you get a note:

a TL;DR callout and key insights
an embedded player at the top — timestamps seek it in place, without leaving the note
chapters as timestamped bullets
optional summary (several templates), quiz, and full transcript in a collapsed callout
frontmatter with title, source, channel, language and tags, shaped for Dataview

Plus a right-sidebar chat panel scoped to the note you're reading, and a command that turns the quiz into Spaced Repetition cards.

Now the parts that were actually decisions.

The plugin holds no model keys

An Obsidian plugin runs on the user's machine. You can't ship an API key in it, and asking every user to paste their own is both friction and a support queue you will personally staff forever.

So the plugin generates nothing. It sends a video link and an account token to a server, and writes down what comes back. That's the whole client.

The honest trade-off: this means the plugin needs an account, which is a real cost to the user and something I put in the README under a Before you install heading rather than burying. A plugin that silently requires a signup is a plugin that gets one-starred.

The connect handshake, and the one line that makes it safe

Settings → Connect opens the browser at /connect/obsidian?state=…&vault=…. You sign in, the server mints a token, and the page bounces you back via obsidian://svt-connect?token=…&state=….

The state is generated by the plugin and checked when the redirect comes home. Without that check, any web page could deep-link a token into your vault — the obsidian:// scheme is open to anyone. It's four lines of code and it's the difference between a handshake and a hole.

Server side the token is stored as a sha256 hash. Client side it lands in .obsidian/plugins/<id>/data.json, which is worth saying out loud in your docs: if the user syncs their vault, that file goes with it.

One note format, two producers

The website also has an Export → Obsidian button. That's two code paths producing "the same" Markdown, which in my experience drift apart within about a week.

So the Markdown is assembled in exactly one place — a server endpoint — and the plugin writes whatever it receives verbatim. The website button and the plugin produce identical notes because they are, literally, the same function call.

Re-running a command must not eat the user's writing

People add their own notes under the generated stuff. Refreshing a note has to be non-destructive or nobody will ever press it twice.

The generated region is fenced:

%% svt:start %%
…everything the server produced…
%% svt:end %%

## My notes
whatever you wrote, untouched

Refresh replaces only what's between the markers. Frontmatter is the subtler half: the server returns an ownedKeys list alongside the note, so the plugin overwrites the keys it owns and leaves every key you added alone. Writes go through vault.process rather than read-then-write, which is also what the community review expects.

`requestUrl` doesn't stream

Obsidian's requestUrl sidesteps CORS, which you want, because your plugin isn't an origin anyone will whitelist. What it doesn't do is stream.

My summary endpoint is server-sent events. So the plugin waits for the whole response and parses the event stream after the fact. You lose the progressive typewriter effect; you keep mobile support and never fight a preflight. Worth knowing before you architect around a stream that won't arrive.

Flashcards, and only appending

0.3.0 turns the quiz into a card note: multi-line format, the right answer and its explanation on the back, and a timestamp link to the moment the question came from.

Run it again after new questions appear and only the missing cards are appended. Existing cards, their  review schedules, and any cards you wrote yourself are never touched. Rewriting a review schedule is the fastest way to lose a user who has been reviewing for six months.

What the community directory review actually checks

Submitting is no longer a PR against obsidian-releases. You log in at community.obsidian.md, link GitHub, and an automated reviewer runs. Mine came back with a list. The useful items:

No inline styles. Anything you'd reach for as el.style.foo = bar belongs in styles.css. My auto-growing textarea became the CSS field-sizing: content instead of a resize handler, which is a better implementation anyway.
Settings must use the declarative 1.13 API (getSettingDefinitions() with groups, getControlValue / setControlValue). That forced minAppVersion up to 1.13.0, because the no-unsupported-api rule rejects 1.13 APIs while you claim to support older versions. Pick a lane; you can't straddle.
Attest your build. actions/attest-build-provenance in the release workflow, with id-token and attestations write permissions. gh attestation verify main.js --owner <you> exiting 0 with no output is what success looks like.
The tag must match the manifest version, and npm version writes tags with a v prefix that Obsidian doesn't want. git tag -d v0.2.2 && git tag 0.2.2.

One false alarm worth pre-empting: right after I re-cut a release, the checker insisted "No release matches your manifest version." It had scanned during the draft window and cached that. Re-scan, it passes. Don't go rewriting your workflow like I nearly did.

Three Obsidian CSS facts that cost me an evening

.view-content ships with padding: 12px 12px 32px. If your custom view's layout looks mysteriously inset, that's why. Zero it with a same-specificity selector: .workspace-leaf-content[data-type="…"] .view-content.your-class.
On desktop the status bar is position: fixed, 27px tall, and floats over the bottom of the right sidebar. Leave it room or your input box is permanently half-covered.
button:not(.clickable-icon) picks up Obsidian's background and shadow. For a text link, use an <a>.

Links

Plugin: community.obsidian.md/plugins/summarize-video-to-text
Source (MIT): github.com/diaozxin007/obsidian-summarize-video-to-text
Setup walkthrough: summarizevideototext.com/obsidian-plugin

If you're building something that writes into other people's vaults, the markers-and-ownedKeys pattern is the piece I'd steal. Everything else was replaceable; that one is what makes a destructive command safe to press twice.

Claude Code Agent Loop Deep Dive (0): From the Chat Window to the Loop

Zhengxin — Wed, 09 Sep 2026 02:50:21 +0000

Open Claude Code, type “Help me investigate this bug,” and press Enter.

The window starts scrolling. Claude reads auth.py, then login.py, runs a search, edits one line, runs a test, and finally says: “Done—the cause was X.”

It feels like a conversation with something that remembers what was said, can use tools, and waits for you when it needs input.

But an LLM API is stateless. Each request is independent; the server does not remember your previous prompt. To make the model appear to remember a conversation, the application must send the full message history again on every call.

That creates an intermediate layer: the harness. It retains the history and packages it every time it calls the LLM. What looks like a continuous chat is closer to this:

Turn 1: harness sends [1 message] → LLM returns a response
Turn 2: harness sends [3 messages] → LLM returns a response
Turn 3: harness sends [5 messages] → LLM returns a response
...

The message array only grows. The LLM remembers nothing; the harness remembers everything.

One user message, how many model calls?

Consider the bug fix above. Claude read two files, searched the codebase, made an edit, and ran a test: five tool calls. After each tool completes, the harness puts its tool_result back into messages and calls the LLM again so it can decide the next action.

One user message can therefore mean five to ten LLM calls:

User presses Enter
  → Call A: “I should read this file”
  → harness reads the file
  → Call B: “I should inspect another file”
  → ...
  → a response with no tool request

Only then does the user-visible turn finish.

That is the loop.

The minimal tool-use loop is deceptively small:

while True:
    response = call_llm(messages)
    if response.has_tool_use:
        results = execute_tools(response.tool_use)
        messages.append(response)
        messages.append(results)
    else:
        break

In plain language:

while True: keep going until something explicitly ends the turn.
call_llm(messages): send the complete current history and get the next response.
has_tool_use: check whether the model asked to use tools.
execute_tools plus two appends: run the requested tools, then retain both the model’s request and the result.
break: if there is no tool request, the turn is over.

The core is only five actions: call the model, inspect the response, execute tools when requested, append the results, and stop when no more tools are needed.

The user is only at the beginning and the end

In this loop, the user appears at two points: pressing Enter at the start and seeing the final answer at the end. The middle—model call, tool execution, result append, and next model call—runs automatically. The harness does not ask the user to approve each ordinary step.

This is the deepest difference between a chatbot and an agent. A chatbot normally waits for a person every turn. An agent waits for a person only at the boundaries; it drives itself through the middle of the task.

That self-driving property makes several mechanisms necessary:

Interrupts: a user needs a way to stop a loop that will otherwise keep running.
Permission approval: dangerous actions, such as destructive shell commands, must be able to pause the loop.
A maxTurns circuit breaker: an accidental loop needs a hard ceiling.
Hooks: custom logic must be inserted through lifecycle hooks because the user is not manually operating the intermediate steps.

Without automatic iteration, none of these would be particularly important.

The five-line happy path is not the product

The toy loop assumes everything works. A real product must handle a much harsher world:

the context window fills up;
the API fails due to a network problem, rate limit, or overload;
the model refuses a request;
the user interrupts while a tool is running;
a tool crashes;
output reaches max_tokens and is cut off;
output is too long, requiring a fallback model or recovery path;
several tool uses may need parallel or serialized execution;
the user sends another message mid-turn, so it must be queued;
hooks in .claude/settings.json must run at session and tool boundaries;
a first-use permission prompt blocks the loop until the UI answers;
a subagent starts its own loop while remaining distinct from the main one.

Every item is outside the five-line example.

From a loop to an agent runtime

Claude Code weaves these cases into its main loop. Conceptually it looks more like this:

while (true) {
    choose a route from state.transition.reason:
        next_turn                    → normal LLM call
        collapse_drain_retry         → context collapse
        reactive_compact_retry       → compact and retry
        max_output_tokens_escalate   → increase the token ceiling
        max_output_tokens_recovery   → inject a “continue” message
        stop_hook_blocking           → a stop hook requires continuation
        token_budget_continuation    → continue under a token budget

    call the LLM and process its stream

    handle stop_reason:
        end_turn                     → complete when there is no tool use
        tool_use                     → runTools
        max_tokens                   → output-token recovery
        refusal                      → explain how to change model settings
        context_window_exceeded      → reactive compaction

    execute tools:
        batch by isConcurrencySafe for parallel or serial execution
        convert every tool failure into an is_error tool_result
        optionally start tools while streaming JSON is still being parsed

    append tool results to messages

    check terminal conditions:
        AbortController.aborted      → aborted_tools
        turnCount > maxTurns         → max_turns
        PostToolUse hook blocks      → hook_stopped
        auto-compact threshold       → compact
        prompt_too_long              → withhold and recover

    continue to the next iteration
}

The simple loop has not disappeared. It is still the heart of the system. The production runtime wraps it with recovery paths, safety gates, queueing, streaming, concurrency control, lifecycle hooks, and context management.

What this series will examine

This series studies those pieces one by one: how history is retained, how state transitions choose a path, how tools are executed and scheduled, how context is compacted, how approval and interrupts work, and how subagents reuse the same machinery.

The key idea to keep in mind is simple: Claude Code is not a chat UI with a few tools attached. It is a harness that repeatedly runs an LLM, observes whether it wants an action, performs that action, and feeds the result back into the next decision. Everything else in the product exists to make that loop reliable in the real world.

Claude Code Tools Deep Dive (14): The Background Mechanism

Zhengxin — Tue, 08 Sep 2026 04:15:34 +0000

This is the fourteenth article in my Claude Code tools series. The first thirteen articles took tools apart one by one. This article is different: it examines a cross-tool, orthogonal capability—the Background mechanism.

This series begins with a prerequisite article explaining what tools are and how Claude uses them. Here I apply the same four lenses—naming, tool descriptions, field descriptions, and schema—to a capability distributed across several tools.

Why Background deserves its own article

There is no tool literally named Background in Claude Code. That is a design choice, not an omission. Background behavior is spread across the ecosystem:

Location	Form
Bash `run_in_background: true`	Parameter
Agent `run_in_background: true`	Parameter
Monitor	A tool whose purpose is continuous background listening
CronCreate	A future, background trigger
TaskStop	A tool for stopping background work
TaskOutput	Explicit output retrieval (now deprecated)
`<task-notification>`	Completion notification

Looking at only one of these reveals only a fragment. Together they form one system.

Background is an execution mode, not a behavior

Every ordinary tool has a core behavior: Read reads a file, Bash runs a command, and Agent delegates to another Claude. Background is not another behavior. It is a mode of execution.

The same Bash or Agent action can run in two modes:

Synchronous (default): call → block → receive the result → continue the conversation.
Background (run_in_background: true): call → return a task ID immediately → the main Claude continues → the harness sends a notification when the work completes.

Making Background a family of separate tools (BackgroundBash, BackgroundAgent, and so on) would double the tool count and the decision burden. Claude Code instead parameterizes the existing behavior. This is the same orthogonal design used by Grep’s output_mode and Edit’s replace_all: keep the behavior fixed and switch the mode with a field.

The analogy to Unix is useful. fork() creates a child process, the task ID acts like a PID, and <task-notification> resembles SIGCHLD. Claude Code has built a process-management system at the harness layer, except a child may be a shell process, another Claude, or a WebSocket connection.

One task-ID system

Background Bash, background Agent, Cron jobs, and Monitor instances all receive a handle that the harness can track:

Bash(command: "long-training.py", run_in_background: true) → task_id
Agent(prompt: "...", run_in_background: true) → task_id
CronCreate(cron: "*/5 * * * *", recurring: true, prompt: "...") → job_id
Monitor(command: "tail -f log | grep ERROR", persistent: true) → monitor_id

All can be stopped through the same TaskStop interface. The notifications differ by type:

Bash completion includes an output-file path.
Agent completion includes the agent’s result.
Cron fires a new turn using its prompt.
Monitor turns each stdout line or WebSocket event into a message.

The interface is unified while the semantics remain specialized. That is good API design.

Three kinds of background work

Type A: a one-shot task with a known end

Examples: background Bash and background Agent.

The task starts now, ends later, and the harness sends one <task-notification> when it finishes. Typical uses include a long test, build, training run, research subagent, or dependency installation.

Bash(command: "...", run_in_background: true) → task_id
    (conversation continues)
[task-notification: completed, output: /tmp/.../out.log]
Read("/tmp/.../out.log")

Type B: trigger at a future time

Example: CronCreate.

The job has not started yet. CronCreate records a prompt and a schedule; when the time arrives, the runtime starts a new turn with that prompt. This is useful for a reminder, a check five minutes from now, or tomorrow’s morning self-check.

That is the key distinction: Type A is an already-running task waiting to finish; Type B is a not-yet-started task waiting for its trigger.

Type C: continuous or long-lived listening

Example: Monitor, especially persistent: true.

The listener starts now, has no fixed end (or ends at timeout, stream close, or an explicit stop), and sends a notification for every event. Typical uses are following errors in a log, watching filesystem changes, subscribing to a WebSocket, or following a PR until merge.

Dimension	One-shot task	Scheduled trigger	Continuous listener
Notifications	One on completion	N fires	Unbounded, one per event
Lifecycle	Started, then finishes	Not started, waiting	Started, stream continues
Interface	Bash / Agent	CronCreate	Monitor
Stop	Natural completion or TaskStop	CronDelete	TaskStop

The anti-polling principle

Background should create a simple intuition:

When the harness can notify you, do not sleep. When a task is already in the background, do not synchronously wait for it.

Do not start a background task, sleep for a minute, and then read its output. The harness will notify you; keep working and read the output after the notification.

Do not repeatedly curl a CI endpoint followed by sleep 60. Choose the primitive that matches the semantics:

a command that eventually exits → Bash run_in_background with an until loop;
a stream of events → Monitor;
one check at a known time → CronCreate.

Claude Code also warns that long leading sleep commands are blocked. This is a hard system constraint, not merely advice. The tool layer actively pushes Claude toward asynchronous thinking.

Task ID, Job ID, and Task (the to-do item)

The word “task” is overloaded:

Name	System	Meaning
Task (`TaskCreate`, `TaskList`, …)	Task family	A conceptual to-do item
`task_id` / `<task-notification>`	Background	A running task instance
ID returned by CronCreate	Cron family	A scheduled job

Task-family tasks may not have started. Background tasks are concrete running processes or listeners. TaskStop and the former TaskOutput control the latter, not the to-do list. A useful memory aid is that TaskCreate/TaskList/TaskGet/TaskUpdate feel like CRUD, while TaskStop is runtime control.

A concurrent workflow

Imagine the user wants to start three things at once: run a 15-minute test suite, ask a subagent to research the auth architecture, and start a dev server while watching its log.

Bash(command: "pnpm test:all", run_in_background: true) → task_test
Agent(prompt: "research auth architecture", run_in_background: true) → task_auth
Bash(command: "pnpm dev", run_in_background: true) → task_dev
Monitor(
  command: "tail -f /tmp/dev.log | grep -E --line-buffered 'error|warn'",
  description: "dev server errors"
) → monitor_dev

Multiple tool calls in one message start concurrently. The main Claude remains available for conversation. The test completion produces a task notification; the research completion produces another; a dev-log error arrives immediately through Monitor; and TaskStop(task_dev) stops the server. Traditional REPL execution would serialize these tasks. Background turns them into parallel work, with the longest task determining the total elapsed time.

Boundaries

Background is not unlimited:

Session-only: jobs die when the session ends. Use system cron, launchd, GitHub Actions, or a cloud scheduler for multi-day work.
Notifications wait for idle: a task notification does not interrupt Claude while it is processing a user turn; it queues until the REPL is idle.
Rate limiting: high-volume Monitor streams and accumulated output can be stopped or truncated. Strong filters are essential.
Concurrency limits: Bash and Agent jobs are queued beyond the runtime’s host-dependent limit (typically min(16, cpu-2)).
Sandboxing remains active: background execution does not bypass the sandbox. A separate, explicit dangerous-sandbox option is required to change that boundary.

The four-layer design signal

Naming

The most important naming decision is the absence of BackgroundBash or BackgroundAgent. One Boolean, run_in_background, declares that Background is an execution mode, not a new behavior.

TaskStop is also deliberately generic. Stopping a background Bash task is not BashStop; stopping an Agent is not AgentStop. The single verb resembles kill <pid>: whatever was forked, the same control operation stops it.

The old TaskOutput has been de-emphasized in favor of reading the output file with Read. If an existing primitive covers the capability, the API does not add another verb. Cron and Monitor keep their specialized names externally while sharing the task infrastructure internally.

Tool-level descriptions

Descriptions carry most of the normative guidance:

avoid unnecessary sleep and polling;
use background Bash for one-shot waiting;
use Monitor for streaming events;
strong filters are required because every event costs conversation context;
Cron jobs are session-only, not system cron jobs.

“Long leading sleep commands are blocked” upgrades a recommendation into an enforced constraint. Monitor’s warnings about buffering, rate limits, and raw logs do the same for event streams. These descriptions are cross-tool contracts encoded in individual tools.

Field-level descriptions

The most visible design signal is that Bash and Agent use the same field with opposite defaults:

Tool	Default	Typical intent
Bash	`false`	Most shell commands are short; synchronous is simpler
Agent	`true`	Subagents usually take time; keep the main Claude free

Bash’s field description says to use background only when the result is not needed immediately, promises a later notification, and warns not to append &. Agent’s description explains when to opt out and run in the foreground. The same field is a mirror: the defaults reflect the typical lifecycle of each tool.

The output path in <task-notification> naturally directs Claude to Read the result. Monitor’s persistent Boolean distinguishes a bounded listener from a session-long listener.

Schema validation

Background has a thin schema layer because it modifies existing synchronous behavior rather than replacing it. The important safeguards are runtime-level: Monitor’s one-hour timeout, persistent semantics, cron-expression validation, unified task IDs, concurrency limits, and sandbox enforcement.

The thinness is evidence for the central design choice. If Background were a new capability, it would need an independent schema. Because it is a mode, the existing command, prompt, and cron schemas are mostly enough; Background adds a flag or a trigger policy.

Relationship to neighboring tools

Tool family	Background expression	Default	Role
Bash	`run_in_background: false`	Foreground	Long commands without blocking the main loop
Agent	`run_in_background: true`	Background	Subagents normally have a long lifecycle
Task family	IDs, TaskStop	N/A	State and a stop interface
Cron family	Time-driven wakeups	Scheduled	Time primitive
Monitor	Event-driven wakeups	Event stream	Event primitive

The anti-polling principle connects Bash, Agent, and Monitor: do not poll a job that will notify, do not schedule checks for an Agent that is already running, and do not use a continuous tail -f for a one-shot event.

The first thirteen tools are mostly synchronous: Read, Edit, Write, Grep, Glob, WebFetch, WebSearch, the interaction tools, and so on. Background is the hidden implementation layer that lets those spatial primitives extend into asynchronous collaboration.

Conclusion: the invisible skeleton

Background’s elegance is not simply that it makes AI asynchronous. It is that every layer reinforces parameterization instead of tool proliferation:

Naming: no independent tool, just run_in_background and a unified TaskStop.
Tool descriptions: anti-polling, filter-first, session-only, and notification contracts are distributed across the relevant tools.
Fields: Bash and Agent have opposite defaults because their normal lifecycles differ.
Schema: deliberately thin, with timeout, persistence, concurrency, and sandbox safeguards as the backstop.

The missing schema is itself evidence. Background is not a new action; it is a mode attached to existing actions. Without it, Claude Code would be a one-action-at-a-time assistant. With it, Claude becomes a multi-threaded collaborator that can run long jobs, keep talking, react to events, and schedule future work.

The series now closes with a complete map: user alignment → locating → perceiving → executing → fallback → scaling through subagents, time, event streams, and background execution. The goal was never to enumerate tools, but to apply the same four-layer anatomy to each one. The reusable lesson is restraint: each tool does one small thing, and composition creates the collaboration system.

Claude Code Tools Deep Dive (13): Monitor

Zhengxin — Tue, 01 Sep 2026 07:23:28 +0000

This is the thirteenth article in my Claude Code tools series. The previous article, The Cron Family, explained how Claude can trigger actions across time. Cron is clock-driven: it fires at a scheduled moment, regardless of what is happening outside.

Engineering has another kind of waiting: wait until something happens, without knowing exactly when. For example:

“Tell me when ERROR appears in the logs.”
“Rebuild when the file changes.”
“Notify me when the PR status changes.”
“Report each CI check as it settles.”

These cases need an event-driven asynchronous waiting primitive. Claude places a set of sensors, and the runtime reports external events automatically. That is the purpose of Monitor.

Monitor

Monitor is Claude Code’s built-in event-stream listener. Together with Bash background execution and Cron, it completes the three basic asynchronous waiting primitives:

Tool	Trigger	Meaning
Bash `run_in_background`	One task completes	“Tell me when the build is done.”
CronCreate	A clock reaches a time	“Remind me at 9.”
Monitor	An event stream, one stdout line per event	“Tell me every time X happens.”

The first two wait for one point. Monitor waits for a line: the stream may continue indefinitely, until a timeout or Claude stops it.

What it solves

Monitor answers the question: how can Claude continuously perceive changes in the outside world?

More than one notification: Bash background execution normally reports once; Monitor reports every event.
Event-stream modeling: each stdout line is a notification, naturally aligned with Unix conventions.
Two data sources: a shell command or a direct WebSocket connection.
Forces filter design: the prompt makes Claude decide what deserves a notification and what should be ignored.
Persistent listening: persistent: true can keep a monitor alive for the whole session, useful for PRs and long-running logs.

Its fundamental difference from Cron is simple:

Cron is clock-driven: time is the active party.
Monitor is event-driven: the outside event is the active party.

Cron says “I will ask you when the time comes.” Monitor says “call me when something happens.” One is pull; the other is push.

A concrete example

Suppose the user says: “I am starting a 20-minute model training run. Watch the log, tell me about errors immediately, and report progress too.” This is a long-running job whose events occur at unknown times.

Bad alternative 1: sleep and inspect later

Bash(command: "sleep 1200 && cat train.log", timeout: 1300000)

If the process fails after three minutes, Claude does not know until the end. Early signals are lost.

Bad alternative 2: scheduled polling

CronCreate(cron: "*/2 * * * *", recurring: true, prompt: "check train.log and report ERROR")

Polling every two minutes introduces up to two minutes of latency and repeatedly rereads the file. Each Cron wakeup also consumes conversation context.

Bad alternative 3: a background `tail`

Bash(command: "tail -f train.log", run_in_background: true)

A background Bash job normally notifies once, when it exits. tail -f never exits, so it never sends the useful notifications.

The Monitor solution

Monitor(
  command: "tail -f train.log | grep -E --line-buffered 'elapsed_steps=|Traceback|Error|FAILED|Killed|OOM'",
  description: "training log: progress and errors",
  timeout_ms: 1500000
)

The runtime starts the shell command and follows the log. grep lets only matching lines through. Each stdout line becomes a notification delivered to the conversation immediately. Claude can continue talking or do other work, while progress and failures arrive automatically. After 20 minutes the timeout ends the monitor, or the user can stop it earlier.

The key insight is that Monitor turns Claude from an active poller into a passive receiver. Every relevant external event is known immediately, without repeated polling or a blocked context.

Two data sources: command or WebSocket

Monitor has an unusually rich design: the source can be a shell command or a WebSocket.

Shell command is the common mode. Every line written to stdout is an event.

WebSocket can be used directly:

Monitor(
  ws: { url: "wss://events.example.com/stream", protocols: ["v1"] },
  description: "deployment event stream",
  timeout_ms: 300000
)

The runtime opens the connection; every text frame is one event, while a binary frame is represented as [binary frame, N bytes]. Closing the connection ends the monitor.

Using websocat through command would work, but adds quoting, process, installation, and buffering problems. Built-in WebSocket support removes a process and normalizes the mapping from frames to events. It is a strong example of using a tool to eliminate fragile plumbing, and suggests concrete use cases such as agent-to-agent communication, deployment subscriptions, and long-lived push channels.

When to use Monitor

The tool prompt gives a useful selection rule:

Use Monitor when:

every occurrence of X should generate a notification;
every occurrence should be reported until a known terminal condition;
you need to consume a WebSocket event stream.

Do not use Monitor when:

you only need one completion notification: use Bash run_in_background with a loop that eventually exits;
you need a clock trigger: use CronCreate;
events arrive at a very high rate: tighten the filter, because rate limiting may stop the monitor.

The important warning is: “Don’t use an unbounded command for a single notification.” For “tell me once when the build is ready,” use a background Bash command such as until grep -q "Ready" dev.log; do sleep 0.5; done. Do not use tail -f ... | grep -m 1 "Ready": tail -f may remain alive after the match, leaving Monitor attached until timeout. Monitor is optimized for continuous events, not one-shot completion.

Technical design

Naming

Monitor is a neutral SRE term for continuous observation and alerting. It is broader than Watch, Tail, Subscribe, or Listen, and steers Claude toward “place a watch and report events,” not “grep the file once.”

The tool-level description is a mini operations guide

The prompt covers notification choice, event-stream semantics, output volume, buffering, data-source preference, and observability completeness.

It explicitly says that each stdout line is an event, then classifies tools by notification count:

One notification: Bash with run_in_background.
One per occurrence indefinitely: Monitor with an unbounded command.
One per occurrence until a known end: Monitor with a command that emits lines and exits.

It also teaches Unix buffering. Every pipeline stage must flush per line: use grep --line-buffered and awk with fflush(). Avoid head, which may wait for N matches before producing output. This tribal sysadmin knowledge is placed directly in the tool prompt so a naïve command does not make events appear delayed.

The deepest rule is “silence is not success.” A filter must match every terminal state, not only the happy path. A monitor that watches only elapsed_steps= stays silent through a crash, hang, or unexpected exit, making failure indistinguishable from “still running.” Before arming a monitor, ask: if the process crashed right now, would my filter emit anything? If not, widen it to include Traceback, Error, FAILED, Killed, OOM, and similar signals.

“Selective” also does not mean “only good news.” Select the lines you would act on, whether they describe progress or failure. If output becomes excessive, the runtime automatically stops the monitor; Claude should restart it with a tighter filter. Lines arriving within 200 ms are batched into one notification, so a multiline traceback remains readable as one event.

Finally, the prompt prefers the native ws source over command: 'websocat wss://…', avoiding an extra process and another buffering layer.

Fields and runtime rules

Monitor has five fields:

Field	Meaning
`command`	Shell source; mutually exclusive with `ws`
`ws`	WebSocket source with `url` and `protocols`
`description`	Required label shown with every notification
`timeout_ms`	Defaults to 300,000 ms; maximum 3,600,000 ms
`persistent`	Defaults to false; true keeps it alive for the session

The schema is moderate, but important constraints live in the runtime:

Exactly one of command and ws must be supplied.
description is required because it is visible in every notification.
A non-persistent monitor cannot exceed the one-hour timeout.
Excessive output triggers rate limiting and an explicit stop.
With persistent: true, timeout_ms is ignored; the monitor ends with the session or an explicit TaskStop.

These are loud failures or loud stops. A bad monitor cannot silently look healthy while doing nothing.

Division of responsibility

Dimension	Bash background	CronCreate	Monitor
Waits for	One task to finish	A clock time	An event stream
Notifications	One on process exit	One per schedule match	One per event
Wakeup	Process exit	Scheduled moment	stdout line or WebSocket frame
Sources	Shell command	Cron expression	Command or WebSocket
Typical use	“Wait for CI”	“Check every five minutes”	“Alert on every log error”
Conservative bias	Notify on exit	Fire at the time	Emit only actionable signals

Monitor completes the waiting model begun by the first twelve tools. Bash waits for a point, Cron waits for a time, and Monitor waits for a line. Compared with Tasks, Task state is pulled by Claude from storage; Monitor state is pushed from the outside world. Compared with Bash polling, Monitor upgrades sleep + poll into a structured event-stream primitive.

Summary

Monitor’s most impressive feature is not merely continuous listening. It embeds an observability methodology in the tool description:

a minimal SRE-oriented name;
a long prompt explaining notification choice, buffering, rate limiting, batching, and “silence is not success”;
only five fields, each backed by a meaningful runtime decision;
hard runtime protection for source selection, timeouts, and output volume.

The schema locks down the basic shape, while the prompt teaches Claude how to build a reliable watch: event-driven, failure-visible, resistant to conversation flooding, and available over both shell and WebSocket sources.

The next article examines Background mechanisms, the final article in the series. It crosses tool boundaries and follows run_in_background through Bash, Agent, the Task family, and Monitor, showing how asynchronous execution becomes a first-class Claude Code semantic.

Claude Code Tools Deep Dive (12): The Cron Family

Zhengxin — Wed, 26 Aug 2026 11:26:04 +0000

This is the twelfth article in my series on Claude Code tools. The first eleven explored Claude Code’s spatial toolkit: from the local filesystem to the public web, from one Claude to multiple Claudes, and from immediate actions to persistent task lists. Their temporal model is fundamentally synchronous: Claude calls a tool, it executes, and a result returns immediately.

Real engineering has another class of requests:

“Remind me to check CI in 30 minutes.”
“Check every five minutes whether the deployment is ready.”
“Run a morning self-check at 9 tomorrow.”
“In an hour, review this proposal again.”

The common feature is that the action is not “do it now.” It is “automatically trigger it at a future time.”

That requires a time primitive. Claude Code’s answer is the Cron family: three tools—CronCreate, CronDelete, and CronList—that form a scheduled-execution system.

This series begins with a prerequisite article explaining what tools are and how Claude uses them. Like the other articles, this one follows the four-layer framework introduced there.

The Cron family: CronCreate / CronDelete / CronList

Like the Task family, these three tools are semantically coupled and share one data model: the session’s list of cron jobs. They are clearer as a family than as isolated operations.

Family overview

Tool	Responsibility
CronCreate	Create a future prompt trigger using standard five-field cron syntax
CronDelete	Cancel a scheduled job
CronList	List all jobs scheduled in the current session

A related tool: ScheduleWakeup is a specialized cousin used by the /loop skill to schedule its next self-wakeup. It is optimized for dynamic loops and is worth mentioning alongside Cron.

The core division is:

CronCreate is the engine. Most calls create jobs.
CronList and CronDelete are management tools. They inspect and clean up.

The biggest difference from Tasks is this: Task records work that remains to be done; Cron schedules an action for the future. Task waits for Claude to choose the next item. Cron triggers automatically when the time arrives.

What it does

The Cron family solves how Claude can execute actions across time:

Break synchronous limits: Claude can schedule a future self-wakeup rather than only respond to the current request.
Schedule precisely: standard cron syntax (M H DoM Mon DoW) supports arbitrary times and periods.
Support one-shot and recurring modes: a recurring boolean selects the lifecycle.
Provide lightweight reminders: “remind me in 30 minutes” does not require a background task.
Proactively observe external state: Claude can check CI or a deployment at a scheduled time.

This is the first tool family that crosses time. The previous eleven tools are actions at a point: a tool call happens and finishes. Cron is a schedule on a timeline: mark a point, then let the runtime fire automatically.

A concrete example

Scenario: The user says, “I just pushed a deployment. It should finish in about eight minutes. Check the CI status then and tell me if anything is wrong.”

This is a classic “wait for external state to change” task.

Bad alternative 1: sleep

Bash(command: "sleep 480 && gh run list", timeout: 500000)

The main Claude is blocked for eight minutes and cannot answer another question. Synchronous waiting wastes conversational time.

Bad alternative 2: poll every minute

while true:
    Bash(command: "gh run list")
    sleep 60

This consumes context once per minute. Eight minutes means eight calls, and logs fill the main context. The context budget is spent on waiting.

How CronCreate solves it

Claude schedules a one-shot wakeup eight minutes in the future:

CronCreate(
  cron: "13 22 29 7 *",           # one trigger at 22:13 on July 29
  recurring: false,
  prompt: "Check CI with gh run list. Tell the user if it failed; otherwise confirm briefly."
)

At runtime:

the job is stored in session memory
the main Claude immediately returns to the user instead of blocking
the user can ask other questions or start other work
at 22:13, the runtime invokes the prompt as a new Claude call
Claude runs gh run list and reports the status

The experience looks like:

[22:05] User: I pushed a deployment; check CI in eight minutes.
[22:05] Claude: Done—I scheduled an automatic check for 22:13.
              You can keep working in the meantime.
[22:05–22:12] User: continues with other work
[22:13] Claude: CI check complete; all three workflows are green.

Key insight: CronCreate moves the responsibility for waiting from the main Claude to the runtime. Claude schedules the work and gets out of the way, consuming neither conversation time nor context while waiting.

Combining the tools: inspect or cancel

If the user changes their mind—“Never mind, I’ll check CI myself”—Claude can call:

CronList()                         # find the job ID
CronDelete(id: "cron_xxx")        # cancel it

If the user asks “What did you schedule?”, CronList provides the answer.

Proactive vs. passive wakeups

Cron supports two modes.

One-shot (recurring: false) is for known moments:

remind me to review this PR tomorrow at 9
check CI again in 30 minutes
remind me to eat lunch at noon

The minute, hour, day-of-month, and month are pinned. The job fires once and disappears.

Recurring (recurring: true) is for monitoring with no known end:

check CI every five minutes until I say stop
inspect queue length every hour
run a morning self-check every day

Typical expressions include */5 * * * *, 0 * * * *, and 0 9 * * *. Recurring jobs live for at most seven days, fire one final time, then are deleted. This prevents forgotten jobs from consuming resources indefinitely.

When it is triggered

Use Cron for:

waiting for an external asynchronous event such as CI or deployment
reminders and actions at a known time
periodic monitoring every N minutes
handing a future check back to Claude after the current conversation ends

Do not use Cron for:

second- or subsecond-level actions; cron has minute resolution
exact event-driven responses; use Monitor
waits already covered by harness notifications, such as completion of a background Bash task or subagent
persistent jobs across sessions; Cron is session-only, stored in memory and gone when Claude exits

Choose among the waiting primitives by meaning:

Need	Primitive
One-shot event notification, such as CI completion	Bash `run_in_background` with harness notification
Listening for a change with no fixed time	Monitor
A reminder or one-time delay	CronCreate with `recurring: false`
Periodic monitoring	CronCreate with `recurring: true`
`/loop` self-wakeup	ScheduleWakeup

Cron is not the only way to wait. The right primitive depends on whether the trigger is a completion event, a change event, a clock time, or a recurring interval.

Technical design

1. Naming

CronCreate / CronDelete / CronList

This is another complete dual loop: Create attaches a job, Delete removes it, and List observes it. A scheduled job has a lifecycle—created, active, expired or cancelled—so observation and cancellation deserve first-class operations.

“Cron” reuses forty years of Unix crontab convention rather than inventing a DSL. Anyone who has used crontab -e on Linux or macOS already understands the idea and much of the syntax. Reusing an industry convention reduces cognitive load. List is plural rather than Get, signaling that multiple jobs may be returned.

2. Tool-level descriptions

Cron’s descriptions cover eight concerns: session-only lifetime, the seven-day cap, load spreading away from :00 and :30, exceptions where exact half-hours are correct, when to use Monitor instead, language signals for one-shot versus recurring jobs, local-time semantics, and transparent jitter.

State the session-only lifetime first

Jobs live only in this Claude session—nothing is written to disk, and the job is gone when Claude exits.

This prevents Claude from promising a weekly job that cannot survive the session. The simplified design avoids the complexity of user authorization, multi-session synchronization, and durable-job failure handling. The tradeoff is that long-lived jobs belong in system cron or a cloud scheduler, not this family.

Explain the seven-day cap proactively

Recurring tasks auto-expire after seven days—they fire one final time, then are deleted. This bounds session lifetime. Tell the user about the seven-day limit when scheduling recurring jobs.

Claude must tell the user about this limit when creating a recurring job. The cap is also an anti-forgetting mechanism: a forgotten hourly monitor cannot consume resources forever.

Spread load by avoiding :00 and :30

Every user who asks for “9am” gets 0 9, and every user who asks for “hourly” gets 0 *, which means requests from across the planet land on the API at the same instant. When the user’s request is approximate, pick a minute that is NOT 0 or 30.

This is a rare case where a tool prompt includes a server-operations concern. If every “9am” becomes 9:00, requests from every timezone create a synchronized load spike. Choosing :03 or :57 spreads the fleet.

The prompt explains the reason, not just the rule, so Claude can reason about exceptions.

Explain when :00 and :30 are correct

Only use minute 0 or 30 when the user names that exact time and clearly means it, such as “at 9:00 sharp,” “at half past,” or coordinating with a meeting. When in doubt, nudge a few minutes early or late—the user will not notice, and the fleet will.

The exception prevents the load-spreading rule from becoming dogma. Exact meeting coordination remains exact.

Point live watching to Monitor

Not for live watching. CronCreate reruns a prompt at fixed wall-clock intervals. To watch a log file, process, or command output and be notified the moment something changes, use Monitor instead—Monitor streams events as they happen; cron polls on a schedule.

The tool explicitly points to its sibling rather than expecting Claude to compare tools unaided. Cron is scheduled polling; Monitor is event streaming.

Infer one-shot jobs from user language

For “remind me at X” or “at , do Y” requests—fire once, then auto-delete. Pin minute, hour, day-of-month, and month to specific values.

The wording itself signals recurring: false, so Claude need not ask the user whether a reminder should repeat.

Use local time, not UTC conversion

Uses standard five-field cron in the user’s local timezone: minute, hour, day-of-month, month, day-of-week. 0 9 * * * means 9am local—no timezone conversion needed.

This avoids a classic sysadmin mistake: manually converting a user’s local time to UTC and getting it wrong.

Make jitter transparent

The scheduler adds a small deterministic jitter on top of whatever you pick.

Claude is told that a job chosen for :57 might fire at :58. Recurring tasks may be delayed by up to 10%, capped at 15 minutes; one-shot tasks scheduled exactly at :00 or :30 may fire up to 90 seconds early. The runtime spreads load even when Claude chooses a round time.

Fire only while the REPL is idle

Jobs only fire while the REPL is idle, not mid-query.

If a cron job becomes due while Claude is processing a user request, it waits until the current response finishes. A scheduled trigger cannot interrupt the user’s active thought.

3. Field-level descriptions

CronCreate exposes:

cron: five fields in the user’s local timezone—minute hour day-of-month month day-of-week
prompt: the prompt to invoke at the scheduled time
recurring: boolean, default true; false creates a one-shot job
durable: a legacy field with no effect

CronDelete takes the id returned by CronCreate. CronList takes no arguments. The interesting design work is concentrated in CronCreate.

Use a standard cron string instead of a new DSL

0 9 * * * means 9am every day, exactly as it does in Unix crontab. A JSON object such as { minute: "*/5", hour: "*", ... } might look more structured, but it would make both users and models learn a new language. Industry convention wins.

The recurring: true default encodes a preference

Without the field, a job repeats. That aligns with Cron’s typical use cases: CI monitoring, deployment observation, and periodic health checks. One-shot reminders are the less common case and require an explicit recurring: false.

durable is a transparent historical artifact

The description says that durable has no effect. The field likely remains for compatibility after an earlier persistence design was removed. It is neither hidden nor silently honored; Claude is told not to spend effort configuring it.

4. Schema validation

Field	Type	Default	Schema constraint
`cron`	string	none; required	five-field shape, shallow validation
`prompt`	string	none; required	no length limit
`recurring`	boolean	`true`	boolean
`durable`	boolean	none	legacy field

The meaningful constraints are runtime behaviors:

seven-day expiry for recurring jobs
firing only while the REPL is idle
automatic jitter and load spreading
session-only lifetime

Cron’s syntax is too flexible for a schema to classify every schedule as good or bad. Both 7 * * * * and 0 * * * * are legal. Natural-language guidance teaches Claude which valid schedule best matches the user’s intent.

ScheduleWakeup: the specialized version

CronCreate is the general scheduler. The /loop skill uses ScheduleWakeup for dynamic-interval loops:

Claude itself is the caller rather than an external trigger.
The previous loop prompt is passed forward automatically.
The tool description accounts for a five-minute prompt-cache TTL.
The usual interval is 60–1,200 seconds.

The division is simple: general scheduling uses CronCreate; self-scheduling inside /loop uses ScheduleWakeup. It is Cron’s loop-specialized relative.

Division of responsibility among neighboring tools

Dimension	Interaction trio	Locate + perceive + execute	Bash	Agent	Task family	Web pair	Cron family
Role	Collaborative alignment	Modify code	Execute commands	Derive Claude	Externalize memory	Reach the web	Trigger the future
Time model	Present	Present	Present	Present, fork/join	Across time	Present	Future, scheduled
State	None	Disk	None	Subagent	Runtime storage	None	Session-only, max seven days
Naming pattern	Enter / Exit	Read / Edit / Write	Single	Single	CRUD family	Fetch / Search	Create / Delete / List
Main benefit	User alignment	Precise code changes	Engineering workflow	Context space	Against forgetting	Controlled information	Wait for the world to change

Cron vs. Task

Both families create state across time, but in opposite directions:

Task: leaves unfinished work in the present, recording what should be done.
Cron: schedules a future prompt, recording when something should happen.

Task is a box of notes that Claude checks manually. Cron is an alarm that rings automatically. Task means “Claude chooses to call List”; Cron means “the clock wakes Claude.”

Cron vs. Bash background execution

Both are asynchronous, but their triggers differ:

Bash background: the machine waits for a command to finish once.
Cron: the runtime waits for a time and fires once or repeatedly.

Bash background handles “wait for CI to finish.” Cron handles “check every five minutes.” One is asynchronous I/O; the other is asynchronous time.

Cron vs. Agent

Both create parallel work in different dimensions:

Agent creates spatial parallelism by forking a new context.
Cron creates temporal parallelism by queueing work for the future.

The first eleven tools perform actions now. Cron is the only primitive that treats future time as a first-class input. It does not add a new capability so much as provide a trigger moment for every other capability.

Summary

The Cron family’s most interesting signal is a single design line visible at every layer: reuse industry conventions to reduce cognitive load.

Naming: reuse forty years of Unix crontab vocabulary rather than inventing concepts.
Fields: represent schedules as standard five-field strings, not a new JSON DSL.
Defaults: recurring: true matches monitoring, while one-shot reminders are explicit exceptions.
Timezone: use local time and avoid UTC conversion.
Schema: remain intentionally thin because valid cron syntax cannot by itself distinguish good intent from bad intent.

Another unusual signal is the server’s perspective encoded in the tool prompt. Avoiding :00 and :30 distributes load across the fleet. Most tools care only about Claude using them correctly; Cron also accounts for the operational consequences of thousands of scheduled requests.

Honest transparency runs throughout the family: session-only lifetime is stated at the start, the seven-day cap must be disclosed, durable is labeled ineffective, and jitter is exposed. Claude should not promise what the runtime cannot deliver.

The Create / Delete / List trio forms a complete lifecycle, just like the Task family. Create does the substantive work; List observes and Delete manages the active state.

The next article will examine Monitor: Cron wakes Claude when the clock reaches a point; Monitor wakes Claude when an event occurs. One is proactive scheduled polling; the other is passive event-driven streaming.

I built a YouTube-to-text tool, and three things turned out much harder than expected

Zhengxin — Wed, 26 Aug 2026 05:59:06 +0000

Someone links a 45-minute conference talk and says "the good part is in the middle somewhere." You want three sentences. You do not want 45 minutes.

So I built SummarizeVideoToText: paste a video link, get a text workspace — full transcript, AI summary, timestamped chapters, a mind map, and a Q&A panel you can interrogate about the video. No sign-up needed to try it.

That's the pitch. The interesting part is what broke along the way.

1. Getting captions is a fallback chain, not an API call

My first version called one endpoint and assumed a transcript came back. In practice, that endpoint fails constantly — YouTube rotates its internals, some videos need a proof-of-origin token, some tracks exist but not in the language you asked for.

What actually works is a chain of providers where each layer falls back to the next:

export class ChainProvider implements TranscriptProvider {
  constructor(private readonly providers: TranscriptProvider[]) {}
  // try each in turn; fall through on failure
}

The non-obvious part is knowing when not to fall through. Two cases end the chain immediately:

invalid_url — the link itself is broken. No provider will do better.
no_transcript — layer one confirmed the page loads fine and has no caption track at all. A paid provider will confirm the same thing and bill you for it.

Everything else falls through. That distinction is the difference between a robust chain and a machine that burns API credits to rediscover the same "nope."

The honest limitation this leaves: if a video has no captions in any form, there's nothing to summarize. I show that plainly instead of pretending. Audio transcription for YouTube is on the roadmap; TikTok and Instagram already go through AI transcription because they rarely ship captions.

2. Caching wasn't about speed. It was about money.

I started with Redis and a TTL, like you do. Then I watched the logs: a video would get summarized, sit for a week, the key would expire, someone would open the same URL — and the whole pipeline would run again. New caption fetch, new LLM call, new bill.

The realization: a video's content never changes. There is no correctness reason to ever evict a summary. TTL made sense for a hot cache, not for the artifact itself.

So it became two layers:

Redis — hot cache, short TTL, absorbs the repeat traffic.
Postgres — permanent store, no TTL. Redis misses land here, not on the model.

Storing a few KB of text forever costs orders of magnitude less than regenerating it once. If your pipeline has an expensive deterministic step, "cache expiry" and "delete the result" should not be the same decision.

The user-visible payoff is that opening a video someone else already summarized is instant and costs nobody anything — which is also why I could leave the free tier usable without an account.

3. Notion doesn't take Markdown

I wanted "export this whole note to Notion." I assumed I'd POST some Markdown. Notion's API is a block model — every heading, paragraph, and list item is a typed object, and the constraints stack up fast:

Max 100 child blocks per request. A transcript is hundreds of lines.
Max 2000 characters per rich-text object. Long paragraphs need chunking.
Max 2 levels of nesting per request. So a collapsible toggle containing a full transcript can't be created in one shot: you create the toggle, read its ID out of the response, then append its children in batches.

And the one that cost me an evening of confusion: an integration without "read content" permission gets partial objects back. Creating a page returns an object with an id and no url. Searching returns pages with no properties, so no title. Nothing errors. You just get undefined where you expected a link, and a page titled "".

Two lessons. First, when an API returns a suspiciously empty field, check the permission scope before you check your code. Second, degrade instead of inventing: my first fix put the string "(Untitled page)" in the UI, which turned a missing title into a confidently wrong one. The real fix was to reconstruct the URL from the ID (notion.so/<id-without-dashes> is a valid link) and drop the page name from the message when it isn't known.

Bonus: the Obsidian URL that was always too long

Obsidian has a URI scheme: obsidian://new?name=...&content=.... Clean, one click, works great in the demo.

It never worked in production. A full transcript blows past the URI length limit every single time, so my code silently fell back to downloading a .md file. Users clicked "Export to Obsidian" and got a file in their Downloads folder — technically not a failure, so nothing ever showed up in the error logs.

The fix was one flag I'd missed in the docs:

await copyText(content);
window.location.href = `obsidian://new?name=${encodeURIComponent(title)}&clipboard=true`;

clipboard=true tells Obsidian to pull the body from the clipboard. The URI now carries only the title, and length stops being a factor.

The analytics bug that made everything else unmeasurable

One more, because it invalidated a week of numbers.

My event helper was defensive:

export function track(event, params) {
  const gtag = window.gtag;
  if (typeof gtag !== 'function') return;  // ← this line
  ...
}

Sensible: ad blockers exist, analytics should never break a click. But the gtag stub was loading with afterInteractive, meaning window.gtag doesn't exist until hydration finishes. On a slow connection that's a multi-second window — and the "Summarize" button is the first thing anyone clicks. Those events were dropped silently, so my funnel's denominator was quietly too small.

The fix is to load the tiny stub beforeInteractive (it only pushes to an array) and let the real script arrive later and replay the queue. That's what Google's own snippet does; I'd split it apart without thinking about ordering.

Related lesson from the same audit: instrument outcomes, not intentions. I was tracking "user clicked Export" but not whether the export succeeded. 100 clicks could be 97 successes or 3. Every click event that kicks off async work deserves a matching result event with a failure code.

What it is now

YouTube via official captions; TikTok / Instagram via AI transcription
Summary, timestamped chapters, key insights, an interactive mind map, and Q&A grounded in the actual transcript
25 summary templates (study notes, meeting minutes, Twitter thread, flashcards, SEO article…) and 14 output languages, independent of the video's language
Export the whole note to Notion, Obsidian, or Markdown, with clickable timestamps that jump back into the video
Free: 2 videos/day with no account (up to 15 min), 10/day with a free Google sign-in (up to 1 hour)

Try it: summarizevideototext.com

If you've fought with the Notion block API or the YouTube caption endpoints, I'd genuinely like to compare notes in the comments — especially if you found a cleaner answer than a fallback chain.

Claude Code Tools Deep Dive (11): WebFetch + WebSearch

Zhengxin — Tue, 25 Aug 2026 05:36:03 +0000

This is the eleventh article in my series on Claude Code tools. The first ten covered Claude Code’s mostly inward-facing toolkit: aligning with the user, operating the local filesystem, running commands, spawning subagents, and managing todos. All of those tools are built around the local environment.

Real engineering work often requires Claude to leave the local environment: read Anthropic’s API documentation, inspect a third-party library’s GitHub README, find a current npm tutorial, or verify an official specification. That information may not be local—or it may postdate the training data.

Claude Code answers with a pair of internet tools: WebFetch retrieves content from one known URL; WebSearch finds URLs across the web from a query.

This series begins with a prerequisite article explaining what tools are and how Claude uses them. Like the other articles, this one follows the four-layer framework introduced there.

WebFetch + WebSearch

These tools are covered together for the same reason as Grep + Glob: their semantics are tightly coupled. One fetches by URL and the other searches by query, and they are frequently combined—Search finds an entry point, then Fetch extracts the content.

Family overview

Tool	Input	Output	Typical use
WebFetch	One known URL	Page content, transformed from HTML to Markdown	“Read this documentation and extract X”
WebSearch	A query	Search results with titles and URLs	“Find the latest way to do X”

The division is simple:

Know the URL? Call WebFetch directly.
Do not know the URL? Use WebSearch, then WebFetch the useful results.

This mirrors Grep + Glob in the local filesystem. Grep + Glob search and locate locally; WebSearch + WebFetch do the same work on the public internet. The mental model stays the same; only the domain changes.

What they do

Together, WebFetch and WebSearch solve how Claude can break through the time and scope limits of training data and obtain current, specific external information:

Break through the training cutoff: search and fetch can retrieve information published today.
Break through training coverage: an obscure library may not appear in training data, but its official docs can be fetched.
Verify official information: when an answer promises citations or official wording, the source must actually be read.
Compress content: WebFetch uses AI to return only what the prompt asks for instead of placing an entire HTML page in context.

This family differs from every earlier tool in one decisive way: it is the only one that crosses the local boundary. The first ten tools operate on the local machine; WebFetch and WebSearch connect Claude to the public web.

A concrete example

Scenario: The user says, “I think Anthropic recently released a Claude 4.5 Sonnet model. Look up how to use its API, especially what changed from Claude 4, and check the pricing.”

The information is online, may postdate training, and is too volatile to answer from memory:

the model may be newly released
API parameters may have changed
pricing numbers are not safe to guess

Step 1: Find an entry point with WebSearch

Claude does not know the exact URL but knows the information should come from Anthropic:

WebSearch(
  query: "Claude 4.5 Sonnet API pricing announcement 2026",
  allowed_domains: ["anthropic.com", "docs.anthropic.com"]
)

allowed_domains narrows the search to official sites and excludes marketing pages or second-hand summaries.

The results might be:

1. Claude 4.5 Sonnet — Anthropic
   https://www.anthropic.com/news/claude-4-5-sonnet
2. Models Overview — Anthropic Docs
   https://docs.anthropic.com/en/docs/about-claude/models
3. Pricing — Anthropic
   https://www.anthropic.com/pricing

Each result is a title and URL, not the full page. Claude now has three precise entry points.

Step 2: Extract the details with WebFetch

Claude fetches each URL with a specific prompt:

WebFetch(
  url: "https://www.anthropic.com/news/claude-4-5-sonnet",
  prompt: "Extract the release date, improvements over Claude 4, benchmark numbers, and API model ID."
)

The second argument does not mean “return the full page.” It means process the page for this purpose. Behind the scenes, the runtime:

fetches the URL
converts HTML to Markdown
uses a smaller, faster model to extract what the prompt requests
returns only the extracted result

A 5,000-word article may become 200 words in the main context. Like Agent, WebFetch is a context-compression mechanism.

After three WebFetch calls, Claude has structured summaries sufficient to answer the API, comparison, and pricing questions.

Key insight: WebFetch is curl with AI

Traditional curl means “URL in, raw HTML out.” WebFetch means “URL plus intent in, processed result out.”

With curl, Claude must parse HTML, remove CSS and navigation noise, and ignore advertisements.
With WebFetch, the runtime’s AI does that work and returns content already extracted for the question.

WebFetch is therefore an on-demand internet extraction primitive, not merely a webpage downloader.

When they are triggered

Use WebSearch when:

you need current information beyond the training cutoff
you do not know the exact URL
you want to compare several sources
you need to search within a particular domain using allowed_domains
you want to exclude particular domains using blocked_domains

Use WebFetch when:

the URL is known from the user or WebSearch
you need official docs, specifications, or API references summarized against a specific prompt
you need to verify a citation
you need a GitHub README or documentation page, although gh is usually better for GitHub

Combine them when:

Search finds URLs → choose authoritative results → Fetch details → synthesize the answer
Search finds three to five sources → Fetch each → cross-check them

Do not use them when:

the answer is stable and already in training knowledge, such as basic JavaScript syntax
the content is GitHub-specific; use gh through Bash when possible
the URL requires authentication; WebFetch cannot access Google Docs, Confluence, Jira, or private GitHub repositories
the information is local; use Grep instead of WebSearch

The central principle is: do not go online unnecessarily. The web is slower, more expensive, and vulnerable to network failures and page changes. Use it only when local files and training knowledge are insufficient.

Technical design

WebFetch and WebSearch are sibling tools with a shared design philosophy. Their roles are distinct but complementary, so we can examine both through the four-layer framework.

WebFetch

1. Naming

WebFetch

The name says exactly what it does: fetch a web resource. “Fetch” is an industry verb from the Fetch API and git fetch, suggesting retrieval rather than exploration. The url field is immediately familiar to anyone who has worked with the web.

ReadURL would be misleading because WebFetch is not a lossless Read operation. It performs AI-assisted, on-demand extraction. HTTPGet would be too low-level and would lose the promise of processing content against a prompt. Fetch sits between raw retrieval and AI processing, which is exactly the intended semantic boundary.

2. Tool-level description

WebFetch’s description is heavier than most tools. It begins with an all-caps IMPORTANT and follows with usage notes focused on four concerns: authentication failures, MCP precedence, GitHub specialization, and redirect safety.

IMPORTANT: authenticated services are out of scope

IMPORTANT: WebFetch WILL FAIL for authenticated or private URLs. Before using this tool, check if the URL points to an authenticated service such as Google Docs, Confluence, Jira, or GitHub. If so, look for a specialized MCP tool that provides authenticated access.

This is the strongest sentence in the WebFetch description. IMPORTANT plus WILL FAIL prevents a wasted call into a 401 or 403. It also gives a replacement: find an authenticated MCP tool.

Every “no” comes with a “yes”: not this fetcher, but that specialized tool. Claude learns to inspect the available tool ecosystem before acting.

MCP takes precedence

IMPORTANT: If an MCP-provided web fetch tool is available, prefer using that tool instead, as it may have fewer restrictions.

WebFetch explicitly acknowledges its limits. If a specialized MCP fetcher exists, use it. This humility is unusual in tool descriptions and reinforces the rule that authentication and capability-specific access belong to a better adapter.

GitHub gets a specialized instruction

For GitHub URLs, prefer using the gh CLI via Bash instead, such as gh pr view, gh issue view, or gh api.

GitHub is singled out because it is common and because gh can use the user’s local credentials. It can access private repositories and review comments that an anonymous WebFetch cannot. This is a case where a specific workflow outranks the general-purpose tool.

Cross-host redirects require an explicit protocol

When a URL redirects to a different host, the tool will inform you and provide the redirect URL in a special format. You should then make a new WebFetch request with the redirect URL.

WebFetch does not silently follow a cross-host redirect. It reports the new URL and lets Claude decide whether to fetch it. Same-host redirects can remain convenient; cross-host redirects become an explicit security boundary. This protects against pages that quietly send the fetcher somewhere unexpected.

Transparent 15-minute caching

Includes a self-cleaning 15-minute cache for faster responses when repeatedly accessing the same URL.

Claude is told that repeated calls to the same URL may be faster. The disclosure encourages useful re-fetching in one session without making Claude worry that every retry is wasteful.

Automatic HTTP-to-HTTPS upgrade

HTTP URLs will be automatically upgraded to HTTPS.

This makes a hidden behavior explicit. Claude can provide http:// and the runtime upgrades it without requiring a manual edit—lowering error rates without relying on silent magic.

3. Field-level descriptions

WebFetch has only two fields, but both are required:

url: the complete URL
prompt: what to extract from the page

Why is prompt required? Because WebFetch does not return the full page. It returns content processed according to the prompt. Without one, the small runtime model would not know what to extract or how much to return.

Compare the two mental models:

curl https://example.com
→ raw HTML, potentially tens of thousands of words

WebFetch(url, prompt: "Extract the three key points")
→ a focused summary

Writing the prompt is like briefing a new colleague. “Read this page” is shallow; “Find every rate-limit number, list each one, and say explicitly if none is present” is precise.

Making prompt required is WebFetch’s most elegant field decision. It forces Claude to decide what it needs before fetching, protecting the context budget instead of fetching first and filtering later.

4. Schema validation

WebFetch’s schema has almost no hard constraints:

Field	Type	Constraint
`url`	string	URI format validation
`prompt`	string	required; no length constraint

The one physical barrier is url with a URI format. A value such as foo is rejected before the tool call is sent. Claude must provide a complete URL.

Everything else—authentication, GitHub, MCP, redirects, and when to use the tool—lives in natural-language guidance. WebFetch’s complexity is not parameter validation; it is judging when the tool should not be used.

WebSearch

1. Naming

WebSearch

The tool uses Search rather than WebQuery or GoogleSearch, preserving generality and avoiding a search-engine brand. Its behavior is “query in, result set out,” exactly what Search means.

Together with WebFetch, the names form a clean pair: Fetch retrieves a known URL; Search discovers URLs from terms.

2. Tool-level description

WebSearch contains two unusually strong constraints: citation obligations and explicit time awareness. Its description focuses on four ideas: capability, mandatory Sources, domain filtering, and the correct year.

Basic capability

Allows Claude to search the web and use the results to inform responses. Provides up-to-date information for current events and recent data.

These two sentences state why WebSearch exists: to overcome the freshness limits of training data.

Mandatory citations at CRITICAL strength

CRITICAL REQUIREMENT - You MUST follow this:

After answering the user's question, you MUST include a “Sources:” section at the end of your response.

In that section, list all relevant URLs from the search results as Markdown hyperlinks: Title.

This is MANDATORY—never skip the Sources section.

This is the heaviest paragraph in the WebSearch description. CRITICAL, MUST repeated three times, and MANDATORY elevate citation from advice to law.

Why require Sources? Search results come from uncontrolled sources: some are biased, stale, or optimized for SEO. A Sources section provides traceability so the user can inspect whether the answer rests on reliable material.

It also enforces the fact-checking discipline established at the beginning of the series. If Claude promises official or cited information, it must actually retrieve the source, and WebSearch must expose the URLs.

Domain filtering

Domain filtering is supported to include or block specific websites.

This reminds Claude that allowed_domains can create an official-source whitelist, while blocked_domains can exclude low-quality or unwanted sites. To verify Anthropic’s official wording, for example, search only anthropic.com.

The current-year rule

IMPORTANT - Use the correct year in search queries. The current month is July 2026. You MUST use this year when searching for recent information, documentation, or current events. For “latest React docs,” search with the current year, not last year.

Hardcoding the current time in a tool description is unusual, but the reason is profound: Claude may not know which month it is after its training cutoff. Search freshness depends on dates. Adding the year to the query helps distinguish current documentation from old results.

The React example turns an abstract rule into a concrete comparison: correct current year versus stale year.

US-only availability

Domain filtering is supported to include or block specific websites. Web search is only available in the US.

This small boundary statement prevents failed calls in unsupported regions.

3. Field-level descriptions

query: required search terms
allowed_domains: optional whitelist array
blocked_domains: optional blacklist array

The two domain filters expose two independent information postures:

allowed_domains: search only sources Claude trusts, such as anthropic.com or docs.python.org.
blocked_domains: exclude sources Claude does not want, such as outdated or low-quality sites.

The same domain should not logically appear in both lists, but the tool leaves that judgment to Claude rather than forbidding both arrays at the schema level.

The only explicit field-level minimum is that query must contain at least two characters, preventing meaningless one-character searches.

4. Schema validation

Field	Type	Constraint
`query`	string	`minLength: 2`
`allowed_domains`	array of strings	optional
`blocked_domains`	array of strings	optional

minLength: 2 is a physical schema barrier. A one-character query is rejected directly, even though a single Chinese character might sometimes be meaningful. The tool chooses a simple universal rule.

The domain arrays are intentionally permissive. The schema allows both to be populated; prompt guidance handles the logical conflict. Capability remains open while judgment stays with Claude.

Why dedicated WebFetch and WebSearch instead of Bash + curl/search APIs?

Bash could theoretically combine curl with a search API, but that creates several problems:

HTML parsing: raw curl output includes CSS, navigation, and advertisements.
Credential leakage: a local curl might accidentally use .netrc or cookies.
Search API key management: someone must provide and protect Google or Bing API credentials.
No citation obligation: Claude could summarize curl output without reporting sources.
No content compression: a 50,000-word page could flood the context.

The dedicated tools solve these problems: HTML becomes Markdown automatically, fetching is anonymous, API credentials are managed by the runtime, WebSearch requires Sources, and WebFetch extracts against a prompt. This is another example of the division: Bash is the catch-all; dedicated tools are the refined interface.

Division of responsibility among neighboring tools

Dimension	Interaction trio	Locate + perceive + execute	Bash	Agent	Task family	WebFetch / WebSearch
Role	Collaborative alignment	Modify code	Execute commands	Derive Claude	Externalize working memory	Reach the public web
Input source	User	Disk	Command	Prompt	User / AI	URL / query
Output	Structured	Text / diff	Raw text	Subagent result	State	HTML → Markdown / summaries
Authentication	None	Existing user session	User credentials	Forked session	User session	Anonymous; no credentials
Main benefit	User alignment	Precise code changes	Engineering workflow	Context space	Against forgetting	Controllable information access

WebFetch + WebSearch mirror Grep + Glob:

Grep + Glob: find by content or path inside a project.
WebFetch + WebSearch: fetch by URL or search by terms on the public web.

Both pairs implement “one precise target plus one exploratory search,” but the web pair faces an untrusted external world. That is why it adds MCP precedence, explicit cross-host redirects, and mandatory Sources.

The boundary with Bash is equally clear. Curl and search APIs could do the work, but they expose parsing, credentials, keys, citations, and context to risk. Dedicated tools package those concerns into a controlled interface.

Summary

WebFetch + WebSearch split the broad request “let the AI browse the web” into two specialized tools and use all four design layers:

Naming: Fetch and Search borrow industry conventions. Fetch implies a known target; Search implies exploratory discovery.
Tool-level descriptions: WebFetch emphasizes authentication failures, MCP precedence, GitHub specialization, and redirect safety. WebSearch emphasizes mandatory Sources and the current-year rule—one protects traceability, the other compensates for Claude’s weak time awareness.
Field design: WebFetch has only two fields, but making prompt required elevates on-demand extraction and protects context. WebSearch exposes allowed and blocked domains as independent trust controls.
Schema validation: WebFetch rejects non-URI strings; WebSearch rejects one-character queries. Basic mistakes are stopped physically at the schema boundary.

Several signals are unique across the tool ecosystem:

Required prompt: WebFetch becomes an extraction primitive rather than a page downloader.
Mandatory Sources: WebSearch is the only tool whose description uses CRITICAL and MANDATORY to enforce response formatting and citation transparency.
Hardcoded current time: a dynamic date is inserted into a static prompt to compensate for Claude’s missing sense of the current month.
Humility toward MCP: the tool explicitly says “not me—use the authenticated or more capable MCP tool.”
No automatic cross-host redirects: the security decision is handed to Claude through an explicit protocol rather than silent behavior.

Together these signals turn the ability to reach the public web into an external information interface that is controlled, traceable, and willing to defer to better tools.

The next article will examine the Cron family, shifting from the spatial dimension—project and public web—to the time dimension: scheduled and future execution.

Claude Code Tools Deep Dive (10): The Task Family

Zhengxin — Mon, 24 Aug 2026 14:34:38 +0000

This is the tenth article in my series on Claude Code tools. The first nine covered:

The interaction primitive trio—AskUserQuestion, EnterPlanMode, and ExitPlanMode.
The execution primitive chain—Grep + Glob → Read → Edit / Write.
The general-purpose fallback, Bash.
The meta-tool, Agent.

The first nine tools are about Claude doing the thing happening now. Each tool call performs one immediate action. Real projects also require Claude to remember what needs to happen, track progress, decompose a large task, and share one checklist across multiple Claudes.

That requires a task-management system. Claude Code’s answer is the Task family—six tools that form a todo system.

This series begins with a prerequisite article explaining what tools are and how Claude uses them. Like the other articles, this one follows the four-layer framework introduced there.

The Task family: TaskCreate / TaskList / TaskGet / TaskUpdate / TaskStop / TaskOutput

This is the first time the series examines six tools in one article. Why group them? Because they share one data model—a task list—and are semantically coupled. Discussing one in isolation would shift attention from the system to a single operation. It would be like explaining how to create one Jira ticket without explaining the Jira system around it.

Family overview

Tool	Responsibility	Typical moment
TaskCreate	Create a task	Decomposing a complex request or receiving multiple requirements
TaskList	List all tasks	Finding the next available task or reporting progress
TaskGet	Retrieve one task’s details	Before starting work or inspecting dependencies
TaskUpdate	Change task status or metadata	Starting, completing, or linking tasks
TaskStop	Stop a background task	Aborting a background Bash process or subagent
TaskOutput	Retrieve background output	Deprecated; use Read on the output file instead

The family actually contains two groups:

The first four are CRUD for conceptual todo tasks—something Claude remembers needs to happen.
The last two control runtime tasks—a real Bash process or subagent that is currently running.

They all say Task, but they operate on different things. This is the family’s most confusing design choice and will matter throughout the article.

What it does

The Task family—especially the four todo tools—solves how Claude can manage multi-step work across tool calls and across time:

Make decomposition visible: complex requirements become entries whose progress the user can see.
Track progress: every task has a pending, in_progress, or completed state.
Model dependencies: “A blocks B” becomes explicit and enforces order.
Coordinate multiple Claudes: the main Claude decomposes work, subagents claim owners, and everyone shares one list.
Compress context: a short subject can stand for an entire chunk of work, reducing what the main Claude must keep in mind.

The crucial difference from earlier tools is that Task is the only family with persistent state. Read, Edit, and Bash return a result once in a tool call. A TaskCreate entry remains in the runtime and appears in future TaskList calls until it is completed or deleted.

A concrete example

Scenario: The user says, “Add a user-profile page. It needs a backend API, a frontend component, a database schema, tests, and permission checks.”

This is a multi-task requirement.

The bad alternative: no Task family

Without tasks, Claude can only:

Keep the plan in short-term memory while working.
Announce every next step in chat as a textual progress log.
Eventually lose a requirement—perhaps the tests—when the conversation becomes long.
Reconstruct the entire conversation whenever the user asks, “How far along are you?”

The core problem is that the checklist exists only in Claude’s short-term context. Context compression, a subagent handoff, or session recovery can make it disappear.

How the Task family solves it

Step 1: Create tasks immediately

TaskCreate(subject: "Design database schema", description: "Add profile fields to users or create a profiles table")
TaskCreate(subject: "Write migration", description: "Generate the Knex migration")
TaskCreate(subject: "Implement backend API", description: "GET/PATCH /api/profile through the auth middleware")
TaskCreate(subject: "Build ProfilePage", description: "Add the /profile route, form, and API submission")
TaskCreate(subject: "Add tests", description: "API tests plus frontend component tests")

Each call returns an ID, such as task_001 through task_005.

Step 2: Add dependencies

The schema must exist before the API, and the API must exist before the frontend. TaskUpdate expresses those relationships through blockedBy:

TaskUpdate(taskId: "task_002", addBlockedBy: ["task_001"])
TaskUpdate(taskId: "task_003", addBlockedBy: ["task_002"])
TaskUpdate(taskId: "task_004", addBlockedBy: ["task_003"])
TaskUpdate(taskId: "task_005", addBlockedBy: ["task_003"])

The list now forms a dependency graph: schema → migration → API → (frontend + tests).

Step 3: Find the next available task

TaskList returns:

task_001 · pending · Design database schema · blockedBy: []
task_002 · pending · Write migration         · blockedBy: [task_001]
task_003 · pending · Implement backend API    · blockedBy: [task_002]
task_004 · pending · Build ProfilePage        · blockedBy: [task_003]
task_005 · pending · Add tests                · blockedBy: [task_003]

Only task_001 is pending and unblocked, so it is the next task.

Step 4: Claim, execute, and complete

TaskUpdate(taskId: "task_001", status: "in_progress")
# Claude designs the schema and records the decision
TaskUpdate(taskId: "task_001", status: "completed")

Once task_001 is complete, the migration task is unblocked.

Step 5: Delegate a task to a subagent

The frontend task can be delegated:

Agent(
  description: "Build ProfilePage",
  prompt: "Task task_004: build the ProfilePage at /profile. Use TaskGet for the full details."
)

The subagent can use the task ID to call TaskGet, claim the task with TaskUpdate, and mark it completed. The main Claude and the subagent coordinate through the shared task system rather than sending ad hoc messages.

Step 6: Report progress

Whenever the user asks for an update, TaskList is enough:

✅ task_001 · completed  · Design database schema
✅ task_002 · completed  · Write migration
🔄 task_003 · in_progress · Implement backend API (Claude)
⏸️ task_004 · pending    · Build ProfilePage (blocked by 003)
⏸️ task_005 · pending    · Add tests (blocked by 003)

One list makes the state immediately legible.

The key insight: Task externalizes Claude’s working memory

Earlier tools are about doing. The Task family is about remembering. It moves Claude’s short-term plan into runtime storage.

That creates two major effects:

Persistence across contexts: tasks survive context compression, switching, and recovery.
Sharing across Claudes: the main Claude and subagents synchronize through the Task system instead of messaging each other manually.

This resembles a human engineering team writing work into Jira. It is not a rejection of personal memory; memory is individual, while tasks are shared. Writing them down enables collaboration, tracking, and completeness.

When it is triggered

The family’s prompts provide fairly strict guidance:

Use Task tools for:

Complex work with three or more steps. A one-step task does not need a task entry.
Nontrivial multi-operation work. Planning and tracking have value here.
An explicit user request for a todo list.
Multiple requirements in one instruction. Create them together.
Plan mode. Track the plan’s steps.
Starting work. Claim the task and mark it in_progress before acting.
Finishing work. Mark it completed immediately and inspect newly unblocked tasks.

Do not use Task tools for:

one direct operation
a trivial task where tracking creates more noise than value
a simple job with fewer than three steps
pure conversation or an informational answer

The core judgment is: the Task family is for work with meaningful scale. If a single tool call completes the task, a Task entry is noise. If the work has decomposition, dependencies, or progress worth tracking, failing to create one is a process failure.

Technical design

1. Naming

TaskCreate / TaskList / TaskGet / TaskUpdate / TaskStop / TaskOutput

The shared Task prefix replaces alternatives such as Todo, Ticket, or Job. “Task” implies a clear execution owner; a todo can merely mean “look at this someday.” The name itself hints that an owner field exists.

The CRUD suffixes—Create, List, Get, Update—are standard database-like verbs: create one, list all, retrieve one, update one. The four names immediately establish a mental model of an enumerable, addressable, mutable entity collection.

There is deliberately no TaskDelete. Hard deletion is represented by TaskUpdate(status: "deleted"). Deletion is treated as a terminal state in the state machine rather than a separate operation, concentrating all status transitions in TaskUpdate and reducing decision overhead.

TaskStop and TaskOutput introduce semantic drift. They reuse the Task namespace but operate on running background processes—Bash or subagents—rather than conceptual todos. The designers chose one namespace over a separate runtime-task family, but this is also the family’s most obvious source of confusion.

activeForm is the most ambitious field name in the family. It is not called presentContinuous, verbForm, or spinnerLabel; activeForm sounds grammatical. When Claude writes it, the name nudges Claude to convert the action into the present progressive rather than enter a generic UI label.

2. Tool-level descriptions

Each Task tool has its own description, but they share a positioning: these are members of one collaboration contract, not isolated utilities.

TaskCreate: a quantitative threshold

Use this tool proactively in these scenarios: Complex multi-step tasks—when a task requires 3 or more distinct steps or actions.

“Three or more” is an explicit threshold. It trains Claude not to create tasks for every small operation and replaces the vague word “complex” with a measurable rule.

A three-stage timing protocol

After receiving new instructions—immediately capture requirements as tasks.
When you start working—mark the task in_progress before beginning.
After completing—mark it completed and add follow-up tasks.

The rhythm is exact: receive → create; start → in progress; finish → completed. It wraps every work segment and prevents work from silently beginning or ending.

TaskUpdate: a strict completion standard

Only mark a task completed when it is fully accomplished. If there are errors, blockers, or unfinished work, keep it in_progress. Never mark it completed when tests fail, implementation is partial, or unresolved errors remain.

This blocks “fake completion”—the tendency to mark something done because the broad direction looks right while leaving half-finished work behind.

TaskList: a default scheduling intuition

Prefer working on tasks in ID order (lowest ID first) when multiple tasks are available.

Earlier tasks are often prerequisites for later tasks, so ID order makes the default schedule match creation order.

TaskGet before TaskUpdate: staleness awareness

Make sure to read a task’s latest state using TaskGet before updating it.

Another agent may have changed the task, especially in a multi-Claude workflow. Fetching the latest state before writing is a simple form of optimistic concurrency control: read before write, never overwrite stale state blindly.

TaskOutput: transparent deprecation

DEPRECATED: Background tasks return their output file path in the tool result and in the completion notification. For Bash tasks, prefer Read on that output path.

The tool description directly says not to use it and gives the replacement. This reflects a broader design principle: if an existing primitive can cover a capability, do not maintain a separate tool for it. Fewer tools mean less API surface and less decision burden.

A family-specific reminder hook

If Claude goes a long time without using task tools, the harness can insert a system reminder:

The task tools haven’t been used recently. If your work would benefit from tracking progress, consider using TaskCreate and TaskUpdate.

This nudges Claude toward progress tracking without making it mandatory. The reminder ends with the equivalent of “only use these if relevant.” Earlier tools do not need this hook because their value is immediate; Task tools need a cross-time nudge.

3. Field-level descriptions

A complete Task object includes:

id: system-generated unique identifier
subject: short imperative title, such as “Run tests”
description: detailed explanation
activeForm: present-progressive form, such as “Running tests,” for a spinner
status: pending, in_progress, completed, or deleted
owner: the agent doing the work; empty means unclaimed
blocks: tasks blocked by this task
blockedBy: tasks blocking this task
metadata: arbitrary key-value data

Four design choices stand out.

Three representations: subject, description, activeForm

The same task appears in three forms:

subject: a short imperative, “Run tests”
description: “Run the unit tests and confirm all four auth tests pass”
activeForm: “Running tests”

They map to different UI locations:

list view shows the short subject
detail view shows the full description
a spinner uses the present-progressive active form

The forced progressive form is more than cosmetic. Claude must provide both “what to do” and “what is happening now,” encoding the distinction between intending to start and having started.

blocks and blockedBy: bidirectional dependencies

They are two views of the same relationship:

A blocks B  ⇔  B is blockedBy A

The runtime keeps both directions consistent. Claude can add one side with addBlocks or addBlockedBy, and the other side synchronizes automatically.

This is redundancy in favor of readable scheduling semantics: “what do I block?” and “what blocks me?” are different questions for Claude even though they describe one edge.

Incremental merge semantics

TaskUpdate accepts addBlocks and addBlockedBy, not a replacement-style blocks: [...]. Adding one dependency therefore cannot accidentally erase existing dependencies. Incremental updates are safer and naturally idempotent.

Status: a linear state machine with a deleted escape hatch

The normal path is:

pending → in_progress → completed

Completed tasks cannot move backward to in_progress; if the work must be redone, create a new task. This prevents unpredictable state oscillation.

deleted is a terminal cleanup state for mistaken tasks. Deleted tasks disappear from normal lists while their IDs remain reserved, preventing reuse. Deletion is therefore part of the state machine rather than disappearance from the database.

blockedBy also constrains status transitions. A task with incomplete dependencies cannot be claimed as in_progress. Status is not an isolated field; it is a multi-field transition governed by the current dependency graph.

owner and metadata: two switches for multi-Claude work

owner identifies which agent currently owns a task:

the main Claude creates it with no owner
a subagent claims it and records its agent name
TaskList shows which work is claimed and which is available
after completion, another agent can take the next task

This is the basic pattern of a distributed work queue, with Claude instances as consumers.

metadata is a free-form key-value escape hatch for file paths, reference links, subagent context, or temporary notes. owner is a core contract; metadata leaves room for extension.

4. Schema validation

The family combines schema-level static checks with runtime state-machine checks:

Constraint	Layer	Meaning
`activeForm` required	Schema	TaskCreate requires the progressive form
`status` enum	Schema	Only `pending`, `in_progress`, `completed`, or `deleted`
`subject` length	Schema	Short title has a version-dependent maximum
Backward status transition	Runtime	`completed → in_progress` is rejected
Unresolved `blockedBy` → `in_progress`	Runtime	A locked task cannot be claimed
TaskGet before TaskUpdate	Runtime guidance	Strongly recommended, but primarily prompt-enforced

Static constraints belong in the schema; dynamic constraints such as dependencies, concurrency, and legal state transitions belong in runtime. The Task family is more balanced than Read or Edit: schemas protect inputs while runtime protects transitions.

TaskOutput’s deprecation also illustrates transparent fallback. Output retrieval is not replaced by a new specialized tool; it is reduced to Read on the existing output path. Capabilities that existing primitives can cover do not need another tool.

Division of responsibility among neighboring tools

Dimension	Interaction trio	Locate + perceive + execute	Bash	Agent	Task family
Role	Collaborative alignment	Modify code	Execute commands	Derive Claude	Externalize working memory
Time model	Present, one interaction	Present, one operation	Present, command lifecycle	Present, fork/join	Persistent across time
State location	None, conversation-driven	Disk + harness	Gone after command	Inside the subagent	Runtime storage
Main benefit	User alignment	Precise code changes	Engineering workflow	Context space	Against forgetting; visible collaboration
Naming pattern	Enter / Exit pair	Read / Edit / Write family	Single tool	Single tool	CRUD + Stop / Output

The Task family is most tightly coupled with Agent:

Agent delegates work whose outcome may fail, hang, or need stopping.
Tasks provide the work-item container that makes subagent work trackable.
TaskStop accepts a subagent ID or task ID, creating a unified stop entry point.
TaskOutput used to retrieve subagent results directly; now Read handles the output file.

Task and Bash also have a useful analogy. Bash’s run_in_background puts a command in the background; TaskCreate puts a todo in persistent storage. Both prevent the main loop from blocking, but they solve different problems: Bash is asynchronous machine I/O, while Task is asynchronous human-AI coordination.

The family’s position in the ecosystem is therefore unique. The first nine tools perform one immediate operation per call. Task is a meta-primitive that stores what should happen across time.

Summary

The Task family’s elegance is not the existence of a todo list. It is the way its signals span four layers and form a complete dual system:

Naming: six tools—four CRUD operations plus Stop and Output. activeForm encodes grammar in a field name; TaskDelete is omitted in favor of status: "deleted"; output retrieval falls back to Read.
Tool-level descriptions: each tool has an independent prompt, but they reference one another and encode the collaboration contract—three-step threshold, timing protocol, false-completion prohibition, staleness warning, deprecation notice, and reminder hook.
Field-level descriptions: subject, description, and activeForm map to three UI contexts; blocks and blockedBy expose both directions of a dependency; add-prefixed fields prevent destructive replacement; owner is a hard collaboration field while metadata is a flexible escape hatch.
Schema validation: static constraints such as required activeForm and status enums live in the schema; dynamic constraints such as state transitions, dependency locks, and stale updates live in runtime.

Task extends Claude Code from the present tense to the future tense. The first nine tools do something now; Task stores what must happen in runtime storage across tool calls, time, and Claude instances. The result is a shift from relying on mental effort against forgetting to using a system against forgetting. Forgetting is no longer catastrophic because the list remains.

The deeper insight is that a dual tool family needs both a complete lifecycle and an exit path. CRUD is not “create without delete”: completed ends the normal lifecycle, deleted cleans up mistaken tasks, and dependency updates release blocked work. Every task has a defined way to end.

The forced progressive activeForm is the family’s boldest field design. It turns “fill in a UI label” into a grammar transformation and trains Claude to see work as currently happening, not merely intended. That distinction is the difference between having started and planning to start—and the difference between a static todo list and a live work rhythm.

The next article will examine WebFetch + WebSearch, the sister tools that take Claude beyond the filesystem and asynchronous tasks into the external web: one is “curl with AI,” the other “search with filters.”

DEV Community: Zhengxin

Meta Connect 2026 in 5 minutes: 7 products, prices, ship dates

1. Muse gets computer use, email and shopping

2. Ray-Ban Meta Audio: glasses with no camera

3. Ray-Ban Meta Gen 3

4. Meta Glasses lineup: 51 styles, Adventurer from $249

5. Meta Ray-Ban Display is finally in stock

6. Meta VR Glasses: 100 grams, $1,299.99, spring 2027

7. Muse Charm: the agent on a keychain

ChatGPT Still Can't Read YouTube Links. Here's the Copy-Paste That Actually Works.

How to tell it happened to you

The fix: 15 seconds, no account

Then take it back to ChatGPT, if you want

If you'd rather not use anything

The one-line version

Studying a YouTube course in Obsidian: playlist in, notes and flashcards out

The playlist becomes a queue, not a folder

One video becomes one note

The quiz becomes cards

A quiz across the whole collection

What it costs

What it doesn't do

Links

Two years of pelicans on bicycles: 103 SVGs, 66 models, and what the guy who invented the benchmark says about it

The prompt is deliberately unfair

2024: it's mostly shapes

The 560-match tournament that cost 18 cents

The models start editorialising

The laptop model that beat Opus

The inventor says don't use it

Building the zoo

Credit

Sources

Turning YouTube Videos Into Obsidian Notes — and What Shipping the Plugin Taught Me

What lands in the vault

The plugin holds no model keys

The connect handshake, and the one line that makes it safe

One note format, two producers

Re-running a command must not eat the user's writing

requestUrl doesn't stream

Flashcards, and only appending

What the community directory review actually checks

Three Obsidian CSS facts that cost me an evening

Links

Claude Code Agent Loop Deep Dive (0): From the Chat Window to the Loop

One user message, how many model calls?

The user is only at the beginning and the end

The five-line happy path is not the product

From a loop to an agent runtime

What this series will examine

Claude Code Tools Deep Dive (14): The Background Mechanism

Why Background deserves its own article

Background is an execution mode, not a behavior

One task-ID system

Three kinds of background work

Type A: a one-shot task with a known end

Type B: trigger at a future time

Type C: continuous or long-lived listening

The anti-polling principle

Task ID, Job ID, and Task (the to-do item)

A concurrent workflow

Boundaries

The four-layer design signal

Naming

Tool-level descriptions

Field-level descriptions

Schema validation

Relationship to neighboring tools

Conclusion: the invisible skeleton

Claude Code Tools Deep Dive (13): Monitor

Monitor

What it solves

A concrete example

Bad alternative 1: sleep and inspect later

Bad alternative 2: scheduled polling

Bad alternative 3: a background tail

The Monitor solution

Two data sources: command or WebSocket

When to use Monitor

Technical design

`requestUrl` doesn't stream

Bad alternative 3: a background `tail`