Docs / Get started

Install & onboard GraphSmith

One install puts GraphSmith into every AI coding agent on your machine. Describe a job in plain English, approve a one-screen blueprint, and get a workflow that's proven to survive failure. This guide takes you from zero to a chaos-tested workflow.

Overview

GraphSmith is a skill your AI agent follows — it injects reliability engineering at the moment code is generated, so you don't have to know it. It hardens the three ways every multi-step agent breaks:

Amnesia → save points: a crash resumes at the exact step it stopped, never from zero.
Duplication → exactly-once: recorded effects run once, even after power loss; an uncertain send halts loudly instead of re-firing.
Hallucination → citations: every claim about your code cites a real file via KnoSky, or is flagged as a guess.

It's MIT-licensed, zero-dependency, needs no API keys, and phones home to nothing. As of v0.2.0 it's also a protocol: a workflow either passes graphsmith verify or it doesn't.

Which reader are you?

The skill serves everyone; pick the path that matches you.

Path A

“I just want it working”

Install, say what you want, run it. No jargon, no theory. Start at the quickstart.

Path B

“My automation keeps breaking”

Point the linter at your repo and fix the exact rule that broke. Jump to fix a broken automation.

Path C

“I'm evaluating this for my org”

Read the trust story, invariants, and the 11-Document framework on the regulated-teams page.

60-second quickstart

Three commands and one sentence:

terminal

# 1. install into every agent on your machine
npx skills add SathiaAI/graphsmith

Then open your AI coding agent and say:

Say this“Build me an agent that researches new leads and drafts outreach emails.”

The skill takes over: it proposes a one-screen blueprint, waits for your approval, generates a runnable project, and hands it over chaos-tested. On Claude.ai, just open the .skill file and click Save skill.

Time-to-first-valueThe scaffolded project runs immediately with stub workers and no API keys — so you can see it work before wiring in your own model.

One-line install

The recommended path installs GraphSmith into whichever AI coding agents the skills CLI detects on your machine:

recommended

npx skills add SathiaAI/graphsmith

Prefer to clone first? The installer detects every AI coding agent on your machine and installs into each:

from source

git clone https://github.com/SathiaAI/graphsmith
node graphsmith/scripts/install.js

RequirementsPlain Node 18+. The scripts are dependency-free and run identically on macOS, Linux, and Windows.

Per-platform matrix

GraphSmith works identically anywhere that implements the Agent Skills open standard. Each install below is already correct — copy, paste, done.

Platform	Install	First run
Claude Code	`npx skills add SathiaAI/graphsmith` (auto-detected)	Say the prompt
Claude.ai	Open the `.skill` file → Save skill	Say the prompt
Codex CLI	Universal installer (auto-detected)	Say the prompt
Gemini CLI	Universal installer (auto-detected)	Say the prompt
Cursor	Universal installer (auto-detected)	Say the prompt
Windsurf / Devin	Universal installer	Devin CLI: invoke with `/graphsmith`
Hermes	Universal installer	Say the prompt
VS Code Copilot	Universal installer	Say the prompt
+ 25 others	Agent Skills standard · Node 18+, incl. Windows	Say the prompt

Claude.ai (.skill file)

On Claude.ai there's no CLI — installation is a click:

Download the packaged dist/graphsmith.skill from the repo.
Open the .skill file in Claude.ai.
Click Save skill. Then describe your job in chat.

Updating

Pull the latest and re-run the installer with --force:

terminal

git pull
node graphsmith/scripts/install.js --force

KnoSky self-updates each session via knosky-sync.js and degrades gracefully when offline.

Offline & Windows

In sensitive or air-gapped environments, disable all network activity with one environment variable:

offline mode

GRAPHSMITH_OFFLINE=1 node graphsmith/scripts/install.js

The scripts are plain Node and run identically on Windows. Nothing touches the network except an explicit, inspectable KnoSky version check — and that's what GRAPHSMITH_OFFLINE=1 disables.

NeverNever put real production data in test environments, and never paste live secrets into prompts or indexes. Agents read secrets from the environment, never from files they can echo back.

Your first workflow (Path A)

Say what you want in plain English — the skill activates on its own. It then walks four steps, and you approve before any code is written:

Describe it. “Build me an agent that researches leads and drafts outreach.”
Approve the blueprint. One screen: workers, handoffs, save points, stop rules.
It builds the project. A runnable, zero-dependency Node project.
It proves it. A chaos test kills the run mid-flight and verifies recovery.

Run the generated project:

terminal

cd your-project
node manager.js

The blueprint gate

Nothing is built until you approve a one-screen plan with four parts:

