~/.claude_tools — agent tooling, OUTSIDE project scope

Tools that must survive project deploys/redeploys and never be "forgotten." Kept out of the project tree on purpose: a prior sbx deploy of core services was orphaned because tooling wasn't redirected and no telemetry was collected — this directory is the always-available fallback.

notesdb — notes + internal-telemetry store (server + client)

A stdlib-only re-implementation of jazz-notes-db (no Docker, no fastapi/uvicorn/aiosqlite) so it can't rot behind a missing venv or a down daemon. Split so the boundary is real, not decorative:

- cnotesd.py — the server. The single writer and the boundary. The ONLY thing that touches the SQL tables. It owns the schema + validation + invariants. Runs as a launchd service (com.claude.cnotesd, KeepAlive → always-up) on http://127.0.0.1:8002. DB: ~/.claude_tools/notes.db (WAL; override $NOTESDB_PATH). - cnotes (CLI) — a pure HTTP client. Holds NO SQL; it never touches the tables. Writes are POST, reads are GET. This is the point: clients (this CLI, sandboxed agents, services) all go through the API, exactly like the read/write planes in ~/code/rebuild/SANDBOX-PLANES.md.

Why not direct-write? The HTTP layer is the boundary that stops any client editing the raw tables. A CLI that writes SQL directly would defeat it. Reliability (the "can't be forgotten" requirement) is met by the server being always-up — and by a client-side spool: if the server is momentarily down, a write is appended to ~/.claude_tools/spool.jsonl (a durable outbox, not the DB) and re-dispatched through the server's validated path on the next flush/successful write. No loss, no bypass.

Schema is faithful to the original (notes, telemetry) + a free-form events table, so backup_notes_db exports stay restorable.

cnotes event KIND [--source S] [--data '{json}'] [--text X]     # internal-telemetry event
cnotes add --title T --text X [--collection C] [--tags a,b]     # a note
cnotes ls [--collection C] [--tag t] | get ID | search Q | rm ID
cnotes events [--kind K] [--limit N]
cnotes telemetry log --package P [--exit-state S] [--elapsed F] ... | ls | stats
cnotes stats | flush | health          # flush drains the spool; --json goes BEFORE the subcommand
cnotes --json <cmd>

Service control: launchctl kickstart -k gui/$(id -u)/com.claude.cnotesd (restart), launchctl print gui/$(id -u)/com.claude.cnotesd (status). Log: ~/.claude_tools/notesdbd.log.