witness: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents (and humans) working in this repo. Claude Code reads this via @AGENTS.md in CLAUDE.md; other tools may read it directly.

What this is

witness is a single pure-Go binary that captures Claude Code and OpenCode sessions into a person-centric growth archive (raw turns → observations → facets → narrative profile). It is a pure capture+serve tool — no coaching, no injection into sessions. See README.md for the full model.

Build, test, run

Everything is CGO_ENABLED=0 (single static binary, no cgo). Use the Makefile:

make build        # compile to bin/witness-<os>-<arch> (with version ldflags)
make test         # CGO_ENABLED=0 go test ./...
make vet          # CGO_ENABLED=0 go vet ./...
make fmt          # gofmt -w internal cmd
make doctor       # build + run the embedder/model/config health check
make install             # (or: make install-opencode) wire hooks/plugin + MCP + bind runner
make build-all    # cross-compile darwin+linux+windows, amd64+arm64
make package-windows     # self-contained Windows zips (exe + prompts + model)

Before finishing a change, run make fmt vet test and expect all green.

macOS gotcha: always make build (or go build -o bin/...) — do not cp a built arm64 binary to another path and run it. macOS invalidates the ad-hoc code signature on copy and the copy dies with SIGKILL (137). Build in place. (The Windows install path does copy the binary into %LOCALAPPDATA% — that's fine, Windows has no such signature, and install_windows.go guards a self-copy with os.SameFile + writes atomically via temp+rename.)

Architecture (where things live)

• cmd/witness/ — 15-line entry point; calls commands.Run().
• cmd/commands/ — one cobra command per file (capture, session, worker, mcp, install, doctor, profile, facets, observations, review, lens, import, distill, cleanup). Shared helpers in cli.go; terminal styling in style.go.
• internal/store/ — SQLite data model + the filesystem/DB-as-queue. raw (L0), observations (L1), facets/facet_versions (L2, bi-temporal), progress (distill watermark), staged, meta. MaxOpenConns(1) + WAL + busy_timeout is the deliberate concurrency model. resolveRoot() picks the data dir via dataDirNames (adopt-in-place, see invariants below).
• internal/distill/ — the worker: mines L0→L1 per lens, reviews L1→L2, and regenerates L4 via a headless runner (claude -p or opencode serve).
• internal/platform/{claude,opencode}/ — the per-runtime capture/import adapters. internal/platform/opencode/plugin/ embeds the OpenCode plugin JS. (internal/platform/platform.go holds the cross-runtime constants + types.)
• internal/bundle/ — resolves bundled-asset dirs (prompts/, the embedding model) relative to the binary via os.Executable() when no env var points at them, so a copied/installed binary self-locates its assets.
• internal/{embed,vector,lens,mcp}/ — embeddings (pure-Go GoMLX), cosine search, lens loading, the MCP server.