Same CLI, Five Targets
Pass --target <id> to install the host-flavored kit — the same eight agents in each host's native format. The gk CLI is identical across targets — validate, graph new/ascii/svg/waves, memory, run ledger all work the same (pure CLI). The kit differs per host.
| Claude | Cursor | OpenCode | Codex | Pi | |
|---|---|---|---|---|---|
| Rules | .claude/rules/*.md | .cursor/rules/*.mdc | AGENTS.md | AGENTS.md rules section | AGENTS.md |
| Agents | .claude/agents/*.md | .cursor/agents/*.md | .opencode/agent/*.md | .codex/agents/*.toml | .omp/agents/ fragments |
| Skills | 13 · .claude/skills/ | 11 · .cursor/skills/ | 11 · .opencode/skills/ | 11 · .codex/skills/ | 11 · .omp/skills/ |
| Hooks | settings.json + *.cjs | hooks.json + *.cjs | TS plugin gk.ts | none — AGENTS.md rules | .omp extension handlers |
| Execution | /gk:run + /gk:execute | /gk:execute | /gk:execute | /gk:execute | /skill:gk-execute via OMP |
Agent formats stay host-native: markdown frontmatter for Claude/Cursor/OpenCode; Codex TOML (name, description, developer_instructions, model, sandbox_mode); Pi prompt fragments installed under .omp/ for OMP. Dispatch paths: Claude Code / Cursor / OpenCode spawn Task-tool subagents wave by wave (parallel within a wave); Codex uses a spawn-prompt protocol against custom TOML agents — the wave barrier is instruction-enforced, not tool-enforced (documented limitation); Pi dispatches through OMP via the gk_dispatch_agent extension, running headless omp -p child processes (requires omp on your PATH). Skills gk-compile/gk-run remain Claude-only; non-Claude targets execute graph.yaml directly through gk-execute.
Dogfooded, Not Mocked
Every graph below actually executed in this repository via /gk:execute — the features shipped on this page (viewer interactivity, CLI hardening, this very report's positioning pass) were built by these graphs. Each card links its graph.yaml.
Sonnet research fleet (Reddit/X/HN sweep, docs audit, product-gap probe, competitive scan) → fable consolidation + plan → 3 parallel sonnet executors → fable review (1 critical found) → fix loop → acceptance gate. Shipped the CLI fail-loudly contract and docs honesty batch.
Built this viewer's interactive edges, drag re-routing, and a11y drawer. The review wave caught what every executor self-review missed: drag deltas compounding across mousemove events (~30× overshoot) — runtime-reproduced by the fable reviewer, fixed with regression tests.
Six sonnet fleet sweeps → four optimization-lens candidates → fable-judged pairwise elimination. Champion measured −29% tokens on the frozen benchmark; the judge also falsified one fleet proposal that regressed accuracy — adversarial checking working as designed.
Self-improvement loop: parallel web research → plan → benchmark harness build → routing experiment. Three rounds took gk's code-graph recall from 124,414 → 59,309 tokens (−52.4%) with wrong-hits 12 → 5, measured on a frozen replay benchmark.
The Full Lifecycle
Inside a session, the kit's skills walk the user from blank canvas to verified run — 13 shipped for Claude Code (including gk-compile and gk-run), 11 for every other target. /gk:execute is new in 0.2 (cyan border).
Engineering Team
Seven agents from agency-agents, plus the Memory Curator. Each declares a model tier, graph roles, and evidence keys.
gk graph search/tracegk graph querygk memory recall/traceCBM Bridge — Five Metrics Proven
The 0.2 bridge was exercised end-to-end by a 15-node gk-evolve custom-topology graph. A verifier node looped until all five success metrics held. Final: all pass, three with documented caveats.
| Metric | Target | |
|---|---|---|
| M1 — indexing speed | ≤ CBM, ≥10k nodes/sec | PASS · delegation |
| M2 — indexing quality | node_yield ≤ 1.10, edge kinds + complexity | PASS |
| M3 — API parity | contract mirrors live CBM output | PASS |
| M4 — retrieval | gk CLI ≤ 1.5× CBM-direct | PASS · 0.28× |
| M5 — recall > grep | Recall@10 ≥ 0.95, ≥10× vs grep | PASS · CBM 4/5 vs grep 0/5 |
Autoresearch — The Kit Improved Itself
Three rounds of the Karpathy-style loop: freeze a benchmark, mutate one axis, keep measured wins, reset the rest. Round 1 failed honestly (the instrument bypassed the product code — diagnosed, not papered over). Rounds 2–3 shipped the corrections.
| Frozen 20-question task-replay | Metric (lower = better) | Wrong |
|---|---|---|
| grep/glob reference | 2,936 | 0 |
gk baseline — raw search_graph | 124,414 | 12 |
+ question-kind routing (gk graph ask) | 63,115 | 5 |
| + tournament payload trims | 59,309 · −52.4% | 5 |
A 6-agent research fleet + fable judge found the ACT-R decay shipped in 0.2 was a store-wide time bomb (no reinforcement → uniform ~day-10 expiry). Fixed with a closed loop: gk memory recall retrieves (keyword×salience + validity/supersede filters) and reinforces survivors; gk memory touch bumps use; gk memory trace decays with a JSONL audit trail; bun run eval:memory reports hit_rate 1 / 0 validity violations / 14 malformed entries counted as expected.
Two adversarial catches along the way: the fleet's deadcode trim was measured regressive before it shipped, and CBM search_graph was measured to return 0 hits over markdown-only projects — gk-recall's semantic step had always been dead weight and was replaced with the measured retriever.
Durable Memory, Strict Boundaries
Memory capture remains GraphKit's markdown store, with additive OKF-compatible provenance fields: generated, recorded_at, status, and sources. This is deliberately not an OKF conformance claim; existing GraphKit fields stay authoritative and unknown fields survive rewrites. See the current OKF specification.
Malformed memory entries are dropped and counted in malformed. A missing memory directory is empty. Other filesystem failures return MEMORY_DIR_UNREADABLE and fail instead of silently erasing recall.
Memory-augmented workflows share one terminal contract: the curator's final non-empty line is exactly INJECTION: <reminder> or INJECTION: null. A non-null reminder is prepended to the next action dispatch; malformed output becomes null and never blocks the action node.
Cadence counts completed action-node executions, not curator calls. recall_topk, expire_policy: manual, and null_intervention_allowed are honored from graph configuration.
Curator contract parity is tested across Claude Code, Cursor, OpenCode, Codex, and pi. Codex uses sandbox_mode = "workspace-write" for persistence.
These are deterministic fixture and behavior checks, not benchmark-superiority claims. The @0xwast3 memory-engineering article is third-party validation only. Its status: conflicted field and three-month capture criterion are follow-up scope, not shipped behavior.
The Kit Ran Its Own Flow — Viewer Interactivity Upgrade
The superpowers preset was extended with a research fan-out and executed via /gk:execute: 3 parallel sonnet researchers → fable consolidation + plan (function-ownership map keeps parallel executors collision-free) → 3 sonnet executors with self-review loops → fable final review → sonnet fix loop → fable acceptance gate with a live smoke test. 10 nodes, 6 waves, one hotfix, zero commits until the gate passed.
Historical note — the local interactive viewer this section documents was removed in v0.3.2 in favor of archify-rendered diagrams; see Visualization above.
| Shipped | Detail |
|---|---|
| Edges are first-class | invisible wide hit-target paths make edges hoverable/selectable; dragging a node re-routes incident edges live (incremental deltas, no dagre re-run); Shift+click traces a route (BFS routeIds) |
| Drawer & keyboard | real SSE focus-restore (the 0.2 fix was a no-op — capture now happens before blur), drawer role="dialog" with focus trap/return, arrow-key nav skipping filtered nodes, coherent Escape |
| Launch ops | pinned port 4800 (GK_VIEWER_PORT), port-busy probe +1…+9 then ephemeral, opt-in Chrome via GK_VIEWER_BROWSER=chrome — default still just prints the keyed URL |
| Kit upgrades | gk init now overwrites stale kit files on upgrade (skills refresh) while preserving user .gk.json; --force remains the wipe path |
Executor self-reviews caught 3 bugs pre-review (inverted drag endpoints, dropped Esc-clears-selection, dual-stack test bind). The fable gate still found 1 critical the tests masked: drag re-routing compounded mousemove deltas — one 40px move vs two 20px moves diverged, ~30× overshoot over a 60-event drag — because every test simulated exactly one mousemove. The reviewer runtime-reproduced it, the sonnet fixer shipped incremental deltas plus a two-moves-equal-one-move regression test, and 2 majors (stale .route ribbons, Shift+click popping the drawer) fell the same way. Acceptance re-proved every plan checkbox independently, including a live key-gated smoke on the pinned port.
Graph Runtime Primitives — Session Store, Loop Groups, Template Gallery
Three core runtime features landed to unlock multi-session workflows and iterative refinement without a custom runtime engine:
| Shipped | Detail |
|---|---|
| Session Graph Store | Immutable timestamped session graphs under .graphkit/graphs/YYYY-MM-DD-<slug>.yaml with collision suffixing (-2, -3) and an active pointer at .graphkit/active. Managed via gk graph list|switch|show. Root graph.yaml fallback preserved. |
| Loop Groups & Hybrid Stop | Top-level loops: directive repeats contiguous wave spans. Hybrid stop hierarchy: deterministic gate_evidence check first, LLM-judged stop_when fallback, max_rounds hard bound. Enforced via schema + compiler wave-span closure. |
| Template Gallery & Materialize | gk template materialize <name> [--params] [--use] resolves project-local ⇒ user-global ⇒ bundled gallery. Ships 4 bundled templates (audit-pr, refactor-module, bench-eval, doc-sweep). |
Try the New Runtime Features
Step-by-step verification flows for the three features shipped in v0.2.25:
The Part of the Stack Every Other Tool Makes You Run Itself
gk is a graph-engineering compiler kit, not a "multi-agent framework." Where CrewAI/AutoGen/ADK ship a runtime that invokes models and owns the execution loop, gk declares the graph, gates it at validate, and compiles it to a deterministic .workflow.js the host already runs — with zero models orchestrating. gk never invokes a model; coordination is compiled from graph.yaml, not delegated to an LLM, which is where other stacks' empirically measured flakiness lives (CrewAI: a 34% non-deterministic failure rate over 3 weeks on identical inputs vs 4% under explicit orchestration — per 2025–26 dev-shop retrospectives). The term "graph engineering" is the field's own label for this rung (Simmons, "We Are Entering the Graph Engineering Phase"): the craft of what happens between context windows.
Budgets are the safety story. Every production postmortem independently converges on caps — hard turn/token/¤ ceilings, fail-closed defaults, checkpointed edges. gk's limits, constraints, and loop max_rounds are that blast-radius control (Edgeless Lab — the $50-night swarm; TURION — "hard budgets, always"). What you leave runnable will eventually run; gk makes the bound explicit and auditable.
Per-node binding kills the state-schema tax. The LangGraph scorecard's cost center is designing a typed state schema — 2–4 weeks per modest graph (Orange ITS review), "most of the time goes to state schema" (Kalvium). gk binds model, tools, skills, refs, loop, constraints per node; there is no shared schema to hand-write. Agent names must resolve to a real file in the active kit's agents directory — validation fails otherwise.
Verification is the field's #1 unmet demand — a partial answer today, not a claim it's solved. Users want a separate verifier; a model must not certify its own work (langgraph #7209; antfarm README). gk's answer is two existing primitives — the adversarial-verification topology (produce → refute → adjudicate) and the evidence gate's required_keys (a node only passes if it produced what its graph declared). That is a partial answer: there is no first-class recompute/verify-gate primitive, and no runtime telemetry. Verification is a direction gk has started, not a solved claim.
Host-native = subscription-safe. gk rides each host's supported first-party harness — Claude Code Workflow / native subagents, Cursor, OpenCode, Codex, or Pi — instead of a third-party orchestration layer — the exact harnesses Anthropic keeps first-class in the subscription, unlike third-party bridges now billed extra (The Verge; TechCrunch). No runtime tax: gk ships no Python/TS runtime, no dependency graph.
Roadmap — Next Up
Five consolidated candidates, cross-validated by four parallel research passes (competitive scan, user-pain mining, repo-internal deferrals, adjacent-standards bridges). Ranked by value × fit with the compiler thesis ÷ effort. S1 checkpoint resume shipped in 0.3.5 — gk run resume replays the ledger, derives a pending-only graph, and starts a provenance-linked child run.
Reconciles .graphkit/runs/<id>/ against the recorded graph (passed + evidence-on-disk), derives a pending-only session graph where satisfied evidence becomes refs, validates it against the compiler's structural rules, and starts a child run carrying resumes: provenance. Drift-guarded by sha256.
approval: wave pauses dispatch before write-capable waves via host-native permission hooks — the production make-or-break primitive (OpenAI needs_approval, Mastra suspend(), Flowise human-input node). Implementable wholly in compiler + host skills.
Serialize run ledgers into OpenTelemetry GenAI-convention spans — waves, nodes, advisor events, durations — ingestible by Datadog/Jaeger/Langfuse. Fills the admitted "no runtime telemetry" gap with a pure compiler-side bridge, zero daemon (the CBM play, repeated).
N runs of a graph; evidence-gate pass-rate and cost matrix per per-node model tier, diffed against a golden baseline run. The deterministic "which tier passes at what cost" answer competitors' eval harnesses approximate with LLM judges.
Route intents to search_graph/trace_path/query_graph, thread result limits, unify the four bespoke subcommand bodies — idea-backlog calls it the "largest single lever"; program.md scores retrieval accuracy as 96.5% of the remaining gap.
Compile-time estimate: nodes × loop rounds × fan-out breadth × tier pricing, calibrated by ledger duration_ms; warnings for unbounded patterns. Budgets-as-blast-radius made checkable before anything runs.
Parking lot from the same consolidation: typed seam contracts on edges (JSON-Schema evidence validation), worktree snapshots for atomic replay, advisor tier-swap escalation (spec'd non-goal), gk graph history ledger join, deterministic predicate routing, MCP-registry tool resolution.