AGENTS.md

1# codedb Agent Guidelines
2 
3## What codedb is (and isn't)
4 
5codedb is a **code-intelligence and context tool, not an editor.** It exists to
6help agents *find and understand* code — structural search, symbol/caller
7lookup, dependency graph, outlines, and task-shaped context — so they can edit
8with their own native tools. codedb has **no edit capability**: the old
9`codedb_edit` fallback (and the HTTP `POST /edit` endpoint, the post-edit
10linter, and `codedb_diagnostics`) was removed because MCP edit calls bypass the
11client's own undo/rewind tracking. Keep that framing consistent across tool
12descriptions, the MCP `initialize` instructions, the README, and these docs.
13 
14## Review guidelines
15 
16- Flag any security issues: injection, file traversal, untrusted input, secret exposure
17- Verify that sensitive files (.env, .pem, .key, credentials) are excluded from indexing AND search
18- Check that telemetry behavior matches documentation claims
19- Flag any regression in benchmark-critical paths (threshold: 10%)
20- Treat P1 issues as merge-blocking
21- Verify new language parsers handle malformed input gracefully (braces in strings, unterminated comments)
22- Check that installer scripts don't execute untrusted code or skip verification
23 
24## Pre-merge verification
25 
26Run these before merging any MCP-related change:
27 
28```bash
29zig build test                                          # unit tests
30python3 scripts/e2e_mcp_test.py \
31    --binary zig-out/bin/codedb \
32    --project /path/to/codedb                          # E2E MCP scenarios
33```
34 
35`e2e_mcp_test.py` covers three scenarios:
361. **issue-346 regression** — spawn from cwd=`/`, roots handshake, tools return real data
372. **Normal mode** — explicit positional root (`codedb <path> mcp`), immediate scan
383. **No-roots client** — spawn from `/` with no roots capability, stays alive gracefully
39 
40## Security-sensitive areas
41 
42- `src/watcher.zig` — file indexing skip lists (secrets must be excluded)
43- `src/mcp.zig` — file read/search (path traversal, scope boundaries)
44- `src/telemetry.zig` — data collection and transmission (must match docs)
45- `src/snapshot.zig` — sensitive file filtering
46- `install/install.sh` — binary download and config modification
47