Repository navigation
v0.1.0 — First release
Heed is a small daemon that watches the AI coding sessions running on your machine — Claude Code, Codex — and exposes their live state as a file other programs can read. heed install once, and ~/.heed/state.json always reflects what every active session is doing.
What it does
- Per-session activity —
working,awaiting input, oridle, resolved from Claude/Codex lifecycle hooks (turn boundaries, tool use, end-of-turn question detection). - State file as the contract —
~/.heed/state.jsonis versioned, atomically written (readers never see partial data), and updated within ~100ms of any event. Per session: activity, liveness, last tool + target, plan mode/progress, a pre-rendered subtitle, transcript path, cwd, and PID. - Process liveness — PID + start-time checks so a crashed session is marked
gone, not falselyworking(survives PID reuse). - Ownership overlay —
owners.jsonlets a consumer (e.g. an orchestrator or Codezilla) tag threads with its own product/session id and filterstate.jsondown to its own children.heed owner registerwrites it. - Human CLI —
heed status,heed watch,heed tui(interactive split-pane),heed events --follow.
Install
```sh
cargo install --git https://github.com/nibbletech-labs/heed
heed install
```
Prebuilt binaries for macOS (arm64/x86_64) and Linux are attached below. On macOS, heed install --service-install registers a launchd service so the daemon returns at login.
Reliability
- Event log self-heals around corrupt/invalid-UTF-8 writes — a bad byte can no longer wedge the daemon into a live-but-dead state.
- Upstream-schema drift CI watches for Claude/Codex hook-format changes.
Activity only — Heed never captures prompts, responses, or file contents; only structural metadata, all on your machine.