graph · yeachan-heo — Claude Code skill: DAG pipelines with crash recovery
Run multi-step pipelines as declarative directed acyclic graphs. If interrupted or restarted, execution resumes from the journal without re-running completed nodes.
MIT 285 installs ★ 40,997 updated 2026-10-24
npx skills add Yeachan-Heo/oh-my-claudecode --skill graph -a claude-codeWhat graph does
The graph skill executes pipelines defined in JSON: nodes (command, agent, human-approval) connected by edges, each with timeout and retry limits. The runtime infers dependencies and parallelizes where possible. Commands run through omc graph run; agents operate read-only.
Crash recovery works via journal: kill or interrupt the process, rerun the same command, and the graph skips done nodes and continues. This makes graph suited for long, deterministic pipelines but not work that needs to adapt mid-run. Approval nodes require interactive mode (! prefix) because they need stdin; Bash tool cannot handle them.
All runs record a journal and snapshots under .omc/graph-runs/<run_id>/. The descriptor is the executable; treat it as untrusted content if it comes from elsewhere.
What it helps with
- Orchestrate repeatable workflows with explicit task dependencies
- Resume a halted pipeline without re-executing finished steps
- Coordinate commands and agents in one directed graph
- Route execution through a human approval gate
Example prompts for the agent
- /oh-my-claudecode:graph build-and-test.json
- Run a graph for build, test, then deploy from
pipeline.json - Resume the graph after a crash by running the same command again
How to install graph
1Skills CLI (Vercel)
npx skills add Yeachan-Heo/oh-my-claudecode --skill graph -a claude-code2Manually: put the files in place
~/.claude/skills/graph/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/graph/
1Skills CLI (Vercel)
npx skills add Yeachan-Heo/oh-my-claudecode --skill graph -a codex2Manually: put the files in place
.agents/skills/graph/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add Yeachan-Heo/oh-my-claudecode --skill graph -a cursor2Manually: put the files in place
.cursor/skills/graph/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install Yeachan-Heo/oh-my-claudecode skills/graph2Manually: put the files in place
.github/skills/graph/SKILL.md1Skills CLI (Vercel)
npx skills add Yeachan-Heo/oh-my-claudecode --skill graph -a gemini-cli2Platform CLI
gemini skills install https://github.com/Yeachan-Heo/oh-my-claudecode --path skills/graphManually: put the files in place
.devin/skills/graph/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add Yeachan-Heo/oh-my-claudecode --skill graph -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about graph
How do I install graph in Claude Code?
Run npx skills add Yeachan-Heo/oh-my-claudecode --skill graph -a claude-code, then open ~/.claude/skills/graph/SKILL.md.
What does graph do?
It executes pipelines described as JSON DAGs with command, agent, and approval nodes. If the process crashes, rerun the same command and execution resumes from the journal.
How is graph different from a shell script?
Graph is declarative: you describe task dependencies, not sequence. It parallelizes independent nodes, respects timeouts, and survives interruption. A script runs commands in order with no recovery.
Source text
SKILL.md · MIT
---
name: graph
description: Deterministic orchestration graph runtime - declarative DAG pipelines with journal-based crash recovery
argument-hint: "<descriptor.json | describe the pipeline> [--runs-root <dir>]"
aliases: []
level: 4
---
# Graph Skill
Run a deterministic orchestration graph from a declarative JSON descriptor.
The runtime consumes the sealed-descriptor and pure-scheduler contracts in
`src/graph/*` and executes through an independent OS process (`omc graph run`),
so crash recovery (kill mid-run, rerun, resume from journal) works for real.
## Usage
```
/oh-my-claudecode:graph <descriptor.json>
/oh-my-claudecode:graph "build then test then ask me before deploy" (author the descriptor first)
```
The execution surface is always the CLI subcommand:
omc graph run <descriptor.json> [--runs-root <dir>]
Run it via the Bash tool for non-interactive graphs. Progress lines stream as
`[run]`, `[node]`, `[ok]`, `[fail]`, `[join]`, `[done]`.
## When To Use
- Repeatable multi-step pipelines with explicit dependencies (DAG)
- Work that must survive interruption: kill/restart resumes from journal
- Auditable runs: OCC journal + projection snapshots under `.omc/graph-runs/<run_id>/`
When NOT to use: exploratory one-off work (use conversation or /team);
anything needing adaptive re-planning mid-run (graphs are deterministic).
## Workflow
1. **Descriptor given** -> go to step 3.
2. **Pipeline described** -> author the descriptor JSON (schema below), write
it next to the project (suggest `.omc/graphs/<name>.json`) and show it to
the user before running. `run_id` must be unique per logical pipeline;
rerunning with the same `run_id` RESUMES, not restarts.
3. **Approval nodes**: if the descriptor contains any `"kind": "human-approval"`
node, do NOT run it through the Bash tool (stdin is not interactive there;
EOF fails closed to denied). Tell the user to run interactively instead:
! omc graph run <file>
The `!` prefix runs it inside this session with live stdin so y/n works.
4. Run and relay progress. Exit codes (normative):
0 succeeded | 1 terminal failed | 19 another writer owns this run (busy)
20 corrupt/tampered journal (fail-closed) | 21 descriptor drift on resume
| 70 runtime crash (unmapped error)
5. **Resume**: rerunning the same command after a crash replays committed
transitions and continues. Completed nodes never re-execute.
## Descriptor Schema (minimal)
{
"descriptor_version": 1,
"run_id": "unique-pipeline-id",
"revision_id": "rev-1",
"goal": "one line",
"nodes": [
{ "id": "n1", "kind": "command", "title": "...", "timeout_ms": 60000,
"max_attempts": 2, "effect_policy": { "policy": "side_effect_free" },
"command": "npm test" },
{ "id": "a1", "kind": "agent", "title": "...", "timeout_ms": 300000,
"max_attempts": 1, "effect_policy": { "policy": "side_effect_free" },
"instructions": "..." },
{ "id": "gate", "kind": "human-approval", "title": "...",
"prompt": "Proceed?" }
],
"edges": [ { "id": "e1", "kind": "fixed", "from": "n1", "to": "a1" } ],
"entry_node_ids": ["n1"],
"concurrency_limit": 2,
"terminal_verification_node_id": "a1"
}
Edge kinds: fixed | conditional | fan_out/join pairs
| back_edge (bounded retries via max_traversals). See src/graph/schema.ts for
the authoritative Zod schema — and read the Capability Boundary section above
for what built-in executors actually execute today.
## Capability Boundary & Semantics (read before authoring)
- **Edge support**: built-in command/agent executors cover `fixed` edges and
`fan_out`/`join` pairs. `conditional` and `back_edge` routes are fully
supported by the runtime and scheduler contracts but require a custom
NodeExecutor that emits `route` on its results — built-in executors never
produce routes, so graphs relying on them fail fast with
`route_required` rather than guessing.
- **Crash-recovery guarantee is at-least-once** for command nodes: a crash
between an external side effect and its journal append re-executes that node
on resume. For `idempotent` commands, the resolved key is available to the
command as `GRAPH_IDEMPOTENCY_KEY` before it starts and is also recorded for
downstream dedupe. Built-in executors reject `reconcile`; reconciliation
requires a custom executor with an actual external reconciliation authority.
Exactly-once for external side effects is out of scope for v1.
- **Command trust boundary**: command nodes are arbitrary shell lines with
process authority in the current working directory. Only run descriptors
you wrote or trust. Command children receive an allowlisted environment
(PATH, HOME/USERPROFILE, TEMP/TMP, locale/timezone, USER identity,
`GRAPH_*`, and the optional idempotency key), not the host's full secrets.
Commands are not filesystem/process sandboxed.
- **Agent authority boundary**: built-in agent nodes are explicitly read-only.
They run in the current working directory with no additional directories,
only `Read`, `Glob`, and `Grep`, `permissionMode: dontAsk`, session
persistence disabled, and a provider-specific environment allowlist. Agent
timeouts abort and interrupt the SDK query. Use a custom executor for any
agent that needs mutation or external effects. Treat
`.omc/graph-runs/<run_id>/descriptor.json` as executable content.
© Yeachan-Heo · MIT · Yeachan-Heo/oh-my-claudecode
Similar skills
All skills for Agent setup: memory, context, orchestration →graph by other authors comes first.