agent-doc

Your markdown document is the conversation.

agent-doc turns an ordinary markdown file into a live session with an AI coding agent. You write in the document, press a hotkey (or just keep typing), and the agent reads what you changed and writes its answer back into the same file. Nothing scrolls away: you can reorganize, annotate, and prune the conversation like any other document, and every turn is committed to git.

Alpha software. Actively developed; commands and frontmatter may change between versions. Single-user only: use a private git repository (see Security).

Getting started

From a clean machine to your first agent turn. Each step links to the full guide if you need more.

You need: git, tmux, and one agent CLI that already works on its own in a terminal: Claude Code (claude), Codex, Grok Build, or OpenCode. agent-doc drives that agent; it does not replace it or hold your API keys.

1. Install the CLI.

curl -fsSL https://raw.githubusercontent.com/btakita/agent-doc/main/install.sh | sh
agent-doc --version

pip install agent-doc and brew install btakita/tap/agent-doc also work. If the installer prints a PATH note, add that line to your shell profile. See Installation.

2. Set up your project (any git repository):

cd your-project
agent-doc init
agent-doc skill install --harness claude   # or: codex, grok, opencode, --all

agent-doc init creates .agent-doc/ (local runtime state: add it to .gitignore) plus runbooks/ and okf/ reference files for the agent. skill install teaches your agent the agent-doc workflow by writing its instructions where that agent looks, for example .claude/skills/agent-doc/ for Claude Code. Run skill install with your harness even if init already installed one: from a plain terminal, init cannot tell which agent you use. The instruction files are regenerated on upgrade; commit them if teammates use agent-doc in the same repository.

3. Optional: add the editor plugin.

agent-doc plugin install jetbrains   # or: vscode

Restart the IDE if it asks you to. The plugin gives you a Run Agent Doc action, live merging while the agent writes, and highlighting. Without a plugin, everything below still works from a terminal. See Editor Integration.

4. Create your first session document.

agent-doc init notes.md "My Topic"

Open notes.md and write a request at the end, under ## User. For example, "Summarize what this repository does."

5. Run the first turn. Pick whichever fits how you work:

The answer is written into notes.md as a ## Assistant block and the turn is committed to git. Add another ## User block below it and run again; that is the whole loop. agent-doc run notes.md --dry-run shows what the agent would receive without sending anything.

What the markers mean. <!-- agent:NAME --> ... <!-- /agent:NAME --> pairs are named sections (components) that agent-doc reads and patches, such as agent:exchange for the conversation or agent:run for a work queue. You do not need any for a first session. The icons agent-doc adds to queue items are explained under Queue attributes. See Document Format and Components for the full layout.

If something goes wrong: agent-doc version shows which binary, native library, and plugin versions are in use, and agent-doc env reports what agent-doc sees of your terminal and tmux. A step-by-step version of this path, with troubleshooting, lives in the Quick Start.

Why a document?

Terminal chats are ephemeral. A document is a workspace you curate:

• Edits are the prompt. agent-doc diffs the document against the last turn, so the agent sees exactly what you added, changed, or deleted, including inline notes on its own earlier answers.
• Work queues up. Drop several requests into an agent:run section and the agent drains them one by one; track follow-ups in agent:backlog.
• You can keep typing. Edits made while the agent works merge safely with its writes in real time, inside your editor, without clobbering your cursor or undo history.
• History is real history. Every turn is a git commit you can diff, revert, or squash.

How it works

1. You edit a session document (a markdown file with agent-doc frontmatter).
2. A hotkey, your editor plugin, or your agent harness triggers a turn.
3. agent-doc computes the diff since the last turn and hands it to the agent, which runs in its own tmux pane.
4. The agent's response is written back into the document (appended, or patched into named sections like agent:exchange), and the cycle is committed.

The Rust binary owns every deterministic step (diffing, merging, routing, git); the bundled skill instructions tell the agent how to take part. See Architecture for the full picture.

Works with

Editors

The plugins add realtime sync, tmux layout mirroring (one pane per visible document), and highlighting for agent-doc structures. See Editor Integration.

Agent harnesses

agent-doc skill install --harness <claude|codex|grok|opencode> installs the matching instructions (or --all for every harness; Cursor rules and a generic target are also available). To pick which agent a document's pane runs, set agent: in its frontmatter (claude, codex, grok, or opencode). See Agent Backends.

Queue markers

agent-doc prefixes each row in an agent:run section with its state:

A session document with an agent:run section keeps this legend on one line at the end of its agent:status section (hide it with queue-legend=off on the status marker), and agent-doc queue --help prints it. See Queue Markers for the full legend, including the [#owner#N], ⟦blocked by …⟧ and ⟦effect:N⟧ annotations. Completed queue rows also retain ⟦addressed-at:…⟧; supported editors rank the newest three as ①/②/③ with graded, caret-dismissible highlights.

Learn more

• Documentation home (also built as an mdBook)
• Document Format and Components: frontmatter, agent: sections, queue and backlog
• Tags and Opening-Marker Attributes: complete agent:*, response patch, boundary, and attribute reference
• Commands and Configuration
• Tmux Routing and Navigation Lanes: multi-pane tmux setups, remote workspaces, and two IDEs on one project
• Feature Catalog: the detailed capability ledger
• Architecture: binary vs. skill responsibilities and the domain ontology
• SPEC.md and specs/: the functional specification

Security

agent-doc is designed for single-user, local operation. Documents, snapshots, and exchange history live on your filesystem and are committed to a git repository.

• Single user only. There is no multi-user access control, authentication, or session isolation.
• Use a private repo. Session documents may contain sensitive content (correspondence, research, credentials in context).
• Prompt injection risk. Content pasted from emails, web pages, or chat logs could contain prompt injection. The agent treats all document content as user input, with no injection scanning.
• --dangerously-skip-permissions exposure. With this flag (common in agent-doc sessions) the agent has full filesystem access, so injected prompts could read files or run commands if not sandboxed.
• The shared-doc guard is an audit marker, not auth. Documents may opt into agent_doc_collaboration: shared; then cross-document extract / transfer and plan-backed do #id work that references another .md file fail closed unless the document also carries agent_doc_security_review: <review-id>.

Planned: collaborative security for web/networked deployments (multi-user access control, session isolation, content scanning, compartmented access).

License

Licensed under the Apache License, Version 2.0 (Apache-2.0).