# Caprock — Context for AI Agents

## What this is

Caprock is a local, open-source mission control for Claude Code: a single static Go binary runs a loopback daemon that captures every `claude` session on the machine (Claude Code hooks via a tiny shim + transcript tailing), normalizes it into one event stream in SQLite, and serves a dense React dashboard — live activity, per-repo cost, token burn, loop alerts, the prose Claude actually wrote (searchable across sessions), spawning/typing into sessions, and a verified multi-agent orchestrator. Local-first, zero servers, Apache-2.0, free for solo use.

**Status: released, and taking money.** All three phases are built and green on
the 3-OS CI matrix; Orchestrate = hive, tasks board, Stop-loop, orchestrator
agent, verification-before-done, approvals. The Phase 2 tag gate — a
real-`claude` unattended run with hooks — passed. Paid plans are live: free,
$30/year or $100 once (the $5/month price is no longer sold), unlocked by an offline licence key
([ADR-022](.ai/08-decisions.md)). Which version is current is what `git
describe`, the releases page and `CHANGELOG.md` answer — rule 9 below is why
this line does not. See `.ai/14-build-status.md`.

## Repository structure

- `.ai/` — full documentation, **source of truth**. Read before any task.
- Go-to-market (`.gtm/`) and user feedback (`.fdck/`) live in the private site
  repo `cybrixcc/caprock-web`, not here: this repo is public.
- `cmd/`, `internal/` — Go daemon, CLI, hook shim (layout in `.ai/02-architecture.md`).
- `ui/` — React + Vite dashboard, embedded into the binary via `go:embed`.
- `app/` — the desktop app, a Tauri v2 shell around that dashboard (`app/README.md`).
- `pricing/` — versioned model pricing table. `testdata/` — fixtures, fake `claude`.
- `scripts/` — `align-tables.py`, `check-links.py` (docs gates); `shots.py`, `feature-shots.py`, `refresh-shots.sh` (the documented screenshots).
- `docs/` — human-facing docs; the spec-migration audit record.
- `changes/unreleased/` — one changelog fragment per PR. **Never edit
  `CHANGELOG.md`'s `[Unreleased]`**: add `changes/unreleased/<slug>.md`
  (format in `changes/README.md`); the release assembles them with
  `scripts/changelog.py`.

## How to get context

Read `.ai/00-index.md` first — its table maps every doc to when you'd read it
(the one home for that map). Then read the one file your task needs, not the
whole corpus. Contributing? See [`CONTRIBUTING.md`](CONTRIBUTING.md).

## Non-negotiable rules

1. **Phase order is the product: Observe → Control → Orchestrate.** Phase 0 must be useful on sessions the user starts themselves; control and orchestration are additive. Skipping ahead builds a runtime nobody adopts.

2. **No task is done with a red Windows CI job. No exceptions.** Cross-platform reliability is the moat.

3. **The shim never breaks a user's Claude session.** Every error path is silent `exit 0` within 1s.

4. **All data stays on the machine.** Loopback listeners only, no telemetry,
   nothing readable ever sent to Caprock. The only outbound calls are the
   release check and integrations the user turns on — Telegram, GitHub,
   Gemini, and access from anywhere, whose relay carries only end-to-end
   ciphertext ([ADR-058](.ai/08-decisions.md)): each off by default,
   revocable, to a destination the user chose, and saying where it is
   switched on what it sends ([ADR-047](.ai/08-decisions.md)). Three more,
   each only on the user's click, to caprock.dev, after the screen names
   what goes, and nothing sent automatically: a survey answer
   ([ADR-062](.ai/08-decisions.md)); a bug report the user wrote, with
   the screenshots they attached, an email if given, the version and the OS
   — to Caprock support, never GitHub ([ADR-073](.ai/08-decisions.md)); and
   the share card the user chose, the picture alone, when they press X,
   Threads or LinkedIn, so the post's link shows it — removable from
   Settings ([ADR-086](.ai/08-decisions.md)).

5. **English only, in every file.** Code, comments, docs, data, commits, PR
   titles and descriptions: no Russian and no other language. A quote from a
   user or the owner is translated, with a note that it was. Drafts in other
   languages (a Habr article, a Telegram post) live outside the repo. Test
   input whose point is non-English text (rune clipping, case folding, width)
   uses Greek, Japanese, accented Latin or emoji — never Cyrillic, which
   `make lang-check` (in `make check` and CI) rejects outside the generated
   `internal/api/dist`. Conventional Commits with scope.

6. **No invented numbers anywhere public** — prices, costs, forecasts, performance claims. Measured or sourced with a date; otherwise an open question in `.ai/12-risks.md`. Forecasts are labeled estimates.

7. **We never signal or type into a process we did not start.** The one
   exception is the doctor's stop: a direct, per-item, confirmed user action,
   never automatic ([ADR-059](.ai/08-decisions.md)).

8. **Contracts, DDL, and pricing change only together with `.ai/03-contracts.md`, a migration, or a `pricing_version` bump — in the same commit.**

9. **Keep the docs current as you build.** A change to behaviour lands with its
   documentation change in the same commit.

   **Never write the current version into prose.** It was in three places, all
   of them saying "v0.1.0–v0.15.1 are all tagged and published" three releases
   after that stopped being true. A number that has to be synced is a number
   that will be wrong; `git describe`, the releases page and `CHANGELOG.md`
   already answer the question. Naming a version to date a decision — "the
   v0.17.0 audit found" — is a historical fact and stays.

10. **Every task ends green** (`go vet`, `go test`, lint, UI typecheck/tests, `make check`) locally before push and in CI on three OS. Ongoing changes are focused PRs to master (the T0–T25 build is complete; see [ADR-014](.ai/08-decisions.md)).

11. **No public page says a paid tier is a pilot, unbuilt or coming soon.** The
    team tier is presented as the product (owner decision, 2026-09-30). "Not
    built" in `.ai/` is internal build status — it never travels to the site,
    README, press kit or any copy. Rule 6 still holds: example figures are
    labelled as examples; the product is not.

12. **A shortcut change is checked on Windows and Linux in the same PR.** Every
    key shown goes through `keys()` in `ui/src/lib/appkeys.ts`; the *every
    listed shortcut, on every OS* test presses each `SHORTCUTS` row as
    Windows and Linux spell it. A new chord that collides off macOS with the
    terminal or another command gets its own spelling there, not a shrug
    (owner, 2026-10-11).

## Dev commands

```bash
make help        # list targets
make dev         # daemon on :22776 + vite dev server on :5173
make test lint   # go + ui tests and linters
make smoke       # the Phase 0 DoD scenario with the fake claude
make docs-fmt    # tight-align all markdown tables (run after editing any table)
make check       # docs + lint + tests + smoke (the CI gate, minus the OS matrix)
```

## Tables

All markdown tables must be tight-aligned (each column padded to its longest value, separator exactly that width, no trailing whitespace). **Never align manually** — run after editing:

```bash
make docs-fmt
```

**Tables are for short enumerable values only.** If a cell needs a full sentence or more, do not use a table — rewrite it as a bulleted list with a bold lead-in per item. Wide prose-in-cells tables are unreadable in diffs and terminals.