Oh My Dag

oh-my-dag

Two ways to put cheap concurrent models behind your agent — call one capability, or hand off a whole graph.

Your agent stays the brain. omd brings the hands, the gates, and the memory.

[](docs/mcp-tools.md) [](client-skills/) [](docs/model-layer.md) [](https://bun.sh) [](LICENSE)

English · [中文](README.zh-CN.md) · [Get started →](docs/MCP-ONBOARDING.md)

The two tracks

Your coding agent is a strong, expensive brain. Using it to type out every file, read every page, and hold every plan in its head is the wrong job for the smartest thing in the room.

omd gives that agent two ways to delegate — and they share one substrate, so switching tracks never costs you reliability:

flowchart TB
  AGENT["Your agentClaude Code · Codex · any MCP client · omd's own TUI"]

  subgraph OMD["omd — one engine, two ways in"]
    direction TB

    subgraph T1["Track 1 · COMPOSE — call one capability at a time"]
      C1["omd_primitivejudge · verify · parallel · tournament · 12 shapes"]
      C2["omd_web / omd_distillfetch pages · distil insight"]
      C3["memory_recall / path_mapfacts that outlive the window"]
      C4["omd_shapesproven decompositions, and when NOT to use them"]
    end

    subgraph T2["Track 2 · GRAPH — hand off a whole fan-out"]
      G1["dag_runa conductor decomposes for you"]
      G2["dag_run_planyou wrote the graph, just run it"]
      G3["dag_review / dag_debug / dag_slim / dag_deepenpre-shaped fleets"]
    end

    BASE["Shared substratetyped plan · deterministic passes · oracle gates · cross-family verifiercheckpoints · model pools · cost accounting"]
    T1 --> BASE
    T2 --> BASE
  end

  MODELS[("Your modelsany OpenAI-compatible backend")]
  AGENT -->|MCP| T1
  AGENT -->|MCP| T2
  BASE --> MODELS

  classDef compose fill:#FAECE7,stroke:#993C1D,color:#4A1B0C
  classDef dagmode fill:#EEEDFE,stroke:#534AB7,color:#26215C
  classDef base fill:#E1F5EE,stroke:#0F6E56,color:#04342C
  classDef ext fill:#F1EFE8,stroke:#5F5E5A,color:#2C2C2A
  class C1,C2,C3,C4 compose
  class G1,G2,G3 dagmode
  class BASE base
  class AGENT,MODELS ext

Track 1 — compose. Call one capability and look at the result: run a judge over three attempts, fetch and distil a page, recall what you decided last week. Two to five steps, you stay in the loop.

Track 2 — graph. Hand off a whole fan-out: a task becomes typed nodes, they run the moment their dependencies settle, every node is checkpointed, and an interrupted run resumes instead of restarting. Ten nodes or a hundred, you go do something else.

The dividing line is scale, and the caller is the best judge of it. The four deterministic passes that make a graph worth it (prune, dedup, evidence, stamp) buy nothing on a 3-step composition and are load-bearing on a 40-node one.

Quick start

git clone https://github.com/AbyssCN/oh-my-dag.git && cd oh-my-dag
bun install && bun link      # puts `omd` on your PATH (Bun ≥ 1.3)
omd init                     # wizard: keys, model presets, reachability probe → .env

cd  && claude mcp add omd -- omd mcp

The slash-command pack (/omd-path, /omd-review, … 20 skills) installs itself into ~/.claude/skills/ on first server start — idempotent, and it never overwrites a skill you edited. Opt out with OMD_INSTALL_SKILLS=0.

→ [Full walkthrough](docs/MCP-ONBOARDING.md) · [command reference](client-skills/README.md)

Alternative front-end: the bundled terminal agent

bun run omd (interactive) or bun run omd -p "..." (one-shot); configure with OMD_RUNTIME_PROVIDER + OMD_RUNTIME_MODEL + your backend key in .env (copy [.env.example](.env.example)). The MCP server is the primary door; this is a convenience.

What you can call

flowchart LR
  subgraph EXEC["EXECUTE — get the work done"]
    E1["dag_run · dag_run_plan · dag_resumedag_status · dag_result · dag_runs"]
    E2["omd_primitive12 control-flow shapes"]
  end

  subgraph RESEARCH["RESEARCH — get to the bottom of it"]
    R1["omd_webzero model: search + fetch, full text to disk"]
    R2["omd_distillexpert: faithful · challenger: long tail"]
    R3["dag_researchfetch + multi-lens synthesis, judged"]
  end

  subgraph AUDIT["AUDIT — find what is wrong"]
    A1["dag_reviewmany dimensions, cross-family falsification"]
    A2["dag_debug · dag_slim · dag_deepen"]
    A3["omd-shots-verifyzero model: shots exist and are not blank"]
  end

  subgraph MEMORY["MEMORY & PLANNING — outlive the context window"]
    M1["memory_recall · memory_rememberdream_consolidate"]
    M2["path_map · path_add · path_rulepath_deliver · path_prefetch"]
  end

  subgraph KNOW["KNOWLEDGE — stop reinventing the shape"]
    K1["omd_shapesgraph shapes, and when NOT to use them"]
    K2["template cardsexpert checklist injected into a node"]
  end

  classDef llm fill:#EEEDFE,stroke:#534AB7,color:#26215C
  classDef zero fill:#E1F5EE,stroke:#0F6E56,color:#04342C
  classDef mixed fill:#FAECE7,stroke:#993C1D,color:#4A1B0C
  class E1,E2,R3,A1,A2 mixed
  class R1,A3,K1,K2 zero
  class R2,M1,M2 llm

Execution — dag_run (a conductor decomposes for you) · dag_run_plan (you wrote the graph) · dag_resume (pick up where a broken run stopped) · omd_primitive (one control-flow shape, no graph required) · dag_status / dag_result / dag_node_output / dag_runs.

Research — omd_web (search + fetch, zero LLM; full text to disk, only an index comes back) · omd_distill (two lenses over text you already have: one faithful, one adversarial) · dag_research (fetch + multi-lens synthesis with a judge panel).

Audit — dag_review (multi-dimension diff review, each dimension routable to a different model family) · dag_debug · dag_slim (deletion-only over-engineering audit) · dag_deepen (architecture hotspots).

Memory & planning — memory_recall / memory_remember / dream_consolidate · path_map / path_add / path_rule / path_deliver / path_prefetch (a decision map in git, advanced by typed tickets, with background research that outlives your client).

Knowledge — omd_shapes (proven graph shapes, each with the trigger and the "not when") · template cards (a vetted specialist checklist injected into a node at run time).

Config — omd_config_status / omd_set_model / omd_set_role / omd_apply_preset / …

→ [Full tool reference](docs/mcp-tools.md)

Deep research, benchmarked

One command fans a question across cheap concurrent models, keeps every source on disk with zero loss, synthesizes through competing lenses, closes its own gaps by re-crawling, and lets a judge panel pick the winner.

bun run scripts/dag-research.ts "" --deep

We put it head-to-head against an all-frontier alternative on the same question (a mid-2026 MCP ecosystem review). System A — omd --deep on cheap seats. System B — a 106-agent Claude workflow where every agent is a frontier model.

| | A · omd --deep | B · 106-agent frontier workflow | |---|---|---| | Cash cost | $2.19 | subscription quota · 3.76M tokens | | Result | 132k-char report · 32 sources | 23 claims, verified 3-of-3 | | The catch | finished clean | hit the limit before it finished |

> A cheap stack reproduced 13 of the 15 facts the frontier workflow verified — for $2.19.

Not because the small models are secretly frontier-grade. Because deep research has a deterministic retrieval floor: omd_web fetches with no model in the loop, full text lands on disk, and gaps close by re-crawling the missing source, never by a model filling them from memory. The model does synthesis; the engine does recall. That is the whole repo's thesis, measured on one task — reliability comes from outside the model.

flowchart LR
  Q(["question"]) --> G["gatherzero-LLM search + fetchfull text to disk"]
  G --> S["synthesizelenses fan out, a panel judges"]
  S --> D["deepen ×3find gaps → re-crawl → mine only the gaps"]
  D -->|no new finds| R(["cited report+ zero-loss appendix"])
  D -.->|new finds| S
  classDef zero fill:#E1F5EE,stroke:#0F6E56,color:#04342C
  classDef llm fill:#EEEDFE,stroke:#534AB7,color:#26215C
  classDef infra fill:#F1EFE8,stroke:#5F5E5A,color:#2C2C2A
  class G zero
  class S,D llm
  class Q,R infra

→ [How it works, the models, and the full A/B benchmark](docs/deep-research.md) · [sample output](docs/examples/deep-research-mcp-2026.md)

How the graph runs

A task is planned once by an LLM, then transformed by pure functions, then executed by dependency order. Everything after the conductor is deterministic.

flowchart TB
  TASK(["TASK"])

  subgraph PLAN["1 · PLAN — one LLM call, everything after it is a pure function"]
    direction TB
    CD["Conductordecomposer seat · frozen prefix + task"]
    PJ["Plan JSONzod-validated · unknown card rejects the plan"]
    P1["prunecut nodes nothing consumes"]
    P2["dedupmerge by semantic key"]
    P3["evidenceUI pixel-chain gate"]
    P4["stamppin a model: pick pool, then 3 rules"]
    CD --> PJ --> P1 --> P2 --> P3 --> P4
  end

  subgraph EXEC["2 · EXECUTE — dependency-driven, no level barrier"]
    direction TB
    RS{{"Ready-set schedulera node waits only for its own deps"}}
    L1["inproc leafone shot, no tools"]
    L2["agent leaftools + bwrap jailthe only kind that writes files"]
    L3["commandzero LLM · allowlisted CLI"]
    L4["map · primitiveruntime fan-out / engine-owned control flow"]
    UI["UI evidence branchrender command prints image pathsthen attach_media leaf judges real pixels"]
    RS --> L1 & L2 & L3 & L4
    L2 -.-> UI
    L3 -.-> UI
  end

  subgraph FB["3 · FEEDBACK — objective gate first, model judgement second"]
    direction TB
    FI["Fan-insummaries, never transcripts"]
    OG["Oracle gatetsc + test · zero LLM, cannot hallucinate"]
    VF["Verifierverify seat · cross-family · fails on doubt"]
    HL["Heala red gate becomes a repair task"]
    ES["Escalationemits a node PATCH; untouched nodes stay byte-identical"]
    FI --> OG --> VF
    OG -->|red| HL
    VF -->|rejected| ES
  end

  CP[("Checkpoint.omd/continuity/runId")]

  TASK --> CD
  P4 --> RS
  L1 & L2 & L3 & L4 --> FI
  UI --> FI
  L1 & L2 & L3 & L4 -.->|every done node lands atomically| CP
  CP -.->|resume: same input hash = green, re-run only the rest| RS
  HL --> RS
  ES --> CD

  classDef llm fill:#EEEDFE,stroke:#534AB7,color:#26215C
  classDef pure fill:#E1F5EE,stroke:#0F6E56,color:#04342C
  classDef exec fill:#FAECE7,stroke:#993C1D,color:#4A1B0C
  classDef infra fill:#F1EFE8,stroke:#5F5E5A,color:#2C2C2A
  class CD,PJ,VF,ES llm
  class P1,P2,P3,P4,OG,L3 pure
  class L1,L2,HL,UI exec
  class TASK,RS,L4,FI,CP infra

Purple = an LLM call · teal = deterministic, zero LLM · coral = executor · grey = engine structure.

Node kinds — what a node can be:

| Kind | Model? | Tools? | Use for | |---|---|---|---| | leaf | one shot | no | generation, research, judgement, drafting | | agent | yes | read/edit/write/bash, in a bwrap jail | the only kind that writes files | | command | none | a CLI from an allowlist | gates (tsc/tests), scanners, indexed lookups | | map | mixed | — | runtime fan-out: a lister discovers the work-list, one child per item | | primitive | mixed | — | 12 control-flow shapes the engine owns |

Plan passes — pure functions between the plan and execution: prune (drop dead nodes) → dedup (semantic-key merge) → evidence (UI pixel-chain gate) → stamp (pin a model on every node).

Control-flow primitives — you pick the shape and its params; the loop / branch / stop / scoring logic belongs to the runtime, never to the model: parallel · pipeline · loop-until · verify · judge · discovery · iterate · tournament · router · race · escalation · saga.

→ [Architecture in depth](docs/architecture.md) · [primitives](docs/primitives.md) · [diagram source](docs/diagrams/01-engine-flow.md)

Which model runs which node

flowchart TB
  N["a node needs a model"]

  N --> R1{"node.model set?"}
  R1 -->|yes| USE["use it"]
  R1 -->|no| R2{"template card pins a model?"}
  R2 -->|yes| USE
  R2 -->|no| STAMP["stamp pass picks from a pool"]
  STAMP --> USE
  USE --> EFF["reasoning effortnode.thinking > run config > seat tier > defaulttransport clamps per provider"]

  subgraph POOLS["pools — capability first, then tier"]
    direction TB
    P0["attach_media? → multimodal pool(tier:strong → the SOTA multimodal pool)"]
    P1["tier:strong → strong pool — ≥2 families"]
    P2["default → mid pool"]
    P3["tier:cheap → cheap pool"]
  end
  STAMP -.-> POOLS

  subgraph RULES["stamp rules, in priority order"]
    direction TB
    S1["chain affinity — inherit upstream, keep the prompt cache"]
    S2["sibling spread — siblings get different model families"]
    S3["rotation — spread load inside the tier"]
  end
  STAMP -.-> RULES

  classDef pick fill:#EEEDFE,stroke:#534AB7,color:#26215C
  classDef pool fill:#E1F5EE,stroke:#0F6E56,color:#04342C
  classDef rule fill:#FAECE7,stroke:#993C1D,color:#4A1B0C
  classDef plain fill:#F1EFE8,stroke:#5F5E5A,color:#2C2C2A
  class R1,R2,STAMP pick
  class P0,P1,P2,P3 pool
  class S1,S2,S3 rule
  class N,USE,EFF plain

Two things stay deliberately separate: a template card says how the work is done (method, checklist, output discipline); a seat or pool says who does it (which model coordinate). They compose freely — the same card runs on any model, one model executes many cards. That is the main structural difference from a subagent, where "who" and "how" are welded into one definition.

The seats at a glance

omd routes work to 14 named seats in five functional classes. Pin any of them once in .omd/config.json models and every resolver reads that one value. Rule of thumb: strong where being wrong is expensive and rare; cheap where volume is high and an oracle catches mistakes.

| Class | Seats | Does | Reach for | |---|---|---|---| | decomposer | conductor · escalation | shapes / repairs the plan graph | strong (SOTA brain) | | judge_synth | judge · reason · reduce | picks winners, reasons, folds results | strong to judge; cheaper to fold | | worker | leaf · agent · lens · expand · distill · overflow | volume execution behind a gate | cheap–mid (family ≠ quality here) | | verify | verifier · review-spec | adversarial cross-check | mid, different family from the author | | dream | dream | memory consolidation | cheap–mid |

Auto-assign fills these by channel economics, not by scattering families — diversity is spent only where it changes the answer (verify is off the author's family on purpose; research lens seats want several). Full per-seat table, the weak/strong rationale, and how to register OAuth/subscription models (Claude · GPT · Kimi) → [model configuration guide](docs/model-config.md).

→ [Model layer in depth](docs/model-layer.md) · [diagram source](docs/diagrams/04-model-layer.md)

Why it holds together

Two halves of one principle. Systems that state only the first end up mechanising the model away; systems that state only the second end up trusting it where trust is not checkable.

> Reliability comes from outside the model. Gates judge — did it happen, is it there, does it > pass? Deterministic, zero-model, fail-closed. A model "having a look" is not a gate: when it > silently does not run, nothing turns red. > > Creativity comes from inside it. Models generate — what to do, how to do it, what is still > missing. Inside the gates, do not replace this with rules. Replacing generation with a mechanical > rule marks a frontier model down to the expressive power of that rule.

Three corollaries that decide real designs:

1. A deterministic detector is a floor, not a ceiling. It guarantees the obvious miss does not

get missed; it must never become the only thing allowed t

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AbyssCN
• Source: AbyssCN/oh-my-dag
• License: MIT

Install and usage instructions live in the source repository linked above.