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).
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:queuesection and the agent drains them one by one; track follow-ups inagent: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
- You edit a session document (a markdown file with agent-doc frontmatter).
- A hotkey, your editor plugin, or your agent harness triggers a turn.
- agent-doc computes the diff since the last turn and hands it to the agent, which runs in its own tmux pane.
- 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
| Editor | Integration |
|---|---|
| JetBrains IDEs (IntelliJ IDEA, Rider, PyCharm, and other IntelliJ-platform IDEs) | Plugin: agent-doc plugin install jetbrains, or the JetBrains Marketplace |
| VS Code | Extension: agent-doc plugin install vscode, or the VS Code Marketplace |
| Zed | Dev extension in editors/zed |
| No editor plugin | Drive sessions directly from your agent harness, or bind agent-doc run <file> to a hotkey in any editor (Vim/Neovim included) |
The plugins add realtime sync, tmux layout mirroring (one pane per visible document), and highlighting for agent-doc structures. See Editor Integration.
Agent harnesses
| Harness | How you start a turn |
|---|---|
| Claude Code | /agent-doc <file> |
| Codex | agent-doc <file> as a normal message |
| Grok Build | agent-doc <file> as a normal message (uses the installed MCP server) |
| OpenCode | /agent-doc <file> |
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.
Install
curl -fsSL https://raw.githubusercontent.com/btakita/agent-doc/main/install.sh | sh
Or pip install agent-doc, brew install btakita/tap/agent-doc, or a prebuilt
binary from GitHub Releases.
Then add your editor plugin and harness instructions:
agent-doc plugin install jetbrains # or: vscode
agent-doc skill install --harness claude # or: codex, grok, opencode, --all
agent-doc's managed sessions run agents in tmux, so install tmux too.
Source builds, PyPI bootstrap details, Windows, and upgrades are covered in
Installation.
Your first session
cd your-project
agent-doc init # set up .agent-doc/ for this project
agent-doc init notes.md "My Topic" # scaffold a session document
Open notes.md, write a request, and start a turn:
- From an editor plugin: run Run Agent Doc (JetBrains) or Agent Doc: Run (Submit) (VS Code) on the file. agent-doc starts (or reuses) the document's agent pane and sends the turn.
- From your harness: type
/agent-doc notes.mdin Claude Code or OpenCode, oragent-doc notes.mdin Codex or Grok Build. - From a terminal:
agent-doc start notes.mdopens a managed agent pane for the document, andagent-doc run notes.mdruns a single headless turn.
The response lands in notes.md. Keep writing below it and run again. For a
guided tour, see the Quick Start; for
multi-pane tmux setups, remote workspaces, and running two IDEs on one project,
see Tmux Routing and Navigation Lanes.
Learn more
- Documentation home (also built as an mdBook)
- Document Format and
Components: frontmatter,
agent:sections, queue and backlog - Commands and Configuration
- 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-permissionsexposure. 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-documentextract/transferand plan-backeddo #idwork that references another.mdfile fail closed unless the document also carriesagent_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).
1 maintainer
Metadata
1 maintainer
Release files for agent-doc 0.35.496
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| agent_doc-0.35.496-py3-none-any.whl | Python 3 | none | any | Details |
Release files / agent_doc-0.35.496-py3-none-any.whl
| Download URL | agent_doc-0.35.496-py3-none-any.whl |
|---|---|
| Size | 12.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1fb597c495232089ae66674afaf2d69185f6a31995831584c3bfc5943b3bc329
|
|
BLAKE2b-256 checksum How to use checksums |
8add4c11d166b25e5e6fa771813447f25499a30d77d95f08d3258958dac3ae6c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency log
