# 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:
1. Compute diff from snapshot
2. Build prompt (diff + full document)
3. Pre-commit user changes (unless `--no-git`)
4. Send to agent
5. Append response as `## Assistant` block
6. 3-way merge if file was edited during response
7. 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 `<!-- agent:name -->...<!-- /agent:name -->`.

| 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](components.md) 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](dashboard.md) 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
```
