Commands

All commands are available through the agent-doc CLI.

run

agent-doc run <FILE> [-b] [--agent NAME] [--model MODEL] [--dry-run] [--no-git]

Diff, send to agent, append response. The core command.

Flag	Description
`-b`	Auto-create branch `agent-doc/<filename>` on first run
`--agent NAME`	Override agent backend
`--model MODEL`	Override model
`--dry-run`	Preview diff and prompt size without sending
`--no-git`	Skip git operations (branch, commit)

Flow:

Compute diff from snapshot
Build prompt (diff + full document)
Pre-commit user changes (unless --no-git)
Send to agent
Append response as ## Assistant block
3-way merge if file was edited during response
Save snapshot and close out through the commit boundary. Successful runs commit the response in the same cycle and clean agent-owned post-commit drift back to HEAD; only genuine later local edits remain uncommitted.

init

agent-doc init <FILE> [TITLE] [--agent NAME]

Scaffold a new session document with YAML frontmatter and a ## User block. Fails if the file already exists.

diff

agent-doc diff <FILE>

Preview the unified diff that would be sent on the next run. Useful for checking what changed before running.

reset

agent-doc reset <FILE>
agent-doc reset --from-current <FILE>

Clear the session ID from frontmatter and delete the snapshot/CRDT sidecars. Use --from-current after manually cleaning a corrupted document; it rebuilds the snapshot and CRDT state from the visible markdown so old sidecars cannot resurrect stale content.

clean

agent-doc clean <FILE>

Squash all agent-doc: git commits for the file into a single commit. Useful for cleaning up history after a long session.

audit-docs

agent-doc audit-docs [--root DIR]

Audit instruction files (CLAUDE.md, AGENTS.md, README.md, SKILL.md) against the codebase:

Referenced file paths exist on disk
Combined line budget under 1000 lines
Staleness detection (docs older than source)
Actionable content checks
Generated agent-doc instruction surfaces match the running binary. From a submodule checkout, the default release audit checks the superproject install root; explicit --root DIR checks generated surfaces under that root exactly.

route

agent-doc route <FILE>

Route a /agent-doc command to the correct tmux pane. Looks up the session UUID from frontmatter, finds the pane in sessions.json, and sends the command via the managed supervisor or tmux submit path. If no live owner exists, route auto-starts a route-owned pane and reaps it after the new document cycle commits; a startup miss records diagnostics and kills the just-created idle pane.

start

agent-doc start <FILE>

Start the configured harness in the current tmux pane and register the session. Ensures a session UUID exists in frontmatter, registers the pane in sessions.json, then runs the harness under the supervisor restart loop. Route-created panes use an internal one-shot mode so successful fresh cycles close the pane automatically; manually started panes remain persistent.

If the YAML frontmatter is malformed, start now fails with a file-targeted error that includes a compiler-style frontmatter excerpt with a caret at the reported line/column, then tells you to fix the --- ... --- block before retrying. The sync/auto-start path also mirrors the same warning into the document's agent:status component when present, so editor-driven auto-start failures are visible even when no tmux pane appears.

claim

agent-doc claim <FILE>

Claim a document for the current tmux pane. Reads the session UUID from frontmatter and $TMUX_PANE, then updates sessions.json. Unlike start, does not launch Claude — use this when you're already inside a Claude session.

Last-call-wins: a subsequent claim for the same file overrides the previous pane mapping. Multiple files can be claimed for the same pane.

Also available as a Claude Code skill: /agent-doc claim <FILE>.

prompt

agent-doc prompt <FILE>
agent-doc prompt --all
agent-doc prompt --answer N <FILE>

Detect permission prompts from a Claude Code session by capturing tmux pane content.

Flag	Description
(none)	Detect prompts for a single file
`--all`	Poll all live sessions, return JSON array
`--answer N`	Answer prompt by selecting option N (1-based)

commit

agent-doc commit <FILE>

Git add + commit with an auto-generated agent-doc: YYYY-MM-DD HH:MM:SS timestamp message.

compact

agent-doc compact <FILE> [--component exchange] [--message TEXT] [--keep N] [--commit]

Archive old exchange/component content and rewrite the document atomically. Use --commit to close out through the binary-owned agent-doc commit path so editor VCS refresh signaling also runs.

skill

agent-doc skill install
agent-doc skill check

Manage the Claude Code skill definition.

Subcommand	Description
`install`	Write the bundled SKILL.md to `.claude/skills/agent-doc/SKILL.md`. Idempotent.
`check`	Compare installed skill vs bundled version. Exit 0 if up to date, exit 1 if outdated.

The skill content is embedded in the binary at build time. After agent-doc upgrade, run agent-doc skill install in each project to update the skill definition.

patch

agent-doc patch <FILE> <COMPONENT> [CONTENT]

Replace content in a named component. Components are bounded regions marked with ....

Argument	Description
`FILE`	Path to the document
`COMPONENT`	Component name (e.g., `status`, `log`)
`CONTENT`	Replacement content (reads from stdin if omitted)

Behavior depends on .agent-doc/components.toml config:

Config	Default	Description
`mode`	`replace`	`replace`, `append`, or `prepend`
`timestamp`	`false`	Auto-prefix with ISO timestamp
`max_entries`	`0`	Trim entries in append/prepend (0 = unlimited)
`pre_patch`	none	Shell hook: transform content (stdin → stdout)
`post_patch`	none	Shell hook: fire-and-forget after write

See Components for full configuration and hook documentation.

watch

agent-doc watch [--stop] [--status] [--debounce MS] [--max-cycles N]

Watch session files for changes and auto-submit.

Flag	Default	Description
`--stop`		Stop the running watch daemon
`--status`		Show daemon status
`--debounce`	`500`	Debounce delay in milliseconds
`--max-cycles`	`3`	Max agent-triggered cycles per file before pausing

The daemon watches all claimed files (from sessions.json), debounces per-file, and triggers agent-doc run on changes. PID stored in .agent-doc/watch.pid.

Loop prevention: bounded cycles (default 3) and convergence detection (stop if agent response matches previous). See Dashboard-as-Document for the full workflow.

memory

agent-doc memory index <FILE> [--db PATH] [--json]
agent-doc memory search <FILE> --query TEXT [--db PATH] [--limit N] [--json] [--rebuild]

Index and search session memory from agent:backlog, agent:review, agent:done (including archive= files), agent:icebox, and live exchange ### Re: sections. The default store is <project>/.tsift/memory.db, using the shared tsift-memory library crate rather than shelling out to the tsift CLI.

upgrade

agent-doc upgrade

Check GitHub Releases for the latest version and upgrade. Tries the prebuilt GitHub binary first, then pip install --upgrade.

Global flags

agent-doc --version    # Print version
agent-doc --help       # Show help