agent-doc 0.31.19__py3-none-win_amd64.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
Binary file
|
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agent-doc
|
|
3
|
+
Version: 0.31.19
|
|
4
|
+
Classifier: Development Status :: 3 - Alpha
|
|
5
|
+
Classifier: Environment :: Console
|
|
6
|
+
Classifier: Topic :: Software Development :: Documentation
|
|
7
|
+
Summary: Interactive document sessions with AI agents
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
Requires-Python: >=3.8
|
|
10
|
+
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
|
|
11
|
+
Project-URL: Documentation, https://btakita.github.io/agent-doc
|
|
12
|
+
Project-URL: Homepage, https://github.com/btakita/agent-doc
|
|
13
|
+
|
|
14
|
+
# agent-doc
|
|
15
|
+
|
|
16
|
+
Interactive document sessions with AI agents.
|
|
17
|
+
|
|
18
|
+
Edit a markdown file, press a hotkey, and the tool diffs your changes, sends them to an AI agent, and writes the response back into the document. The document is the UI.
|
|
19
|
+
|
|
20
|
+
> **Alpha Software** — actively developed; APIs and frontmatter format may change between versions.
|
|
21
|
+
|
|
22
|
+
> **Single-user only.** agent-doc operates on the local filesystem with no access control. Use a private git repository. See the [Security](#security) section for details.
|
|
23
|
+
|
|
24
|
+
## Install
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
curl -fsSL https://raw.githubusercontent.com/btakita/agent-doc/main/install.sh | sh
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
**Alternatives:**
|
|
31
|
+
|
|
32
|
+
```sh
|
|
33
|
+
# From crates.io
|
|
34
|
+
cargo install agent-doc
|
|
35
|
+
|
|
36
|
+
# From PyPI
|
|
37
|
+
pip install agent-doc
|
|
38
|
+
|
|
39
|
+
# From source
|
|
40
|
+
cargo build --release
|
|
41
|
+
cargo install --path .
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Quick Start
|
|
45
|
+
|
|
46
|
+
```sh
|
|
47
|
+
# 1. Initialize project (creates .agent-doc/ and installs SKILL.md)
|
|
48
|
+
agent-doc init
|
|
49
|
+
|
|
50
|
+
# 2. Scaffold a session document
|
|
51
|
+
agent-doc init session.md "My Topic"
|
|
52
|
+
|
|
53
|
+
# 3. Claim the document to the current tmux pane
|
|
54
|
+
agent-doc claim session.md
|
|
55
|
+
|
|
56
|
+
# 4. Route hotkey triggers to the correct tmux pane
|
|
57
|
+
agent-doc route session.md
|
|
58
|
+
|
|
59
|
+
# 5. Run: diff, send to agent, write response back
|
|
60
|
+
agent-doc run session.md
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
The typical edit cycle: write in your editor, trigger `agent-doc route <file>` via a hotkey, the agent responds in the same document.
|
|
64
|
+
|
|
65
|
+
## Key Features
|
|
66
|
+
|
|
67
|
+
- **Template mode** — named component regions (`<!-- agent:name -->`) updated independently; inline attrs (`patch=`, `max_lines=`) > `components.toml` > built-in defaults
|
|
68
|
+
- **CRDT merge** — yrs-based conflict-free merge for concurrent edits between agent writes and user edits
|
|
69
|
+
- **IPC-first writes** — socket IPC (Unix domain sockets); editor plugin receives JSON patches instead of file overwrites; preserves cursor position, undo history, and avoids "externally modified" dialogs
|
|
70
|
+
- **Tmux routing** — persistent Claude Code sessions per document; `route` dispatches to the correct pane or auto-starts one; reconciler always runs (no early exits) handling 0/1/2+ panes uniformly
|
|
71
|
+
- **Streaming** — real-time CRDT write-back loop (`agent-doc stream`) with optional chain-of-thought routing
|
|
72
|
+
- **Parallel fan-out** — independent git worktrees per subtask, each with its own Claude session (`agent-doc parallel`)
|
|
73
|
+
- **Editor plugins** — JetBrains and VS Code plugins for hotkey integration and IPC writes
|
|
74
|
+
- **Watch daemon** — auto-submit on file change with debounce and reactive mode for stream documents
|
|
75
|
+
- **Linked resources** — `links` frontmatter field for local files and URLs; URL content fetched, converted HTML→markdown via `htmd`, cached, and diffed on each preflight
|
|
76
|
+
- **Session logging** — persistent logs at `.agent-doc/logs/<session-uuid>.log` for debugging session crashes and restarts
|
|
77
|
+
- **Git integration** — auto-commit each run; squash history with `agent-doc clean`
|
|
78
|
+
- **Bulk resync** — validates session state and fixes stale/orphaned panes in 2 subprocess calls instead of ~20-40; `--fix --session <name>` relocates WrongSession panes via join-pane instead of killing them
|
|
79
|
+
- **Column memory** — `.agent-doc/last_layout.json` remembers column→agent-doc mapping; preserves 2-pane tmux layout when one editor column switches to a non-agent file
|
|
80
|
+
- **Stash + rescue** — replaced panes are stashed (alive in background); stash rescue brings them back when the user switches to that document again
|
|
81
|
+
- **Startup lock** — `.agent-doc/starting/<hash>.lock` with 5s TTL prevents double-spawn when sync fires twice in quick succession
|
|
82
|
+
- **Component-aware baseline guard** — detects stale baselines by comparing append-mode components only; user edits to replace-mode components (status, pending) don't trigger false positives
|
|
83
|
+
- **Hook system** — cross-session event coordination via `agent-doc hook fire/poll/listen/gc`; integrates with Claude Code hooks via `PostToolUse` bridge
|
|
84
|
+
- **Slash command dispatch** — `preflight` extracts slash commands from user-added diff lines (`parse_slash_commands`); the SKILL executes them before responding; guards exclude code fences, blockquotes, and non-added lines
|
|
85
|
+
- **Dedupe stale patch cleanup** — after removing duplicate blocks, `dedupe` also deletes the stale `.agent-doc/patches/<hash>.json` to prevent the plugin's startup scan from re-applying removed content
|
|
86
|
+
|
|
87
|
+
## Architecture
|
|
88
|
+
|
|
89
|
+
The binary owns all deterministic behavior: component parsing, patch application, CRDT merge, snapshot management, git operations, tmux routing, and IPC writes. The SKILL.md Claude Code skill is the non-deterministic orchestrator — it reads the diff, generates responses, and decides what to write.
|
|
90
|
+
|
|
91
|
+
**Binary vs. Agent Responsibility:**
|
|
92
|
+
|
|
93
|
+
| Responsibility | Owner | Why |
|
|
94
|
+
|---------------|-------|-----|
|
|
95
|
+
| Component parsing, patch application, mode resolution | **Binary** (Rust) | Deterministic, testable, consistent across agents |
|
|
96
|
+
| CRDT merge, snapshot management, atomic writes | **Binary** (Rust) | Concurrency safety requires flock + atomic rename |
|
|
97
|
+
| Diff computation, comment stripping, truncation detection | **Binary** (Rust) | Reproducible baseline comparison |
|
|
98
|
+
| Git operations (commit, history, clean) | **Binary** (Rust) | Direct `std::process::Command` calls |
|
|
99
|
+
| Tmux routing, session registry, pane management | **Binary** (Rust) | Process-level coordination |
|
|
100
|
+
| Pre-response snapshots, undo, extract, transfer | **Binary** (Rust) | File-level atomicity |
|
|
101
|
+
| Boundary marker lifecycle (insert, reposition, cleanup) | **Binary** (Rust) | Deterministic, all write paths need it |
|
|
102
|
+
| Reading diff, interpreting user intent | **Skill** (SKILL.md) | Requires LLM reasoning |
|
|
103
|
+
| Generating response content | **Skill** (SKILL.md) | Non-deterministic |
|
|
104
|
+
| Deciding what to write to which component | **Skill** (SKILL.md) | Context-dependent |
|
|
105
|
+
| Streaming checkpoints, progress tracking | **Skill** (SKILL.md) | Response-generation timing |
|
|
106
|
+
| Pending item management (parse, populate, process) | **Skill** (SKILL.md) | Semantic understanding of prompts |
|
|
107
|
+
|
|
108
|
+
See [CLAUDE.md](CLAUDE.md) for the full module layout, stream mode details, and release process.
|
|
109
|
+
|
|
110
|
+
## Supported Editors
|
|
111
|
+
|
|
112
|
+
**JetBrains (IntelliJ, PyCharm, etc.)**
|
|
113
|
+
|
|
114
|
+
```sh
|
|
115
|
+
agent-doc plugin install jetbrains
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Or install from JetBrains Marketplace. Configure an External Tool: Program=`agent-doc`, Args=`run $FilePath$`, Working dir=`$ProjectFileDir$`. Assign a keyboard shortcut.
|
|
119
|
+
|
|
120
|
+
**VS Code**
|
|
121
|
+
|
|
122
|
+
```sh
|
|
123
|
+
agent-doc plugin install vscode
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Or install from the VS Code Marketplace. Add a task with `"command": "agent-doc run ${file}"` and bind it to a keybinding.
|
|
127
|
+
|
|
128
|
+
**Vim/Neovim**
|
|
129
|
+
|
|
130
|
+
```vim
|
|
131
|
+
nnoremap <leader>as :!agent-doc run %<CR>:e<CR>
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## Domain Ontology
|
|
135
|
+
|
|
136
|
+
agent-doc extends the [existence kernel vocabulary](https://github.com/btakita/existence-lang) with domain-specific terms.
|
|
137
|
+
|
|
138
|
+
### Document Lifecycle
|
|
139
|
+
|
|
140
|
+
| Term | Definition |
|
|
141
|
+
|------|-----------|
|
|
142
|
+
| **Session** | A persistent conversation between a user and an agent, identified by UUID. Stored in frontmatter as `agent_doc_session`. |
|
|
143
|
+
| **Document** | A markdown file that serves as the UI for a session. Contains frontmatter, components, and user/agent content. |
|
|
144
|
+
| **Snapshot** | A baseline copy of the document at a known state. Used for diff computation and CRDT merge. |
|
|
145
|
+
| **Component** | A named region in a template document (`<!-- agent:name -->...<!-- /agent:name -->`). Targeted by patch blocks. |
|
|
146
|
+
| **Boundary** | A marker (`<!-- agent:boundary:hash -->`) that separates committed content from uncommitted user edits. |
|
|
147
|
+
| **Exchange** | The shared conversation surface where user and agent write inline. A component with `patch=append`. |
|
|
148
|
+
|
|
149
|
+
### Pane Lifecycle
|
|
150
|
+
|
|
151
|
+
| Term | Definition |
|
|
152
|
+
|------|-----------|
|
|
153
|
+
| **Binding** | The document→pane association stored in `sessions.json`. Created by `claim` (explicit) or `auto_start` (automatic). One document per pane. |
|
|
154
|
+
| **Reconciliation** | The process of matching editor layout to tmux layout. Performed by `sync`. Stashes unwanted panes, provisions missing ones. |
|
|
155
|
+
| **Provisioning** | Creating a new tmux pane and starting a Claude session for a document. Performed by `route::auto_start`. The normal path for new documents — sync triggers provisioning when it finds a session UUID with no registered pane. |
|
|
156
|
+
| **Initialization** | Assigning a session UUID, creating a snapshot, and committing to git. Performed by `ensure_initialized()`. Called from claim, preflight, and sync's resolve_file. |
|
|
157
|
+
|
|
158
|
+
### Integration Layer
|
|
159
|
+
|
|
160
|
+
| Term | Definition |
|
|
161
|
+
|------|-----------|
|
|
162
|
+
| **Route** | Resolve which tmux pane handles a file. Creates panes if needed (provisioning). |
|
|
163
|
+
| **Sync** | Reconcile editor layout with tmux layout. The primary entrypoint from the JB plugin on every tab switch. |
|
|
164
|
+
| **Claim** | Bind a document to a specific existing pane. Used for manual pane assignment; not needed in normal editor workflow (sync + auto_start handles it). |
|
|
165
|
+
|
|
166
|
+
### Interaction Model
|
|
167
|
+
|
|
168
|
+
| Term | Definition |
|
|
169
|
+
|------|-----------|
|
|
170
|
+
| **Directive** | A signal that authorizes and requests action. User inputs like "do", "go", "yes" are directives. Classified as `DiffType::Approval` in preflight. The directive's brevity is independent of the expected execution thoroughness — quality processes always apply in full. |
|
|
171
|
+
| **Cycle** | One round-trip: user edits -> preflight -> agent response -> write-back -> commit. Logged in `.agent-doc/logs/cycles.jsonl` with git state references for reproducibility. |
|
|
172
|
+
| **Layout check** | Pre-agent tmux health inspection (`check_layout()`). Detects: missing window 0, non-idle stash panes, and session drift (registered panes spanning multiple tmux sessions). Reported as `layout_issues[]` in preflight JSON. |
|
|
173
|
+
| **Session drift** | Condition where registered document panes span more than one tmux session. Detected by preflight's `check_layout()`. Fixed by `agent-doc session set <N>` to consolidate panes into the target session. |
|
|
174
|
+
| **Diff** | The user's changes since the last snapshot. Classified by `classify_diff()` into a `DiffType` for skill routing. Comment-stripped before comparison. |
|
|
175
|
+
| **Annotation** | A user edit to agent-written content (inline modification, colon-append). Classified as `DiffType::Annotation`. |
|
|
176
|
+
|
|
177
|
+
## Security
|
|
178
|
+
|
|
179
|
+
agent-doc is designed for **single-user, local operation**. All session data (documents, snapshots, exchange history) is stored on the local filesystem and committed to a git repository.
|
|
180
|
+
|
|
181
|
+
**Current security model:**
|
|
182
|
+
- **Single user only.** There is no multi-user access control, authentication, or session isolation.
|
|
183
|
+
- **Private repo recommended.** Session documents may contain sensitive content (correspondence, research, credentials in context). Use a private git repository.
|
|
184
|
+
- **Prompt injection risk.** Content pasted into documents from external sources (emails, web pages, chat logs) could contain prompt injection attempts. The agent processes all document content as user input with no injection scanning.
|
|
185
|
+
- **`--dangerously-skip-permissions` exposure.** When running with this flag (common in agent-doc sessions), the agent has full filesystem access. Injected prompts could read files or execute commands if not sandboxed.
|
|
186
|
+
|
|
187
|
+
**Planned:** Collaborative security for web/networked deployments (multi-user access control, session isolation, content scanning, compartmented access patterns).
|
|
188
|
+
|
|
189
|
+
## License
|
|
190
|
+
|
|
191
|
+
Licensed under either of [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE) at your option.
|
|
192
|
+
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
agent_doc-0.31.19.data/scripts/agent-doc.exe,sha256=xMCxDsYW437Bfy6zv9eR69BBIC1pUXihx4tOJdwxW8M,8143360
|
|
2
|
+
agent_doc-0.31.19.dist-info/METADATA,sha256=FOXjYm7qPBoB2R9_fAy8OQZ57oQM7SG9ymY5HTvAg9k,12019
|
|
3
|
+
agent_doc-0.31.19.dist-info/WHEEL,sha256=uJOc2U-Q1x95AlblQcqMRb3iR4QnPtdI7X2ycPN99rM,94
|
|
4
|
+
agent_doc-0.31.19.dist-info/sboms/agent-doc.cyclonedx.json,sha256=GnDlgDGdr1K6Y-dE-vhUF3W2uq-6-awLBgt5vVVERLE,262936
|
|
5
|
+
agent_doc-0.31.19.dist-info/RECORD,,
|