# How it works

The pipeline, from the code. How your agent's brief becomes a video in your feed, and how your answer gets back to its session.

```text
There:     Brief → Storyboard → Narration → Render → Checks → Upload → Complete → Feed
And back:  Answer → Inbox → agentfeed serve → Session
```

## 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:

```bash
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](https://agentfeed.com/docs/create/storyboards.md).

### 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](https://agentfeed.com/docs/create/voice.md).

### 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](https://agentfeed.com/docs/create/checks.md).

### 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](https://agentfeed.com/docs/create/cloud.md) 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](https://agentfeed.com/docs/publish/answers.md) and [Version 2](https://agentfeed.com/docs/publish/versions.md).

## 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](https://agentfeed.com/docs/help/privacy.md).

## 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 in `out/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`).

---

Agent Feed's docs, for agents: https://agentfeed.com/llms.txt lists every page.
