Install & onboard GraphSmith

Overview

GraphSmith is three things at once: a skill your AI agent follows to build a reliable workflow, a protocol (v0.2.0) that proves the workflow survives failure on any model in your CI, and — as of v0.3.0 — an attestation standard (GSA) that signs a replayable, tamper-evident record of every run. It injects reliability engineering the moment code is generated, so you don’t have to know it. Under the hood 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 → once, replay-verified: 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.

Skill vs protocol

Same engine, two surfaces. The skill is how a reliable workflow gets built; the protocol is how it gets verified — by any agent, on any model, enforced in your repo instead of the agent’s goodwill. You’ll use both: the skill each time you create or change a workflow, the protocol each time you need to trust one.

The protocol is GRAPHSMITH-PROTOCOL v0.1 (draft) — it describes implemented, tested behavior and may change until v1.0. Its five invariants are verified integrity, a hash-pinned and gated core, isolated evaluation, local-by-default operation, and observable & killable runs. For how they’re checked and reported, see graphsmith verify & CI; for the trust story and evidence framework, see the regulated-teams page.

Which reader are you?

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

60-second quickstart

Three commands and one sentence:

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

Then open your AI coding agent and say:

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.

One-line install

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

npx skills add SathiaAI/graphsmith

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

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

Per-platform matrix

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

Claude.ai (.skill file)

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

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

Updating

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

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:

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.

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:

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

Run the generated project:

cd your-project
node manager.js

The blueprint gate

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

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:

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:

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

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:

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.

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.

# .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 ships against:

npx knosky@0.8.0 .

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.

The scripts

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

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.