AGENTS.md

1# tools/cli — Agent Instructions
2 
3`brain` CLI tool built with Commander.js for interacting with the knowledge graph.
4 
5## Entry Point
6 
7`src/index.ts` → Commander program. Commands in `src/commands/`.
8 
9## Commands
10 
11| File | Command(s) | Purpose |
12|------|-----------|---------|
13| `init-reset.ts` | `init`, `init server`, `init client`, `reset`, `admin`, `doctor`, `auth rotate` | Solo/team initialization, admin, diagnostics, auth |
14| `add.ts` | `add` | Add entities manually |
15| `decide.ts` | `decide` | Record decisions |
16| `recall.ts` | `recall` | Build assistant context blocks |
17| `search.ts` | `search` | Full-text search |
18| `query.ts` | `query` | Natural-language graph query |
19| `index-cmd.ts` | `index` | Run collector pipelines |
20| `embed.ts` | `embed` | Generate embeddings |
21| `export-import.ts` | `export`, `import` | JSON export/import |
22| `status.ts` | `status` | Show brain status/stats |
23| `sync.ts` | `sync` | Manage sync state |
24| `wire-unwire.ts` | `wire`, `unwire` | Connect/disconnect repositories |
25| `wire-assistant.ts` | `wire-assistant`, `unwire-assistant` | Install/remove assistant hooks |
26| `watch.ts` | `watch` | File system watcher |
27| `tail.ts` | `tail` | Stream recent changes |
28| `flip-branch.ts` | `flip-branch` | Switch branch context |
29| `ownership-cmd.ts` | `ownership` | Entity ownership management |
30| `personal-cmd.ts` | `personal` | Personal namespace operations |
31 
32## Adding a New CLI Command
33 
341. Create command file in `src/commands/`
352. Export a function that takes the Commander `program` object
363. Register in `src/index.ts`
37 
38## Other Key Files
39 
40- `src/keychain.ts` — Credential storage
41- `src/personal-crypto.ts` — Encryption for personal namespace
42- `src/git-context-daemon.ts` — Background git context tracking
43- `src/sse-relay.ts` — SSE relay for real-time events
44- `src/lib/` — Shared CLI utilities
45