Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add Yeachan-Heo/oh-my-claudecode --skill graph -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/graph/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/graph/

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.

graph smallnest Turns a task, PRD, or issue set into a dependency graph (DAG), layers it into waves, and runs independent nodes concurrently — each in its own git worktree, via subagents. CX Codex +1 267installs graph Artem Novitckii graph is a Claude Code skill that makes a line-chart animation for a reel, with a counter that follows the line. It runs for /graph or requests for a growth chart or animated statistic. CX Codex +1 ★ 1,047repo stars mantis-pipeline-adapter official google mantis-pipeline-adapter — a skill for Claude Code, Codex, Cursor and other agents that walks you through designing a deterministic orchestrator harness around Mantis skills. CX Codex +1 1,600installs workflow-builder Alireza Rezvani workflow-builder is a Claude Code plugin for designing deterministic multi-agent JavaScript workflows. It splits complex tasks across fresh sub-agents to save context. ★ 30,251repo stars maestro-graph ReinaMacCredy maestro-graph — a skill for Claude Code and Codex that runs a task along a predefined graph: spawns agents on each node, collects results, and moves to the next step. CX Codex +1 ★ 238repo stars airflow-expert PCL Team airflow-expert guides Apache Airflow DAG design, task dependencies, operators, sensors, and scheduling. Use it when building or reviewing data workflows. CX Codex +1 174installs authoring-dags astronomer authoring-dags guides the creation and validation of Apache Airflow DAGs across a six-phase workflow. Useful when writing new data pipelines or adding downstream tasks to existing DAGs. CX Codex +1 1,300installs task-decomposer curiositech task-decomposer decomposes plain-text problem statements into structured sub-tasks for DAG nodes, spotting dependencies and parallel execution paths. CX Codex +1 155installs

From the same set48

The whole set →
ultragoal Splits a brief into ordered goals and keeps an append-only ledger in .omc/ultragoal, so a long run survives a session restart. CX Codex +1 575installs minimal-code-discipline The minimal-code-discipline skill enforces YAGNI discipline: check for existing code first, reach for the standard library, write new code last. CX Codex +1 316installs omc-review omc-review is a Claude Code skill that checks finished code for defects, risks, and bloat before release. It ranks issues by severity without making fixes. CX Codex +1 309installs execute The execute skill takes a well-defined task through implementation and verification. Use it when you want working code and a clear account of what was checked. CX Codex +1 307installs drydock drydock — a skill for Claude Code, Codex, Cursor, Copilot, and Gemini CLI that sets up a shared repo harness on first run. It seeds CLAUDE.md and GLOSSARY.md immediately; every other surface appears on first use. CX Codex +1 273installs launch launch — a skill for the complete development cycle: from mission to shipped, verified code. Splits work between agent (everything verifiable and repeatable) and human (decisions that only a person can make). CX Codex +1 272installs tdd tdd enforces a strict red-green loop: one test per agreed seam, minimal green implementation, and no mid-cycle refactoring. CX Codex +1 244installs harbor harbor triages incoming issues and pull requests, verifies each claim, and hands the maintainer only the decisions that genuinely need a signature. CX Codex +1 241installs

Project sponsors

Companies that keep this analytics open