Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
docs: design spec for Graft × Claude Code integration
Shrish Dwivedi10c1e26a5d62
diff --git a/docs/superpowers/specs/2026-07-20-graft-claude-code-integration-design.md b/docs/superpowers/specs/2026-07-20-graft-claude-code-integration-design.mdnew file mode 100644index 00000000..5438fa6d--- /dev/null+++ b/docs/superpowers/specs/2026-07-20-graft-claude-code-integration-design.md@@ -0,0 +1,270 @@+# Graft × Claude Code integration — design++**Date:** 2026-07-20+**Status:** Draft for review+**Owner:** Shrish+**Scope:** One implementation plan.++## 1. Goal++Make Graft *visible and active* inside a Claude Code session, the way ruflo's+statusline makes ruflo visible. Today Graft is a passive `graft/` folder that an+agent is *supposed* to read. This feature ships a `.claude/` integration that:++1. **Shows** the developer what Graft holds and whether it's trustworthy (a live statusline).+2. **Feeds** relevant graph context into the model automatically (retrieval + orientation + blast-radius).+3. **Keeps itself fresh** — auto-syncs the graph after edits, at `$0`, with no manual command.++Every number shown must be real. No fabricated "tokens saved %", no misleading+dollar cost. If a signal can't be measured honestly, it isn't displayed.++## 2. Background & constraints (grounded in the engine)++- Graft = `@nanonets/graft` v0.2.1, a Node/TS **CLI + library**. No daemon, no MCP.+ Commands: `graft build` / `ask` / `check` / `viz`.+- State on disk under `<repo>/graft/`:+ - `graft/.graph/wiring.json` — deterministic code graph. Top-level `meta`+ (`{version, nodeCount, edgeCount, languages[]}`), `nodes[]` (each with+ `id, name, kind, path, span, signature, exported, body_hash, summary_state,+ summary, crux`), `edges[]` (`{from, to, relation, confidence}`,+ `relation ∈ contains|calls|imports|references|implements|extends`).+ - `graft/*.md` — concept nodes (LLM prose) with typed `[[wikilinks]]`.+ - `graft/manifest.json` — roster + `repoDigest` + per-file hashes.+ - `graft/INDEX.md` — human-readable map (~4.4 KB).+ - `graft/.cache/` — **gitignored**; safe home for session state + sync lock.+- Measured facts that shape the design:+ - `graft check --json` runs in **~0.35s**, read-only, and returns precise drift:+ `graph.changed[]` (files *and* symbols), `graph.added/removed`, `context.contentDrift[]`, and `ok: false` when stale.+ - Plain `graft build` = **structural, deterministic, offline, `$0`**.+ `graft build --deep` = the LLM pass (summaries/crux) that spends OpenRouter+ credits and needs `OPENROUTER_API_KEY`; without a key it degrades to structural.+ - Graft has **no token/cost meter**. There is no runtime signal for "tokens saved".+- Claude Code `.claude/` surface we rely on (confirmed against docs):+ - `statusLine` (command): runs a script per render, receives a JSON blob on+ **stdin** including `model`, `cwd`, `session_id`, `agent.name`, and+ `context_window.{used_percentage, total_input_tokens, total_output_tokens}` and+ `cost.total_cost_usd`. Re-renders several times/second while streaming → the+ script **must be a fast pure reader**.+ - `subagentStatusLine` — per-subagent row.+ - `footerLinksRegexes` — regex → clickable link in the transcript.+ - Hooks (command scripts, JSON on stdin, can inject context via+ `additionalContext` / `hookSpecificOutput`): `SessionStart`, `UserPromptSubmit`,+ `PreToolUse`, `PostToolUse`, `Stop`.++**Honesty grading** used throughout:+- **real** — already on disk (`wiring.json`) or in stdin (`context_window`).+- **instrumented→real** — a small hook captures it honestly (reads count, drift, dirty).+- **not measurable** — dollar cost (misleading estimate) and "tokens saved %" (no baseline). **Excluded by design.**++## 3. Scope++**In scope (9 features):**++| # | Feature | Surface | Honesty |+|---|---------|---------|---------|+| D1 | Status bar (2-line) | `statusLine` | real |+| D2 | Drift beacon (`⚠ N stale`) | `statusLine` + PostToolUse flag | instrumented→real |+| D3 | Per-subagent region | `subagentStatusLine` | real |+| D4 | Clickable node refs | `footerLinksRegexes` | real |+| F1 | Active retrieval (`graft ask` → inject) | `UserPromptSubmit` | real |+| F2 | Session orientation (`INDEX.md` → inject) | `SessionStart` | real |+| F3 | Blast-radius nudge (edges → inject) | `PostToolUse · Edit` | real |+| O1 | Drift flag (mark dirty) | `PostToolUse · Edit` | instrumented→real |+| S1 | Auto-sync (turn-end background rebuild) | `Stop` | real |++**Explicitly out of scope (deferred):**+- Pre-grep short-circuit (`PreToolUse · Grep`) — powerful but intrusive; needs tuning.+- Coverage-gap detector — nice, not core to this deliverable.+- Graft-read usage counter as a *displayed number* — we will **capture** graft-vs-source+ reads in state (cheap), but only surface it once we trust it; the bar ships without it if noisy.+- `$` cost and "tokens saved %" — never shipped (not measurable).+- A `graft claude-init` CLI subcommand to scaffold this into *other* repos — the helpers+ will be written to be liftable, but productizing the installer is a separate plan.+- Debounced live watcher / session-end-only sync — rejected in favor of turn-end sync.++## 4. Architecture — readers vs. writers, one state file++The ruflo pattern: the **statusline only reads**; **hooks write and act**. They meet+at one small gitignored state file, so rendering never invokes Graft and the+expensive work happens only on real events.++```+ ┌─────────────────────────────┐+ edits / prompts ───▶│ graft-hooks.cjs (writer) │──▶ graft ask / build / check+ │ post-edit · prompt · stop │ (episodic, not per-paint)+ └──────────────┬──────────────┘+ │ writes+ ▼+ ┌─────────────────────────────┐+ │ graft/.cache/ (state) │+ │ stats.json · session/* │+ │ .sync.lock │+ └──────────────┬──────────────┘+ │ reads (small files only)+ ▼+ Claude Code stdin ───────▶ graft-statusline.cjs (reader) ──▶ the 2-line bar+```++### Files shipped++| Path | Role | Responsibility |+|------|------|----------------|+| `.claude/settings.json` | config | wire `statusLine`, `subagentStatusLine`, `footerLinksRegexes`, and 4 hook events |+| `.claude/helpers/graft-statusline.cjs` | reader | pure/fast: read `stats.json` + `session/<id>.json` + stdin → render bar. Never calls Graft. |+| `.claude/helpers/graft-hooks.cjs` | writer | single dispatcher: `session-start` \| `prompt` \| `post-edit` \| `stop`. Runs Graft, writes state, injects context. |+| `graft/.cache/stats.json` | state | precomputed `{nodeCount, edgeCount, languages, enrichedPct, staleCount, dirty, syncedAt}` for the statusline |+| `graft/.cache/session/<session_id>.json` | state | per-session: `{lastQuery, perAgentQuery, graftReads, sourceReads}` |+| `graft/.cache/.sync.lock` | lock | one background `graft build` at a time |++CJS Node scripts, no new dependencies (matches ruflo + Graft's own stack). All paths+resolved relative to `CLAUDE_PROJECT_DIR` with a `$HOME` fallback (ruflo's pattern).++## 5. The status bar (D1/D2)++Two lines. Top = Graft's own state (capture/coverage/freshness). Bottom = session+reality from Claude Code stdin. Example:++```+◤ graft · 319 nodes / 730 edges · 100% enriched · ⚠ 4 stale+▸ ctx 34% · syncing… · last: pkce.ts+```++- **Top line** from `stats.json`:+ - `nodeCount` / `edgeCount` (from `wiring.json` meta, precomputed).+ - `enrichedPct` = share of nodes with `summary_state === "ready"` (precomputed).+ **Show this segment only when `readyCount ≥ 1`.** A structural-only graph (no+ `--deep` run) has zero enriched nodes → the segment is hidden entirely; after any+ enrichment it shows `NN% enriched`. Keeps the bar quiet when there's nothing to say.+ - Freshness: `✓ synced` when `dirty=false && staleCount=0`; `⚠ N stale` when drift+ detected; `syncing…` while a background build holds the lock.+- **Bottom line** from stdin + session state:+ - `ctx NN%` = `context_window.used_percentage` (real, unambiguous).+ - sync status verb OR `last: <basename>` of the most recent captured/edited node.+- **Colors** (Nanonets palette, ANSI): indigo `#546FFF` for live/real graft data,+ amber for `⚠ stale` / drift, muted grey for separators. No green. No gradients.+- **Degraded states:** no `wiring.json` → `graft · not built · run graft build`+ (muted). Missing stdin fields → omit that segment, never error.+- **Performance:** reads only small files (`stats.json`, one session file). Optional+ ~2s /tmp memo keyed by `session_id` to coalesce render storms. Never spawns a+ subprocess. (Guards against the load-average storm ruflo hit by shelling out per render.)++## 6. Feed features++### F1 — Active retrieval (`UserPromptSubmit`)+- On each user prompt, run `graft ask "<prompt>" --json -n 5`.+- Inject the top hits as `additionalContext`, clearly fenced, e.g.:+ ```+ [graft] relevant context for this prompt:+ • PkceVerifier.verify — auth/oauth/pkce.ts:42-71 — validates the PKCE challenge…+ • OAuthClient.exchange — auth/oauth/client.ts:88-120 — …+ ```+- Caps: ≤5 hits, ≤~800 tokens total, each = title · `path:Lx-Ly` · one-line crux.+- `graft ask` is `$0`/no-LLM/lexical-structural, so this is cheap and offline.+- Silent no-op if: graft not built, zero hits, or prompt is trivial (< N chars).+- Records `lastQuery` (and `perAgentQuery[agent]`) into session state for D3.++### F2 — Session orientation (`SessionStart`)+- Inject the head of `graft/INDEX.md` (top concepts / entry points) as+ `additionalContext` so Claude starts oriented instead of re-exploring.+- Cap to a budget (e.g. first ~1.5 KB / top section). Skip on `source: resume`+ if already injected this session. No-op if `INDEX.md` absent.++### F3 — Blast-radius nudge (`PostToolUse · Edit`)+- After an edit to a source file, find nodes in that file and inject their+ **incoming** edges (who `calls`/`imports`/`references`/`depends_on` this) —+ the "what breaks if I change this?" direction.+- From `wiring.json` `edges[]` filtered by `to` ∈ edited file's node ids.+- Cap ≤8, with `+N more`. Format: `↳ used by: OAuthClient.exchange (client.ts), …`.+- Ignore edits under `graft/` itself (no self-referential noise / loops).+- Episodic (once per edit) so parsing `wiring.json` here is fine.++## 7. Auto-sync (S1) + drift flag (O1)++The closed loop:++```+1. edit source → PostToolUse·Edit sets stats.dirty=true, records last file+2. statusline → shows "⚠ stale" instantly (reads stats.json)+3. turn ends (Stop) → graft check --json (~0.35s) → write precise staleCount+4. if dirty & staleCnt → acquire .sync.lock → graft build (structural, $0) in background+5. build done → recompute stats.json (counts, enrichedPct), dirty=false,+ staleCount=0, syncedAt=now, release lock+6. statusline → flips to "✓ synced"+```++- **Money guard (hard rule):** auto-sync runs **only plain `graft build`** —+ structural, offline, `$0`. It **never** runs `--deep`. New/changed nodes sit at+ `summary_state: pending` until the developer manually enriches. No background API spend, ever.+- **Concurrency:** `.sync.lock` (pid + timestamp). If held, skip (a build is already+ running); stale locks (> N min) are reclaimed.+- **Non-blocking:** the build is detached/background so the `Stop` hook returns fast+ and never stalls the UI. Failure logs to `graft/.cache/sync.log`, leaves `dirty=true`+ (bar keeps `⚠`), and never throws.+- **Scope:** v1 runs a full structural `graft build` (fast for this repo). If measured+ slow on large repos, a later optimization scopes to `graph.changed[]` from `check`.+- **Guard against loops:** edits under `graft/` never set dirty and never trigger sync.++## 8. Display extras++### D3 — Per-subagent region (`subagentStatusLine`)+- Render `agent.name` + its `perAgentQuery` (last `graft ask` subject) from session+ state. Falls back to the main bar when no per-agent query exists.++### D4 — Clickable node refs (`footerLinksRegexes`)+- Regex matches `graft/[\w./-]+\.md` mentions in the transcript → link to the local+ file (or the `graft viz` URL, `http://localhost:4400`, if a viz server is detected).+- Lowest priority; pure garnish; ship last.++## 9. Data contracts++**`stats.json`** (writer: post-edit sets `dirty`; stop/build recomputes the rest):+```json+{ "nodeCount": 319, "edgeCount": 730, "languages": ["typescript"],+ "enrichedPct": 100, "staleCount": 0, "dirty": false,+ "syncedAt": "2026-07-20T14:30:00Z", "lastFile": "pkce.ts" }+```+**`session/<session_id>.json`:**+```json+{ "lastQuery": "pkce verification", "perAgentQuery": { "Explore": "…" },+ "graftReads": 6, "sourceReads": 11 }+```+**stdin fields consumed by the statusline:** `session_id`, `agent.name`,+`context_window.used_percentage`. Everything else optional/ignored.++## 10. Error handling & degradation++- Graft not built / no `wiring.json`: statusline shows muted "not built"; hooks no-op.+- `graft` binary not resolvable: hooks no-op; statusline still renders from `stats.json` if present.+- Malformed stdin JSON: render a minimal bar; never crash a hook (crashing a hook can disrupt the session).+- Concurrent Claude Code sessions: state keyed by `session_id`; single global `.sync.lock`.+- Windows console-flash (upstream bug): statusline reads files only — no subprocess spawns — so it doesn't flash.+- All hooks are best-effort: any failure logs to `graft/.cache/*.log` and exits 0.++## 11. Testing++- **Unit:** stdin parse, bar formatting, `enrichedPct` calc, dirty transitions,+ edge filtering for blast-radius, `graft ask` output → injection formatting, lock acquire/release.+- **Integration:** feed recorded hook payloads (JSON on stdin) to `graft-hooks.cjs`+ and assert (a) state writes and (b) injected `additionalContext`. Feed a recorded+ statusline stdin blob and assert the rendered string.+- **Dogfood (manual):** run inside `context-graph-engine`'s own Claude Code session+ (it is already indexed by Graft). Edit a source file, confirm `⚠ stale` → turn end →+ `✓ synced`, and that `--deep` is never invoked (watch for OpenRouter calls = none).++## 12. Rollout++1. Build + dogfood in `context-graph-engine/.claude/` on a feature branch.+2. Keep helpers repo-agnostic (paths via `CLAUDE_PROJECT_DIR`) so they can later be+ emitted by a `graft claude-init` command (separate plan).+3. Merge once the drift→sync loop is verified end-to-end with zero API spend.++## 13. Decisions (resolved 2026-07-20)++1. **`enrichedPct` display:** show the segment **only when `readyCount ≥ 1`**; hide+ entirely for a structural-only graph. (See §5.)+2. **`graftReads` on the bar:** **capture in `session/<id>.json` now, do not display yet.**+ Revisit surfacing it once the number is trusted.+3. **Sync build scope:** **build auto-sync properly** — robust lock, detached+ background process, debounce, and correct `dirty`/`staleCount`/`syncedAt`+ transitions. v1 runs a full structural `graft build`; changed-files scoping is a+ later optimization behind the same interface (not a shortcut on correctness).