Walkthroughs

A walkthrough is an ordered tour of code that an agent writes for you: notes, line ranges in files, files at a commit, and diffs, each with Markdown narration. Ask an agent to explain a pull request, a branch, or how a feature works as a walkthrough; Zero shows it beside the code.

Following a walkthrough

Open the Walkthroughs view (the route icon in the activity bar), or the link the agent prints. The badge counts walkthroughs published since you last looked, and a dot marks each one you haven't opened yet. Choose one to see its steps; Overview opens its cover, with the summary and an outline. If you stopped partway through, the cover offers Resume at step N.

Each step opens an ordinary tab: the file in Source with the step's lines selected, a read-only snapshot at a commit, or a review of uncommitted work, a commit, a range, or a branch. Steps share one preview tab, its name in italics: the next step replaces it. Double-click it, or choose Keep Open from its menu, to keep it. In Source the code around the step's lines is dimmed; a review opens the step's file and folds the others. The narration appears inside the code, right after the step's lines, with a progress line, Previous, Next, and Close. Notes appear alone in the walkthrough's own tab.

Steps you have read get a check in the step list, and Zero remembers them in this browser. On the last step, Finish marks the walkthrough done and suggests the next one you haven't opened. Publishing a walkthrough again starts its progress over.

To ask your agent about a step, choose Copy Step for Agent in the narration: it copies the walkthrough, the step, what it points at, and a link, ending with “Question: ”.

Present hides the activity bar, sidebar, tabs, and status bar, sets the narration larger, and floats a step bar over the document. On phones the step bar shows while you follow a walkthrough; Steps opens the list.

A step can record the start of its first line when it is written. If the code changes later, the step says so, showing the line it expected and the line there now, instead of guessing where the code moved. Steps pinned to a commit never change.

Walkthroughs live in your user cache (zero/walkthroughs), up to 100 per project; the least recently updated go first. Delete one from its step list. They are per machine and are not shared through git.

Writing walkthroughs (for agents)

The quickest start: choose Copy agent instructions (the copy icon in the Walkthroughs header, or the button in an empty list), paste it into your agent, and finish the last line, “Walk me through: ”, with what to explain. The instructions carry this Zero's address, your project's path, the format, and how to publish.

Agents publish with the Zero CLI; no running server is needed:

zero walkthrough publish walkthrough.json

Examples and copied prompts use the canonical zero. If installed as zero-cli or with --name NAME, substitute your chosen command; see installation details.

{
  "project": "/absolute/path/to/repository",
  "title": "How login sessions refresh",
  "summary": "From the cookie check to the token refresh.",
  "steps": [
    { "title": "Where it starts", "body": "Every request passes through `requireSession`." },
    { "title": "The cookie check", "body": "Expired cookies fall through to refresh.", "file": { "path": "auth/session.go", "lines": [40, 58] } },
    { "title": "What this branch changes", "body": "Refresh now retries once.", "diff": { "compare": { "kind": "branch", "base": "main" }, "path": "auth/refresh.go", "lines": [12, 30] } }
  ]
}

Zero checks every path, line, and commit, stores the walkthrough, and prints its id. An open browser lists it within seconds. project is the repository or worktree root (git rev-parse --show-toplevel) or a folder outside any repository; folders inside a repository are rejected. Publishing again with the same id replaces it. Any mistake exits 1 and names each problem field, such as steps[2].file.lines: end 90 is past the file's last line, 61.

When the desktop app is installed and the daemon serves the project, the CLI prints a zero:// url and "open": true opens it in the app. On a machine serving with --remote, it prints a zero:// link that opens on your connected computer (desktopUrl in --json; see Remote hosts). Otherwise, when a running browser server shows the project, the CLI prints its web url, and "open": true opens it in the browser (never on a machine without a UI, such as an SSH session). Without one, it prints how to view the walkthrough: zero <project>, then the Walkthroughs view. The CLI never starts a server. zero walkthrough schema prints the JSON Schema.

Agents can also publish with POST /api/walkthroughs on a running zero:

curl -q -sS -X POST -H 'Content-Type: application/json' \
  --data @walkthrough.json http://localhost:7971/api/walkthroughs

The response carries the walkthrough's id and url; "open": true also opens it in the browser unless Zero runs with --no-open. GET /api/walkthrough-schema returns the JSON Schema, and any mistake comes back as a 400 naming each problem field.

Zero ships an agent skill with the full guidance: discovery, targets, and how to tell a good story. Install it with the skills CLI:

npx skills add flexdinesh/zero --skill zero-walkthrough

The skill is documentation only; Zero does not install it. Its source is skills/zero-walkthrough.

The endpoint accepts JSON only, from any local process; requests from another site's pages are refused.