Part	What it pins down
Workers	One job each, one line each.
Handoffs	Who passes what to whom — only the fields needed.
Save points	“Crash at step 3 restarts at step 3, not step 1.”
Stop rules	End condition plus hard retry/loop caps. Nothing runs forever.

Why a gateArchitecture decided by vibes gets discovered in production. Approving the blueprint first is the cheapest bug fix you'll ever make.

Run & resume

The generated manager.js routes deterministically and writes a per-step checkpoint keyed by run ID. If it crashes, just run it again — it resumes from the last save point instead of restarting:

resume after a crash

node manager.js   # picks up exactly where it stopped

Then replace the stub workers in workers/ with your real logic — LLM and API calls live only inside workers, and each stub's comments say exactly what to preserve and why.

Fix a broken automation (Path B)

Already have an agent that misbehaves? Tell your agent the symptom and let the linter map it to the broken rule, with file and line:

terminal

node graphsmith/scripts/graphlint.js path/to/your/agent

Symptom	Broken rule
Forgets where it left off	No save points
Sent it three times	Not safe to re-run (no exactly-once guard)
Loops forever	No stop rules
Makes stuff up about the codebase	Ungrounded — needs KnoSky

Findings are heuristic — verify each against the live file before applying the proposed smallest fix. The linter won't rewrite what already works.

The chaos harness

Proof, not promises. The harness works on any project following the scaffold's checkpoint conventions:

terminal

node graphsmith/scripts/chaos.js your-project

A full (green) pass verifies five properties:

Kill test — SIGKILLs the run mid-flight and asserts it resumed from the last save point.
Double-run test — asserts no recorded side effect ran twice across the crash/resume cycle.
Power-loss probe — stages the state a lost flush leaves and proves the restart halts instead of re-sending.
Lock probes — a concurrent manager refuses; a dead holder's lock is stolen; a recycled pid is judged by its lease.
Halt path — a crash inside a side-effect window halts loudly with UNRESOLVED SIDE EFFECT — that's the guard working, and it counts as a pass.

What it proves — and doesn'tThe harness proves crash recovery and exactly-once execution of recorded effects. True exactly-once delivery to an external system also needs an idempotency key that system honours (the worker stubs build runId:step for you). A workflow can pass and still compute the wrong answer — that's what your acceptance tests are for.

graphsmith verify & CI

Turn the discipline into an enforceable gate. graphsmith verify reports capability profiles — resumable, effect-reconciled, budget-enforced, integrity-verified, adversarially-tested — with linked evidence, and runs on every pull request through a GitHub Action or GitLab template.

CI · GitHub Actions

# .github/workflows/graphsmith.yml (excerpt)
- name: graphsmith verify
  run: node graphsmith/scripts/chaos.js ./workflow

KnoSky setup (grounding)

KnoSky turns your repo into a local map plus a read-only connector your AI cites from. It indexes pointers (titles, headings, short excerpts) — never file bodies — and nothing is uploaded anywhere. Try it standalone with the pinned, integrity-checked version this release was reviewed against:

from your project root

npx knosky@0.6.3 .

It builds a local index (writes to a .knosky/ folder in your repo) and prints an MCP config. Register that config per your agent — Claude, Codex, Gemini, and Cursor each have their own MCP settings.

A map, not an oracleKnoSky routes agents to the right files with citations; the agent still reads the live source. Its one job is to stop the agent inventing files — free under FSL.

The scripts

Everything is dependency-free Node you can read in five minutes and vendor freely.

Script	What it does
`install.js`	Installs the skill into every agent on your machine.
`scaffold.js`	Generates a runnable, zero-dependency project: manager, workers, save points, resume, retries, logs.
`chaos.js`	Kills the workflow mid-flight, restarts, and asserts recovery + exactly-once recorded effects.
`graphlint.js`	Project-aware scan of existing agent code for the classic failure patterns.
`knosky-sync.js`	Prepares pinned, content-hash-verified KnoSky grounding via npx.

FAQ

Do I need to know how to code?

No. Describe the outcome and approve the blueprint. You'll eventually edit worker files, but each is small, single-purpose, and commented in plain English.

Do I need API keys to try it?

No. The scaffolded project runs immediately with stub workers; wire in your model when you replace them.

Does my code get uploaded anywhere?

No. Scripts run locally; KnoSky is local-first and indexes pointers on your machine only. No telemetry.

How is this different from LangGraph / Temporal?

Those are frameworks you learn for large-scale durable execution. GraphSmith is the discipline enforced at generation time, with a zero-dependency start and an explicit graduation path to those frameworks. On-ramp, not competitor.

Is it free?

Yes. The skill is MIT; KnoSky is free under FSL.