How it works
There
- Briefyour agent writes it
- Storyboardthe beats, by a worker
- NarrationSeth's voice, the voice gate
- RenderManim, 1080×1920, 60 fps
- Checksvoice, pacing, layout
- Uploadto signed links
- Completethe API verifies it
- Feedyour iPhone, its link
And back
- Answervoice, text, photo
- Inboxwaits for the Mac
- agentfeed serveor Agent Feed for Mac
- Sessionthe agent picks it up
There: from a brief to your feed
1. Brief
Your agent writes a brief, 150 to 400 words: what to explain, for whom, and the facts and numbers that prove it. Then it runs:
agentfeed make --brief @brief.md --project . --title "The new cache"make returns in under three seconds. On a signed-in Mac, it first records the agent's session (PUT /v1/sessions) and creates the video's job (POST /v1/jobs). That's how it can print the video's link at once. The agent puts the link in its reply.
2. Storyboard
make starts a worker in the background: a headless Claude Code (claude -p) or Codex (codex exec), in the video's job folder, ~/.agentfeed/jobs/<date>-<title>/.
The worker reads the brief and the project. It writes storyboard.json: the narration, split into beats, with what each beat shows. See Storyboards.
3. Narration and the voice gate
agentfeed narrate reads the storyboard in Seth's voice, from ElevenLabs, in one take with the timing of every word.
Each take gets a 3b1b voice score, from 0 to 100: how close its delivery is to 3Blue1Brown's narration, measured on ten dimensions. The voice gate is a score of 83, with no dimension under 60. A take that misses it gets another try. See Voice.
4. Render
The worker writes scene.py, a Manim scene that animates each beat on its words. agentfeed render renders it at 1080×1920, 60 frames a second, and mixes in the narration: out/final.mp4.
5. Checks
agentfeed check decides whether the video can be published: the voice again, the format, the hook, the pacing, the layout, the safe zones under the app's buttons, and the loop. When a check fails, the worker goes back to the scene once, with what failed. See Checks.
6. Upload to signed links
For each file, the video, its poster and its captions, the Mac asks the API for an upload link (POST /v1/jobs/{jobId}/uploads), with the file's size and SHA-256.
It sends the file straight to storage, with a PUT to that link. Media never passes through the API. An upload link works for 30 minutes.
7. Complete
POST /v1/jobs/{jobId}/complete marks the video ready. The API checks that each file arrived and matches its size, type and SHA-256. Then it notifies your phone: "Your video is ready".
8. Feed
The video is in your feed, and its link plays it.
While it's made, the link shows each step live. The Mac posts them as progress events (POST /v1/jobs/{jobId}/events): writing the storyboard, recording the narration, animating the scenes, rendering, checking, uploading.
With --cloud, steps 3 to 7 run in Agent Feed Cloud instead. Only the storyboard leaves the Mac.
And back: from your answer to the session
1. Answer
You answer at a moment in the video: a voice note, text, photos or files. Or you approve it. Your iPhone transcribes a voice note itself, and you see the words before you send them.
The app sends your answer as a comment (POST /v1/jobs/{jobId}/comments), with the moment in the video.
2. Inbox
Your answer waits in the inbox of the Mac that made the video, addressed to the session that asked for it. It stays there until that Mac takes it: it doesn't expire.
3. agentfeed serve
On the Mac, agentfeed serve asks the inbox for new answers (GET /v1/inbox). Each request waits up to 25 seconds for one, so answers arrive within moments.
4. The session
serve delivers the answer into the agent's session as a new turn:
- an open Claude Code session gets it as a message;
- a closed Claude Code session is resumed in the background, with
claude -p --resume; - a Codex thread gets it with
codex queue.
Then serve reports what happened (POST /v1/comments/{commentId}/ack), and your phone shows it: delivered, then acted on.
The agent answers with the next version of the video: agentfeed make --revise. See Get answers back and Version 2.
What leaves your Mac
- The finished video, its poster and its captions.
- The video's title, the project's folder name, the git branch and the session's title. Names only, never file paths.
- Progress labels while the video is made, its voice score and its checks.
- With Agent Feed voice, the narration's text. With Agent Feed Cloud, the storyboard.
Your code, your agent's transcript and your file paths stay on your Mac. See Privacy.
Where things live on your Mac
~/.agentfeed/jobs/<job>/: one folder per video.brief.md,storyboard.json,scene.py,narration.wav,worker.log, and the video inout/final.mp4.~/.agentfeed/settings.json: how videos are made, which agent makes them, and the voice.~/.agentfeed/device.json: your Mac's link, without its token.~/.agentfeed/venv: the toolkit's Python, with Manim.- The macOS Keychain: your Mac's device token (
agentfeed-device), and your ElevenLabs key if you added one (agentfeed-elevenlabs).