Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.
JavaScript ai-codingclaudeclaude-codeclaude-code-pluginclicoding-agentsdeveloper-toolsgitllmtypescript
docs(spec): verify capture hooks, add session-end catch-up and locking
Eren9a44766bc0fe
diff --git a/specs/codelineage-mvp.md b/specs/codelineage-mvp.mdindex 1839cf9..cc765f4 100644--- a/specs/codelineage-mvp.md+++ b/specs/codelineage-mvp.md@@ -1,6 +1,6 @@# codelineage — MVP spec-Status: Draft · 2026-10-21+Status: Draft · 2026-10-21 (rev. 2: capture verified against hooks docs)Tagline: *The lineage of your AI coding sessions.*## Problem@@ -20,7 +20,9 @@ these records into static HTML:phase/step/decision. Every node can be expanded to drill down. Each session nodecarries a `claude --resume <id>` copy button.- **Status card** at the top of every project: goal, done, pending (flags items- waiting on the user), next step, last activity.+ waiting on the user), next step, last activity. With parallel sessions, goal and+ next come from the most recently updated session; `needsUser` items are merged+ from all active sessions.- **Panel** (global): every registered project as a small status card, with quickswitching into each project map. Settings are shown read-only.@@ -39,7 +41,10 @@ Sessions are not a separate view. A session is a level of the project tree.```<project>/.codelineage/project.json # project name, epochs[], schema version- sessions/<session-id>.json # one file per session; only that session writes it+ sessions/<session-id>.json # one file per session (see Concurrency)+ state/<session-id>.json # hook state: turn counter, last recorded turn, pending tail+ snapshots/<session-id>-<ts>.jsonl # transcript copy taken before compaction+ locks/ # lock fileslineage.html # generated~/.config/codelineage/@@ -75,25 +80,72 @@ Session file (schema v1, sketch):The agent picks an existing epoch or adds one through the CLI (`codelineage epoch add`),which does a locked, atomic write.-**Concurrency:** one file per session means parallel agents in the same project never-write the same file. Only `project.json` is shared, and only the CLI writes to it.+**Writes go through the CLI.** The agent never writes JSON files directly. It pipes+its JSON to `codelineage session write`, which validates against the schema, runs the+redaction pass, merges with the existing file and writes atomically, then runs+`build` quietly.++**Concurrency:**+- One file per session, so parallel agents in the same project never write the same+ file. A session file may also be written by a catch-up run for that session (see+ Capture), so every session write takes a per-session lock and does+ read → merge → write, never a blind overwrite.+- `project.json` is shared; only the CLI writes it, under a lock.+- All writes (JSON and HTML) go to a temp file and are renamed into place, so a+ reader never sees a half-written file. Concurrent builds: last one wins.+- A catch-up run that finds the session lock held exits ("already running").## Capture (Claude Code plugin)-Distributed like OpenViking: a Claude Code plugin that ships `hooks/hooks.json` plus a-skill.+Distributed like OpenViking: a Claude Code plugin that ships `hooks/hooks.json`, a+skill, and a bundled build of the CLI (single file), so hooks run+`node ${CLAUDE_PLUGIN_ROOT}/dist/…` with no global install and no `npx` startup cost.+The npm package is published separately for standalone use.-- **Skill `/lineage`:** writes or updates this session's file following the schema.- The user can call it at any time.-- **Stop hook:** counts turns since the last update. Every N turns (default 5,- configurable) it blocks the stop with a reason, so the agent runs the skill. If- nothing meaningful happened, the agent leaves the file unchanged.-- **PreCompact hook:** forces an update before context compaction, so details are- saved before they are lost.-- Then `codelineage build` runs quietly to refresh the HTML.+Behavior verified against the Claude Code hooks docs (2026-10-21):-Each update costs agent tokens (the user's subscription or API usage). The frequency-setting is the cost knob.+- **Skill `/codelineage:lineage`:** writes or updates this session's record. The skill+ gets its session ID from `${CLAUDE_SESSION_ID}` and injects the current session file+ with `` !`command` ``, so the agent updates the record instead of rewriting it.+ The user can call it at any time.+- **Stop hook (the main path):** counts turns per session in `state/`. Every N turns+ (`updateEveryTurns`, default 5) it asks the agent to run the skill, using+ `hookSpecificOutput.additionalContext` (shown as "Stop hook feedback", not as an+ error). It never asks when `stop_hook_active` is true, which also keeps us clear of+ Claude Code's 8-consecutive-continuation cap. Stop does not fire on user interrupts,+ so the count is approximate. If nothing meaningful happened, the agent leaves the+ record unchanged.+- **Compaction (safety net).** PreCompact output never reaches the model and it cannot+ make the agent act; it can only block compaction, and blocking an auto-compact+ triggered by a context-limit error fails the request. So:+ - PreCompact never blocks. It copies the transcript to `snapshots/` and marks the+ session as needing an update.+ - PostCompact stores `compact_summary` in the session's state as a raw note.+ - SessionStart with `source: "compact"` tells the agent (via `additionalContext`)+ to run the skill, using the compact summary and the snapshot.+- **Session end catch-up.** Turns after the last update are lost when the user exits,+ runs `/clear` or switches with `/resume`. SessionEnd cannot make the agent act and+ plugin hooks get a 1.5 s budget, so the hook only records the pending tail in+ `state/` and spawns a detached `codelineage backfill <session-id> --tail`, then+ returns. The catch-up summarizes only the unrecorded turns with a headless run and+ merges them into the session file. Setting: `sessionEndCatchUp` (`on` by default,+ `off` = no tokens spent; the tail is shown as "not recorded").+ - Fallback: if the detached process dies, the pending tail stays in `state/`; the+ next `build` or the next session start in that project retries it.+ - To verify during implementation: the detached process survives the hook and+ Claude Code exiting.+- **Before `init`:** if `.codelineage/` does not exist, all hooks are no-ops, except+ that SessionStart injects a one-line hint to run `codelineage init`. Projects are+ never registered automatically.+- **Recursion guard:** every headless run started by codelineage (`backfill`,+ catch-up) sets `CODELINEAGE_DISABLE=1`, and our hooks do nothing when it is set.+ Users can set it too, to turn capture off for any headless run (for example a+ loop runner). Other plugins' hooks (memory plugins and the like) must not fire in+ these runs either; the headless run starts Claude Code without user plugins and+ settings. To verify during implementation: which flag does that.++Each update costs agent tokens (the user's subscription or API usage).+`updateEveryTurns` and `sessionEndCatchUp` are the cost knobs.## CLI surface@@ -104,7 +156,9 @@ setting is the cost knob.| `codelineage open [dir]` | Builds, then opens the map (or the panel if no dir is given) || `codelineage epoch add <id> <title>` | Adds an epoch (locked write) || `codelineage config get/set <key> [value]` | Reads or changes settings |-| `codelineage backfill [dir]` | Summarizes existing transcripts by running the agent headless, one session at a time. Estimates cost and asks first. |+| `codelineage session write` | Reads session JSON from stdin, validates, redacts, merges and writes it under the session lock, then builds. Used by the skill. |+| `codelineage backfill [dir]` | Summarizes past transcripts of that project by running the agent headless, one session at a time. Estimates cost and asks first. Selection: `--pick` (default: lists sessions with date, first prompt and estimated cost), `--last <n>`, `--since <date>`, `--all`. |+| `codelineage backfill <session-id> --tail` | Summarizes only the unrecorded turns of one session. Started by the SessionEnd hook. |## Install questions (`init` and first plugin run)@@ -114,8 +168,11 @@ setting is the cost knob.(`cleanupPeriodDays`). Offer to raise it. Never change it silently. The READMEexplains this too.3. **Language** for summaries: `auto` (the conversation's language) or a fixed language.+4. **Past sessions:** "This project has N earlier sessions: all, pick, or none?"+ Default: none. Picking or all runs `backfill` with a cost estimate first.-Settings in `config.json`: `language`, `updateEveryTurns`, `gitPolicy`, `agents`.+Settings in `config.json`: `language`, `updateEveryTurns`, `sessionEndCatchUp`,+`gitPolicy`, `agents`.## Privacy@@ -134,6 +191,10 @@ Settings in `config.json`: `language`, `updateEveryTurns`, `gitPolicy`, `agents`trigger a warning.- **Project directory moved or deleted:** the panel marks it as missing.`codelineage config` can prune it.+- **Exit and immediate `--resume`:** the catch-up run and the resumed agent may write+ the same session; the session lock plus read → merge → write keeps both changes.+- **`~/.config/codelineage` not writable** (containers, CI, read-only home): registry+ and panel updates are skipped with a warning; project-local writes still work.## Tech stack@@ -147,11 +208,13 @@ Settings in `config.json`: `language`, `updateEveryTurns`, `gitPolicy`, `agents`## MVP scope-1. Schema, plus `init`, `build`, `open`, `epoch add`, `config`+1. Schema, storage (locks, atomic writes), plus `init`, `session write`, `build`,+ `open`, `epoch add`, `config`2. HTML template: status card, graph with drill-down, outline, resume button3. Panel-4. Claude Code plugin: skill, Stop and PreCompact hooks-5. `backfill`+4. Claude Code plugin: skill; Stop, PreCompact, PostCompact, SessionStart and+ SessionEnd hooks; recursion guard+5. `backfill` (project selection and `--tail` catch-up)## Later