Configuration

Config file

Location: ~/.config/agent-doc/config.toml

default_agent = "claude"
tmux_bin = "/opt/tmux/bin/tmux"

[agents.claude]
command = "claude"
args = ["-p", "--output-format", "json"]
result_path = ".result"
session_path = ".session_id"

[agents.codex]
command = "codex"
args = ["--prompt"]
result_path = ".output"
session_path = ".id"

[agents.opencode]
command = "opencode"
args = ["run"]

[terminal]
host = "auto"
auto_start_tmux = true
# command = "wezterm start -- {tmux_command}"
# attach_command = "tmux attach-session -t {session}"

Fields

Resolution order

The agent backend is resolved in this order:

1. --agent CLI flag
2. agent: field in document frontmatter
3. default_agent in config
4. Fallback: "claude"

Per-document overrides

Set agent and model in the document’s YAML frontmatter:

---
session: null
agent: opencode
opencode_model: zai/glm-5
---

These override the config file for that specific document.

terminal_host: auto|ide|external|none may also be set in document frontmatter. Its precedence is document, project, global, then auto. The other terminal fields use project then global precedence. Terminal configuration does not contain a session name: use project tmux_session / agent-doc session set. The tmux executable uses project tmux_bin, then global tmux_bin, then PATH; agent-doc env --json reports the selected binary and its source. See the Coder workspace terminal runbook for remote IDE setup and headless failure behavior.

To dogfood Agent Doc itself, opt a document into typed, deduplicated findings:

---
dogfood:
  path: tasks/agent-doc/agent-doc-bugs.md
  auto: true
  prompt: >-
    File a GitHub issue with the diagnostic instead of changing code.
---

path is project-relative and defaults to the current document. auto defaults to false; when true, only generated stable-keyed findings are queued. The same typed value may be set in .agent-doc/project.md, while session frontmatter wins. dogfood: false disables inheritance and absence everywhere is off. prompt optionally replaces the default “diagnose and fix” action while keeping the stable issue metadata and retained-write safety guidance. Blank prompts use the default action, and map fields do not merge across precedence layers. agent-doc dogfood policy <FILE> --json shows the effective destination and auto-queue setting plus any custom prompt after applying that precedence. Watchers use this typed query instead of parsing either document themselves. Set a document-local policy without editing live frontmatter directly:

agent-doc dogfood set tasks/session.md
agent-doc dogfood set tasks/session.md \
  --path tasks/agent-doc/agent-doc-bugs.md --auto true \
  --prompt 'File a GitHub issue with the diagnostic instead of changing code.'

The first form targets the current document with auto: false. The second path is relative to the project root. The command changes only the public dogfood: frontmatter field through editor-aware document authority and preserves all other frontmatter and body bytes. Invariant diagnosis and uniquely-safe projection repair remain on regardless.

To opt a document into retained-write-owned terminal convergence:

---
agent_doc_per_component_convergence: true
---

The same experiment can be enabled project-wide in .agent-doc/config.toml with agent_doc_per_component_convergence = true. It is off by default. When enabled, an operator edit in an unowned component such as agent:queue does not block an agent response that owns only agent:exchange. Invalid or legacy ownership evidence falls back to whole-document equality.

Environment Variables

Runtime Tuning

Harness Detection

These are read by detect_harness() to identify the active agent harness:

Harness Arg Overrides

Vision

Testing / Debug

Probe Markers

Set by child processes to confirm capability proofs:

Project Config

Location: .agent-doc/config.toml (relative to project root).

Project-wide prompt presets

Project-wide prompt presets do not go in .agent-doc/config.toml. After initializing the project with agent-doc init, create or edit .agent-doc/project.md and define presets in its YAML frontmatter:

---
presets:
  "#review": Review the change and run focused tests.
  "#release":
    prompt: Prepare and publish the release.
    runbook: runbooks/release.md
---

# Agent Doc project defaults

Quote names that begin with #; otherwise YAML treats the rest of the key as a comment. prompt_presets: is accepted as an alias for presets:.

Invoke a preset by adding its name to a session prompt or queue, for example #review in agent:exchange or - #review in agent:queue. Every ancestor .agent-doc/project.md supplies live defaults within the configured root ceiling. A nested project’s values overlay its parent’s values, and a session document can override either by defining the same exact name in its own frontmatter. Relative runbook paths resolve from the project root and are loaded only when the preset is invoked.

See Document Format for the full inheritance and masking rules.

To publish each newly created closeout commit to the current branch’s configured upstream, opt in explicitly:

[commit]
push = "ff-only"

The push uses an explicit HEAD:<upstream-branch> refspec, disables force, mirror, tag, and recursive-submodule modes, and runs only after the local closeout transaction succeeds. A missing upstream, non-fast-forward rejection, or transport failure is logged as an advisory warning; the local committed cycle remains valid.

SSH Config

[ssh.profiles.production]
targets = ["host1", "host2"]

[ssh.docs."ops/deploy.md"]
profile = "production"

Component Config

Inline component attributes override defaults:

<!-- agent:exchange patch=append max_lines=50 -->