OpenExpertise

OpenExpertise

Your team's best workflows — version-controlled, reproducible, self-improving.

[](https://www.npmjs.com/package/@openexpertise/cli) [](https://github.com/xingchengxu/OpenExpertise/actions/workflows/ci.yml) [](https://xingchengxu.github.io/OpenExpertise/) [](#) [](#) [](LICENSE)

[Install](#install) · [60-second demo](#60-second-demo) · [Why](#why-openexpertise) · [Examples](#built-in-examples) · [Compare](#vs-the-alternatives) · Docs site →

---

What it is (in one sentence)

OpenExpertise is the AI-era Makefile: write your team's SOPs as YAML graphs, run them with deterministic flow + LLM-powered nodes, and let the LLM propose graph upgrades after each run.

# examples/review-branch/experience.yaml — 10 lines, real result:
graph:
  nodes:
    - { id: bugs, kind: agent, prompt: 'Find bugs in {{diff}}', writes: [findings] }
    - { id: security, kind: agent, prompt: 'Find injection flaws in {{diff}}', writes: [findings] }
    - { id: score, kind: agent, reads: [findings], writes: [risk_score] }
  edges:
    - { from: bugs, to: score }
    - { from: security, to: score }

• Repeatable — same DAG every run, JSONL audit log, SQLite state you can query hours later
• Multi-vendor — one graph calls Claude Code, Codex, and Gemini; state flows between all three
• Self-improving — oe evolve reads what happened and proposes the next YAML patch

It's NOT an autonomous agent. It's the orchestration layer that lets you wire deterministic code, LLM agents, and CLI agents (Claude Code / Codex / Gemini) into reproducible, persistent, self-improving pipelines.

---

Install

npm install -g @openexpertise/cli      # the `oe` command — Node 20+
oe doctor                              # verify env (CLI agents, API keys, write perms)
oe init my-first                       # scaffold a minimal no-LLM flow
oe init my-flow --template full-pipeline   # 4 templates: tool-only | agent | cli-agent | full-pipeline
oe registry                            # see 5 curated experiences (need API key to run)
oe demo                                # see pre-recorded runs of bundled examples (zero API key)
oe demo review-branch                  # preview the PR review flow + advisor's evolution proposal

> Don't want to write YAML by hand? Run oe ultra "describe your task in one sentence" and the LLM scaffolds the whole experience — graph, prompts, tool stubs with // TODO: markers, and validation. oe ultra runs a built-in critique→revise quality loop (--max-rounds, default 1; --max-rounds 0 for the legacy one-shot) that feeds deterministic validation/preflight errors back to an incremental reviser and keeps the best-scoring draft. See the 30-min oe ultra tutorial.

> New to OpenExpertise? Walk through the 30-minute "Your first experience" tutorial — by the end you'll have a tested, registry-submittable flow you built yourself.

See any experience as a diagram

oe graph turns any experience into a Mermaid diagram — paste it straight into a GitHub README (or --html for a standalone page).

oe graph examples/review-branch

flowchart TD
  subgraph phase_collect["collect"]
    fetch_diff["fetch_diff"]:::tool
    seed_dimensions["seed_dimensions"]:::tool
  end
  subgraph phase_review["review"]
    bug_review("bug_review
⟳ for each $.dimensions"):::agent
  end
  subgraph phase_verify["verify"]
    verify_finding("verify_finding
⟳ for each $.findings"):::agent
  end
  subgraph phase_score["score"]
    score("score"):::agent
  end
  fetch_diff --> seed_dimensions
  seed_dimensions --> bug_review
  bug_review --> verify_finding
  verify_finding -->|"length($.findings) > 0"| score
  classDef tool fill:#e3f2fd,stroke:#1565c0
  classDef agent fill:#ede7f6,stroke:#5e35b1

Already ran it? oe inspect --experience --html -o report.html writes a self-contained run report — the DAG colored by each node's status (success/failed/skipped), an events timeline, and per-node duration + tokens. Pin it to a PR.

Pull any public GitHub repo with an experience.yaml:

oe install gh:owner/repo               # latest commit
oe install gh:owner/repo@v1.2.3        # pin to tag/SHA
oe submit --tags x,y                   # submit YOUR experience to the curated registry

Want yours discoverable via oe install ? Run oe submit inside your experience directory — opens a pre-filled GitHub issue with the registry entry generated for you.

📖 Full docs: https://xingchengxu.github.io/OpenExpertise/ — guide, all 12 examples, 10-recipe cookbook, API reference, comparison vs LangGraph/CrewAI/Mastra/Inngest, operations playbook.

---

60-second demo

npm install -g @openexpertise/cli
git clone https://github.com/xingchengxu/OpenExpertise && cd OpenExpertise

export ANTHROPIC_API_KEY=sk-...        # or OPENAI_API_KEY=...
oe run examples/review-branch --tui

You'll see three reviewers (bugs/perf/tests) fan out over a Python diff. They find missing null-check + missing test + unclosed cursor — but miss the SQL injection.

ⓘ run-2026-05-26-a1b2c3 finished
  findings: 3 issues
  risk_score: 0.30

Now ask the evolution advisor what's missing:

oe evolve run-2026-05-26-a1b2c3
# → wrote .openexpertise/evolution/run-2026-05-26-a1b2c3.md
#   proposal: "Add `security` dimension — default reviewers focus on
#              logic/tests; injection bugs need a dedicated reviewer."

Apply the one-line YAML patch from the proposal and re-run:

ⓘ run-2026-05-26-d4e5f6 finished
  findings: 4 issues (+ SQL injection in /users/)
  risk_score: 0.85

The experience improved itself. Author → run → evolve, all driven by the same LLM. That's the whole story.

---

Why OpenExpertise

> Five reasons it's different from every other AI workflow tool.

| | What it gets you | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Code-as-Law | YAML schema validates structure. LLMs only fill the gaps inside nodes — they can't rewrite the graph at runtime. No drift, no surprises. | | 6 node kinds in one graph | tool (deterministic code) · agent (LLM + structured output) · skill (SKILL.md packages) · dataset (file / SQLite / HTTP) · experience (nested) · cli-agent (delegate to Claude Code / Codex / Gemini) | | Persistent SQLite state | Every node's writes land in a typed blackboard. oe state findings works hours later. Resume with oe resume and replay cached steps. | | Self-improving | oe evolve reads the events + state diff and proposes graph upgrades as git apply-ready diffs; oe evolve --runs a,b,c analyzes several runs to surface stable patterns vs one-off blips. The author → run → evolve loop closes. | | Two-way agentic-CLI integration | Outbound: delegate a node to Claude Code / Codex / Gemini. Inbound: oe-mcp exposes 8 OE tools (incl. oe_graph) so the same CLIs can run, visualize, and evolve experiences from inside their own sessions. |

---

vs the alternatives

| | OpenExpertise | LangGraph | CrewAI | /workflows (Anthropic) | Claude Code | | ------------------------------------------------------ | :------------------------------------------------------: | :-----------: | :-----------: | :----------------------: | :------------: | | Declarative YAML graph | ✓ | (Python code) | (Python code) | (JS code) | — | | Schema validation of flow | ✓ | — | — | partial | — | | Persistent state across runs | ✓ | — | — | — | — | | Self-evolution (advisor) | ✓ | — | — | — | — | | Calls Claude Code / Codex / Gemini | ✓ | — | — | — | (is one) | | Callable AS MCP tool | ✓ | — | — | — | (consumes MCP) | | 6 heterogeneous node kinds | ✓ | (functions) | (agents only) | (agents only) | — | | Multiple LLM providers | ✓ (Anthropic + OpenAI + any OpenAI-compatible self-host) | ✓ | ✓ | (Anthropic) | (Anthropic) | | Parallel + 429-aware | ✓ | ✓ | partial | unknown | — | | One-keyword authoring (oe ultra / /ultraexpertise) | ✓ | — | — | ✓ (ultrawork) | — |

Full write-up: [docs/comparison.md](docs/comparison.md).

---

Where OpenExpertise fits in the ecosystem

                    ┌────────────────────────────────────────┐
                    │   OpenExpertise — workflow orchestrator │
                    │   YAML graph · SQLite · scheduler · evolve │
                    └──────────────────┬─────────────────────┘
                                       │ composes
        ┌──────────────────────────────┼──────────────────────────────┐
        ▼                              ▼                              ▼
   ┌──────────┐                  ┌──────────┐              ┌──────────────────────┐
   │   MCP    │                  │  Skills  │              │  Autonomous agents   │
   │ protocol │                  │ SKILL.md │              │  (executors)         │
   │ for tools│                  │ reusable │              │  Claude Code · Codex │
   │ + data   │                  │ LLM units│              │  · Gemini CLI        │
   │          │                  │          │              │  + OSS frameworks    │
   └──────────┘                  └──────────┘              └──────────────────────┘

        ▲                              ▲                              ▲
        └──────────────────────────────┼──────────────────────────────┘
                                       │
                  OE composes all three into one durable, replayable graph.
                  Plus it exposes ITSELF as MCP tools (`oe-mcp`) so any agent
                  can call OpenExpertise from inside its own session.

OE is not a protocol (that's MCP), not a reusable LLM unit (that's a Skill), and not an autonomous agent (that's Claude Code / Codex / Gemini / OpenHands / …). It's the workflow layer that orchestrates those pieces.

vs MCP — protocol bus, OE speaks both sides

MCP is a protocol for exposing tools, data, and prompts to LLMs. OpenExpertise rides on top:

• Consumes MCP — a dataset node with source.type: mcp-resource reads from any MCP server (declared in schema today; dispatcher wiring planned for a later 0.x).
• Exposes MCP — @openexpertise/mcp-server (binary oe-mcp) ships 8 tools (oe_run, oe_validate, oe_state, oe_inspect, oe_evolve, oe_ultra, oe_ultra_revise, oe_graph) so any MCP client — Claude Code, Codex, Gemini, or anything else — can run OpenExpertise experiences from inside its own session.

MCP is the wire format; OE is the workflow on top of the wire, AND offered ON the wire.

vs Skills (Anthropic SKILL.md packages) — units, OE composes

A Skill is a packaged LLM capability: a SKILL.md system prompt + scripts + references + assets. Reusable across sessions, across projects.

OE has a skill node kind — runs SKILL.md as a graph step. Three of the bundled examples are direct YAML translations of Anthropic skills:

| Skill | Translated to OE | What it adds | | ---------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | | systematic-debugging | [examples/systematic-debugging](examples/systematic-debugging) | Persistent hypothesis log + replay + auto-evolve the hypothesis prompt | | brainstorming | [examples/brainstorming](examples/brainstorming) | 3-angle fan-out + per-cluster critique + synthesizable picks across sessions | | experience-creator | [@openexpertise/skill-experience-creator](packages/skill-experience-creator) | Itself a Skill — teaches an LLM how to author OE flows. Used by oe ultra. |

Skills define what one LLM call does; OE arranges Skills (plus tools, agents, datasets, CLI agents) into a flow whose output is durable, replayable, and improvable.

vs Anthropic /workflows — different tradeoffs

Anthropic's /workflows (the workflow-creator preview in Claude Code) is the first-party in-CLI option for multi-step procedures. It's the lightest path if you're already inside Claude Code and want a quick procedural sketch.

OE is broader: YAML-declared (vs JS-coded), persistent SQLite state across runs (vs in-session ephemeral), multi-vendor by design (one graph can call Claude Code AND Codex AND Gemini), and self-improving (oe evolve reads the events + state diff and proposes graph upgrades as git apply-ready diffs).

Different shapes for different jobs. Use /workflows for "I want to do this once-ish in Claude Code". Use OE for "this is my team's repeatable SOP, I want it version-controlled and getting better every quarter".

vs autonomous agents — executors, OE wraps and chains them

"Autonomous agent" is a moving category: Claude Code, Codex CLI, Gemini CLI on the commercial side, plus the rapidly-growing OSS constellation — OpenHands, AutoGen, CrewAI agents, OpenClaw, Hermes Agent, OpenHuman, more launching every month.

An agent is "AI bash": improvises each run, opaque trajectory, no shared state across invocations. OpenExpertise is "AI Makefile": same DAG every run, persistent state, replayable.

OE's cli-agent node wraps any of these autonomous agents as a single graph step. Today, three providers ship: claude-code, codex, gemini. The same pattern (spawn a subprocess, capture stdout, parse JSON) is what makes the broader OSS constellation viable as future providers — adding openhands

…

Source & license

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

• Author: xingchengxu
• Source: xingchengxu/OpenExpertise
• License: MIT
• Homepage: https://xingchengxu.github.io/OpenExpertise/

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