Skip to content

v0.1.0 — First release

Choose a tag to compare

@github-actions github-actions released this 09 Jun 01:33
· 27 commits to main since this 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, or idle, resolved from Claude/Codex lifecycle hooks (turn boundaries, tool use, end-of-turn question detection).
  • State file as the contract — ~/.heed/state.json is 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 falsely working (survives PID reuse).
  • Ownership overlay — owners.json lets a consumer (e.g. an orchestrator or Codezilla) tag threads with its own product/session id and filter state.json down to its own children. heed owner register writes 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.