Skip to content

Releases

v0.4.4

Choose a tag to compare

@github-actions github-actions released this 02 Oct 10:57

v0.4.4 — Codex Worker Tracking

  • Codex sessions started from inside a Claude Code session now record which session started them, so apps can show them as that session's workers.
  • Ownership records for sessions that haven't run in two weeks are now cleared instead of building up forever.

v0.4.3 — Reliable Codex Session Tracking

  • Codex sessions keep their own agents and activity when several sessions run at once.
  • Restarting Heed clears incorrect session links saved by older versions.

v0.4.2 — Codex Agent Monitoring

  • Track Codex child agents and nested agents alongside Claude agents, with running and completed status and recorded tool activity.
  • Recover monitoring of live Codex sessions and their agents after Heed restarts.
  • Provide task names and worktree activity for Codezilla’s Haven ticket grouping.

v0.4.3

Choose a tag to compare

@github-actions github-actions released this 01 Oct 01:10

v0.4.3 — Reliable Codex Session Tracking

  • Codex sessions keep their own agents and activity when several sessions run at once.
  • Restarting Heed clears incorrect session links saved by older versions.

v0.4.2 — Codex Agent Monitoring

  • Track Codex child agents and nested agents alongside Claude agents, with running and completed status and recorded tool activity.
  • Recover monitoring of live Codex sessions and their agents after Heed restarts.
  • Provide task names and worktree activity for Codezilla’s Haven ticket grouping.

v0.4.2

Choose a tag to compare

@github-actions github-actions released this 27 Sep 14:46

v0.4.2 — Codex Agent Monitoring

  • Track Codex child agents and nested agents alongside Claude agents, with running and completed status and recorded tool activity.
  • Recover monitoring of live Codex sessions and their agents after Heed restarts.
  • Provide task names and worktree activity for Codezilla’s Haven ticket grouping.

v0.4.1

Choose a tag to compare

@github-actions github-actions released this 25 Sep 10:23

Full Changelog: v0.4.0...v0.4.1

v0.4.0

Choose a tag to compare

@github-actions github-actions released this 24 Sep 19:21

Full Changelog: v0.3.1...v0.4.0

v0.3.1

Choose a tag to compare

@github-actions github-actions released this 07 Sep 10:19

Full Changelog: v0.3.0...v0.3.1

v0.3.0-rc.1

Choose a tag to compare

@github-actions github-actions released this 05 Sep 14:09

Full Changelog: v0.2.0...v0.3.0-rc.1

v0.3.0

Choose a tag to compare

@github-actions github-actions released this 05 Sep 14:21

Full Changelog: v0.2.0...v0.3.0

heed v0.2.0 — Session Succession

Choose a tag to compare

@github-actions github-actions released this 19 Aug 21:49

Session succession

A thread is keyed by native session UUID, but a conversation isn't. Claude Code rotates the session id part-way through when a session forks into its background daemon (--session-id <new> --fork-session --resume <old>.jsonl) or restarts in place. The hook stream moves to the new id while the old one falls silent but stays live — so a consumer watching the old id sees the thread go idle forever while the work carries on somewhere it can't see.

Heed now follows the conversation across that rotation.

Linking. At the successor's first hook event, the daemon looks for a predecessor using two deterministic signals: a matching (pid, pid_start), meaning the session rotated inside the same process; or the --resume value in the successor's argv, which names the predecessor's transcript outright. Process ancestry is deliberately not a signal — a background session spawned from a tracked session shares its ancestry without continuing it, and ancestry alone can't separate a sibling from a successor. Resolution happens at first sighting because it reads the live process; once the predecessor exits, the evidence is gone.

Ownership. Linking alone doesn't move the owner overlay, because a session may fork a sibling and keep working. Ownership follows the live end of the lineage: it moves when the predecessor's process is gone, when the successor is the same process, or when the predecessor has been hook-silent for 120s while the successor kept emitting. A predecessor that is no longer tracked but still holds an overlay is claimable too, so a handoff that happened while the daemon was down doesn't strand the thread.

The overlay is moved, never copied, in a single atomic owners.json write. A product's thread id must name exactly one native session, or a consumer diffing state.json flaps between the superseded record's frozen activity and the live one's.

Contract changes

Two optional fields on the per-thread record, omitted unless the thread is part of a lineage:

  • supersedes — native session id this thread continues
  • superseded_by — native session id that continued this thread

These are additive and schema_version is unchanged at 1, so existing consumers are unaffected and no lockstep upgrade is needed. Consumers need no new logic for the common case: the overlay arrives on the live session and the superseded record drops out of an owner_product filter on its own. Follow superseded_by if you want to render the chain; the successor's thread_id is what a later --resume should target.

See SPEC §4.7 for the full specification.

Also

  • cargo fmt --check passes again; CI on main is green for the first time since June.

v0.1.0 — First release

Choose a tag to compare

@github-actions github-actions released this 09 Jun 01:33

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.