{"id":"1de45e48-d8a2-4b2d-b3d0-6a5e2917a9e1","slug":"btakita-agent-doc","kind":"skill","name":"agent-doc","summary":"Interactive document sessions with AI agents","owner":"btakita","repoUrl":"https://github.com/btakita/agent-doc","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":6,"match":null,"fewStars":false,"format":"skill","createdAt":"2026-02-23T16:35:53.000Z","addedAt":"2026-10-21T16:53:06.105Z","logoUrl":"https://avatars.githubusercontent.com/u/3664?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["files-documents"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T15:08:21.078Z","sample":false,"url":"https://conduits.dev/tools/btakita-agent-doc","language":"Rust","transports":["stdio"],"install":{"pypi":"agent-doc"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# agent-doc\n\n**Your markdown document is the conversation.**\n\nagent-doc turns an ordinary markdown file into a live session with an AI coding\nagent. You write in the document, press a hotkey (or just keep typing), and the\nagent reads what you changed and writes its answer back into the same file.\nNothing scrolls away: you can reorganize, annotate, and prune the conversation\nlike any other document, and every turn is committed to git.\n\n> **Alpha software.** Actively developed; commands and frontmatter may change\n> between versions. **Single-user only**: use a private git repository (see\n> [Security](#security)).\n\n## Getting started\n\nFrom a clean machine to your first agent turn. Each step links to the full\nguide if you need more.\n\n**You need:** `git`, `tmux`, and one agent CLI that already works on its own\nin a terminal: [Claude Code](https://docs.anthropic.com/en/docs/claude-code)\n(`claude`), Codex, Grok Build, or OpenCode. agent-doc drives that agent; it does\nnot replace it or hold your API keys.\n\n**1. Install the CLI.**\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/btakita/agent-doc/main/install.sh | sh\nagent-doc --version\n```\n\n`pip install agent-doc` and `brew install btakita/tap/agent-doc` also work. If\nthe installer prints a `PATH` note, add that line to your shell profile. See\n[Installation](docs/getting-started/installation.md).\n\n**2. Set up your project** (any git repository):\n\n```sh\ncd your-project\nagent-doc init\nagent-doc skill install --harness claude   # or: codex, grok, opencode, --all\n```\n\n`agent-doc init` creates `.agent-doc/` (local runtime state: add it to\n`.gitignore`) plus `runbooks/` and `okf/` reference files for the agent.\n`skill install` teaches your agent the agent-doc workflow by writing its\ninstructions where that agent looks, for example `.claude/skills/agent-doc/`\nfor Claude Code. Run `skill install` with your harness even if `init` already\ninstalled one: from a plain terminal, `init` cannot tell which agent you use.\nThe instruction files are regenerated on upgrade; commit them if teammates use\nagent-doc in the same repository.\n\n**3. Optional: add the editor plugin.**\n\n```sh\nagent-doc plugin install jetbrains   # or: vscode\n```\n\nRestart the IDE if it asks you to. The plugin gives you a **Run Agent Doc** action,\nlive merging while the agent writes, and highlighting. Without a plugin,\neverything below still works from a terminal. See\n[Editor Integration](docs/guide/editor-integration.md).\n\n**4. Create your first session document.**\n\n```sh\nagent-doc init notes.md \"My Topic\"\n```\n\nOpen `notes.md` and write a request at the end, under `## User`. For example,\n\"Summarize what this repository does.\"\n\n**5. Run the first turn.** Pick whichever fits how you work:\n\n| Where you are | What to do |\n|---|---|\n| Your agent (Claude Code, OpenCode) | type `/agent-doc notes.md` |\n| Your agent (Codex, Grok Build) | type `agent-doc notes.md` as a normal message |\n| JetBrains / VS Code with the plugin | run **Run Agent Doc** (JetBrains) or **Agent Doc: Run (Submit)** (VS Code) on the file |\n| A terminal | `agent-doc run notes.md` for one headless turn, or `agent-doc start notes.md` for a long-lived agent pane in tmux |\n\nThe answer is written into `notes.md` as a `## Assistant` block and the turn is\ncommitted to git. Add another `## User` block below it and run again; that is\nthe whole loop. `agent-doc run notes.md --dry-run` shows what the agent would\nreceive without sending anything.\n\n**What the markers mean.** `<!-- agent:NAME -->` ... `<!-- /agent:NAME -->`\npairs are named sections (components) that agent-doc reads and patches, such as\n`agent:exchange` for the conversation or `agent:run` for a work queue. You do\nnot need any for a first session. The icons agent-doc adds to queue items are\nexplained under [Queue attributes](docs/reference/tags-and-attributes.md#queue-attributes).\nSee [Document Format](docs/guide/document-format.md) and\n[Components](docs/guide/components.md) for the full layout.\n\n**If something goes wrong:** `agent-doc version` shows which binary, native\nlibrary, and plugin versions are in use, and `agent-doc env` reports what\nagent-doc sees of your terminal and tmux. A step-by-step version of this path,\nwith troubleshooting, lives in the\n[Quick Start](docs/getting-started/quick-start.md).\n\n## Why a document?\n\nTerminal chats are ephemeral. A document is a workspace you curate:\n\n- **Edits are the prompt.** agent-doc diffs the document against the last turn,\n  so the agent sees exactly what you added, changed, or deleted, including\n  inline notes on its own earlier answers.\n- **Work queues up.** Drop several requests into an `agent:run` section and\n  the agent drains them one by one; track follow-ups in `agent:backlog`.\n- **You can keep typing.** Edits made while the agent works merge safely with\n  its writes in real time, inside your editor, without clobbering your cursor\n  or undo history.\n- **History is real history.** Every turn is a git commit you can diff, revert,\n  or squash.\n\n## How it works\n\n1. You edit a session document (a markdown file with agent-doc frontmatter).\n2. A hotkey, your editor plugin, or your agent harness triggers a turn.\n3. agent-doc computes the diff since the last turn and hands it to the agent,\n   which runs in its own tmux pane.\n4. The agent's response is written back into the document (appended, or patched\n   into named sections like `agent:exchange`), and the cycle is committed.\n\nThe Rust binary owns every deterministic step (diffing, merging, routing, git);\nthe bundled skill instructions tell the agent how to take part. See\n[Architecture](docs/reference/architecture.md) for the full picture.\n\n## Works with\n\n**Editors**\n\n| Editor | Integration |\n|--------|-------------|\n| JetBrains IDEs (IntelliJ IDEA, Rider, PyCharm, and other IntelliJ-platform IDEs) | Plugin: `agent-doc plugin install jetbrains`, or the JetBrains Marketplace |\n| VS Code | Extension: `agent-doc plugin install vscode`, or the VS Code Marketplace |\n| Zed | Dev extension in [`editors/zed`](editors/zed/README.md) |\n| 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) |\n\nThe plugins add realtime sync, tmux layout mirroring (one pane per visible\ndocument), and highlighting for agent-doc structures. See\n[Editor Integration](docs/guide/editor-integration.md).\n\n**Agent harnesses**\n\n| Harness | How you start a turn |\n|---------|---------------------|\n| Claude Code | `/agent-doc <file>` |\n| Codex | `agent-doc <file>` as a normal message |\n| Grok Build | `agent-doc <file>` as a normal message (uses the installed MCP server) |\n| OpenCode | `/agent-doc <file>` |\n\n`agent-doc skill install --harness <claude|codex|grok|opencode>` installs the\nmatching instructions (or `--all` for every harness; Cursor rules and a generic\ntarget are also available). To pick which agent a document's pane runs, set\n`agent:` in its frontmatter (`claude`, `codex`, `grok`, or `opencode`). See [Agent Backends](docs/guide/agent-backends.md).\n\n## Queue markers\n\nagent-doc prefixes each row in an `agent:run` section with its state:\n\n| Marker | Meaning |\n|--------|---------|\n| `📥` | pending, ready to run |\n| `🟡` | claimed for a worker that has not started yet |\n| `🚧` | a worker is running it |\n| `☑️` | the worker reported back; the coordinator still has to integrate and close it |\n| `⚠️` | lost: the claim expired; it can be reclaimed |\n| `🔄` | needs reconcile: there is finished-work evidence but no current claim; it is not dispatched again |\n| `❔` | unknown: the state is unreadable or contradicts the row |\n| `⏭️` | skipped this pass |\n| `⏳` | waiting on an operator verdict |\n| `🙋` | an operator request is open for the row |\n| `📌` / `📍` | operator / agent priority pin |\n\nA session document with an `agent:run` section keeps this legend on one line\nat the end of its `agent:status` section (hide it with `queue-legend=off` on\nthe status marker), and `agent-doc queue --help` prints it. See\n[Queue Markers](docs/guide/queue-markers.md#queue-markers) for the full legend,\nincluding the `[#owner#N]` and `⟦effect:N⟧` annotations.\n\n## Learn more\n\n- [Documentation home](docs/README.md) (also built as an mdBook)\n- [Document Format](docs/guide/document-format.md) and\n  [Components](docs/guide/components.md): frontmatter, `agent:` sections, queue\n  and backlog\n- [Tags and Opening-Marker Attributes](docs/reference/tags-and-attributes.md):\n  complete `agent:*`, response patch, boundary, and attribute reference\n- [Commands](docs/guide/commands.md) and [Configuration](docs/getting-started/configuration.md)\n- [Tmux Routing and Navigation Lanes](docs/guide/tmux-routing.md): multi-pane\n  tmux setups, remote workspaces, and two IDEs on one project\n- [Feature Catalog](docs/reference/features.md): the detailed capability ledger\n- [Architecture](docs/reference/architecture.md): binary vs. skill\n  responsibilities and the domain ontology\n- [SPEC.md](SPEC.md) and [`specs/`](specs/07-commands.md): the functional\n  specification\n\n## Security\n\nagent-doc is designed for **single-user, local operation**. Documents,\nsnapshots, and exchange history live on your filesystem and are committed to a\ngit repository.\n\n- **Single user only.** There is no multi-user access control, authentication,\n  or session isolation.\n- **Use a private repo.** Session documents may contain sensitive content\n  (correspondence, research, credentials in context).\n- **Prompt injection risk.** Content pasted from emails, web pages, or chat logs\n  could contain prompt injection. The agent treats all document content as user\n  input, with no injection scanning.\n- **`--dangerously-skip-permissions` exposure.** With this flag (common in\n  agent-doc sessions) the agent has full filesystem access, so injected prompts\n  could read files or run commands if not sandboxed.\n- **The shared-doc guard is an audit marker, not auth.** Documents may opt into\n  `agent_doc_collaboration: shared`; then cross-document `extract` / `transfer`\n  and plan-backed `do #id` work that references another `.md` file fail closed\n  unless the document also carries `agent_doc_security_review: <review-id>`.\n\n**Planned:** collaborative security for web/networked deployments (multi-user\naccess control, session isolation, content scanning, compartmented access).\n\n## License\n\nLicensed under the [Apache License, Version 2.0](LICENSE) (`Apache-2.0`).\n"}