Keep coding agents working as long as they are still making useful progress.
Graphcraft is a local execution layer for long-running coding agents. It turns a repository task into a durable execution and governance graph, runs bounded workers through Codex or Claude Code, checks progress with repository evidence, survives interruption, and stops safely when a changed strategy is no longer productive.
Warning
Graphcraft v0.1 is an alpha. It supports local verification and atomic-commit finish lines. It does not yet push, open pull requests, monitor CI, merge, or deploy.
Requirements: Git, Node.js 22+, and an authenticated Codex or Claude Code CLI.
The public npm package is @tpypan/graphcraft; the unscoped graphcraft name belongs to an unrelated project. Install it globally with either package manager:
npm install --global @tpypan/graphcraft
graphcraft install --host codexpnpm add --global @tpypan/graphcraft
graphcraft install --host claudeIf the npm registry is unavailable, install the same executable directly from GitHub:
npm install --global https://github.com/tpypan/graphcraft/archive/refs/heads/main.tar.gz
graphcraft install --host codexFor a one-shot installation, use npx @tpypan/graphcraft install --host codex or pnpm dlx @tpypan/graphcraft install --host claude. The installer copies its MCP runtime to ~/.graphcraft/runtime/<version>/ before host registration, so clearing the package-manager cache does not break Graphcraft.
Installation registers one local MCP tool; Graphcraft does not inject a large prompt or install a skill. Start a new coding-agent session after installation.
You can also run Graphcraft directly:
graphcraft run --host claude \
"migrate every v2 client call to v3 and verify the repository"Graphcraft displays a concise run contract before doing work. Use --yes only when you have already reviewed and approved that contract.
- Lets the selected host propose a task-specific execution graph from bounded repository evidence, then validates and displays the actual plan before approval.
- Keeps the finish line, permissions, repository policy, and acceptance anchors outside worker control.
- Creates an isolated Git worktree without stashing, cleaning, or resetting the current checkout.
- Stores a hashed append-only event log and rebuildable state under the repository's local
.graphcraft/directory. - Gives each worker a small context capsule instead of replaying raw transcripts.
- Infers deterministic, task-family-specific progress and completion probes from repository evidence, then lets users inspect or replace the versioned probe plan before approval.
- Runs approved probes outside model context and classifies progress as advanced, learning, stalled, regressed, oscillating, blocked, or done.
- Schedules one evidence-driven repair when verification fails, then stops if the changed strategy does not clear the failure.
- Checkpoints host sessions and results during execution, resumes the same host session when safe, and falls back to repository evidence when switching hosts or native continuation is unavailable.
- Accepts pause or stop from another CLI process, terminates the active child with bounded escalation, and records the exact cause and outcome before releasing the run lock.
- Tracks cached, uncached, output, reasoning, and total tokens when the host exposes them.
graphcraft install --host <codex|claude>
graphcraft run <task>
graphcraft status [run]
graphcraft inspect [run]
graphcraft probes [run] [--set probe-plan.json]
graphcraft pause [run]
graphcraft resume [run]
graphcraft stop [run]
graphcraft trace [run]
graphcraft doctor
graphcraft uninstall --host <codex|claude>
Small localized tasks bypass Graphcraft by default. Pass --force when you deliberately want a durable graph.
The v0.1 implementation report records the acceptance boundary, architecture, tests, real-host dogfood, and known gaps. Research and competitive rationale live under docs/research.
Graphcraft does not yet claim stable reliability or a 20% token-savings gate. Those require a future matched multi-task, dual-host benchmark.
pnpm install
pnpm checkpnpm check formats, typechecks, tests, bundles both executables, enforces the plugin discovery-context limit, and verifies the exact npm tarball contents.