{"id":50289562,"url":"https://github.com/xingchengxu/openexpertise","last_synced_at":"2026-06-01T09:00:40.367Z","repository":{"id":360691206,"uuid":"1249201746","full_name":"xingchengxu/OpenExpertise","owner":"xingchengxu","description":"AI-era Makefile, codify expert workflows as YAML graphs","archived":false,"fork":false,"pushed_at":"2026-05-30T05:37:26.000Z","size":1686,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-30T07:03:11.864Z","etag":null,"topics":["agentic","agents","ai-workflow","claude-code","cli","codex","dag","gemini-cli","llm","mcp","model-context-protocol","prompt-engineering","typescript","workflow-orchestration","yaml"],"latest_commit_sha":null,"homepage":"https://xingchengxu.github.io/OpenExpertise/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xingchengxu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-25T13:04:07.000Z","updated_at":"2026-05-30T05:37:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"eb8214e0-8a75-4ce9-bb7c-edcd93511d15","html_url":"https://github.com/xingchengxu/OpenExpertise","commit_stats":null,"previous_names":["xingchengxu/openexpertise"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/xingchengxu/OpenExpertise","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xingchengxu%2FOpenExpertise","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xingchengxu%2FOpenExpertise/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xingchengxu%2FOpenExpertise/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xingchengxu%2FOpenExpertise/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xingchengxu","download_url":"https://codeload.github.com/xingchengxu/OpenExpertise/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xingchengxu%2FOpenExpertise/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33723549,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic","agents","ai-workflow","claude-code","cli","codex","dag","gemini-cli","llm","mcp","model-context-protocol","prompt-engineering","typescript","workflow-orchestration","yaml"],"created_at":"2026-05-28T05:01:18.904Z","updated_at":"2026-05-31T08:00:34.883Z","avatar_url":"https://github.com/xingchengxu.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/demo.svg\" alt=\"animated demo: oe doctor → oe registry → oe init → oe run\" width=\"720\"\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n# OpenExpertise\n\n### Your team's best workflows — version-controlled, reproducible, self-improving.\n\n[![npm](https://img.shields.io/npm/v/%40openexpertise%2Fcli?label=%40openexpertise%2Fcli\u0026color=cb3837)](https://www.npmjs.com/package/@openexpertise/cli) [![CI](https://github.com/xingchengxu/OpenExpertise/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/xingchengxu/OpenExpertise/actions/workflows/ci.yml) [![docs](https://img.shields.io/badge/docs-xingchengxu.github.io%2FOpenExpertise-3b82f6)](https://xingchengxu.github.io/OpenExpertise/) [![tests](https://img.shields.io/badge/tests-292%20passing-brightgreen)](#) [![packages](https://img.shields.io/badge/packages-15-blueviolet)](#) [![license: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\n[**Install**](#install) · [**60-second demo**](#60-second-demo) · [**Why**](#why-openexpertise) · [**Examples**](#built-in-examples) · [**Compare**](#vs-the-alternatives) · [**Docs site →**](https://xingchengxu.github.io/OpenExpertise/)\n\n\u003c/div\u003e\n\n---\n\n## What it is (in one sentence)\n\n**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.**\n\n```yaml\n# examples/review-branch/experience.yaml — 10 lines, real result:\ngraph:\n  nodes:\n    - { id: bugs, kind: agent, prompt: 'Find bugs in {{diff}}', writes: [findings] }\n    - { id: security, kind: agent, prompt: 'Find injection flaws in {{diff}}', writes: [findings] }\n    - { id: score, kind: agent, reads: [findings], writes: [risk_score] }\n  edges:\n    - { from: bugs, to: score }\n    - { from: security, to: score }\n```\n\n- **Repeatable** — same DAG every run, JSONL audit log, SQLite state you can query hours later\n- **Multi-vendor** — one graph calls Claude Code, Codex, and Gemini; state flows between all three\n- **Self-improving** — `oe evolve \u003crun-id\u003e` reads what happened and proposes the next YAML patch\n\nIt'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.\n\n---\n\n## Install\n\n```bash\nnpm install -g @openexpertise/cli      # the `oe` command — Node 20+\noe doctor                              # verify env (CLI agents, API keys, write perms)\noe init my-first                       # scaffold a minimal no-LLM flow\noe init my-flow --template full-pipeline   # 4 templates: tool-only | agent | cli-agent | full-pipeline\noe registry                            # see 5 curated experiences (need API key to run)\noe demo                                # see pre-recorded runs of bundled examples (zero API key)\noe demo review-branch                  # preview the PR review flow + advisor's evolution proposal\n```\n\n\u003e **New to OpenExpertise?** Walk through the [30-minute \"Your first experience\" tutorial](https://xingchengxu.github.io/OpenExpertise/guide/first-experience) — by the end you'll have a tested, registry-submittable flow you built yourself.\n\nPull any public GitHub repo with an `experience.yaml`:\n\n```bash\noe install gh:owner/repo               # latest commit\noe install gh:owner/repo@v1.2.3        # pin to tag/SHA\noe submit --tags x,y                   # submit YOUR experience to the curated registry\n```\n\nWant yours discoverable via `oe install \u003cname\u003e`? Run `oe submit` inside your experience directory — opens a pre-filled GitHub issue with the registry entry generated for you.\n\n📖 **Full docs: https://xingchengxu.github.io/OpenExpertise/** — guide, all 12 examples, 10-recipe cookbook, API reference, comparison vs LangGraph/CrewAI/Mastra/Inngest, operations playbook.\n\n---\n\n## 60-second demo\n\n```bash\nnpm install -g @openexpertise/cli\ngit clone https://github.com/xingchengxu/OpenExpertise \u0026\u0026 cd OpenExpertise\n\nexport ANTHROPIC_API_KEY=sk-...        # or OPENAI_API_KEY=...\noe run examples/review-branch --tui\n```\n\nYou'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**.\n\n```\nⓘ run-2026-05-26-a1b2c3 finished\n  findings: 3 issues\n  risk_score: 0.30\n```\n\nNow ask the evolution advisor what's missing:\n\n```bash\noe evolve run-2026-05-26-a1b2c3\n# → wrote .openexpertise/evolution/run-2026-05-26-a1b2c3.md\n#   proposal: \"Add `security` dimension — default reviewers focus on\n#              logic/tests; injection bugs need a dedicated reviewer.\"\n```\n\nApply the one-line YAML patch from the proposal and re-run:\n\n```\nⓘ run-2026-05-26-d4e5f6 finished\n  findings: 4 issues (+ SQL injection in /users/\u003cid\u003e)\n  risk_score: 0.85\n```\n\n**The experience improved itself.** Author → run → evolve, all driven by the same LLM. That's the whole story.\n\n---\n\n## Why OpenExpertise\n\n\u003e **Five reasons it's different from every other AI workflow tool.**\n\n|                                     | What it gets you                                                                                                                                                                                                  |\n| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **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.                                                                          |\n| **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) |\n| **Persistent SQLite state**         | Every node's writes land in a typed blackboard. `oe state findings` works hours later. Resume with `oe resume \u003crun-id\u003e` and replay cached steps.                                                                  |\n| **Self-improving**                  | `oe evolve \u003crun-id\u003e` reads the events + state diff and proposes graph upgrades as `git apply`-ready diffs. The author → run → evolve loop closes.                                                                 |\n| **Two-way agentic-CLI integration** | **Outbound:** delegate a node to Claude Code / Codex / Gemini. **Inbound:** `oe-mcp` exposes 6 OE tools so the same CLIs can run experiences from inside their own sessions.                                      |\n\n---\n\n## vs the alternatives\n\n|                                                        |                      OpenExpertise                       |   LangGraph   |    CrewAI     | `/workflows` (Anthropic) |  Claude Code   |\n| ------------------------------------------------------ | :------------------------------------------------------: | :-----------: | :-----------: | :----------------------: | :------------: |\n| Declarative YAML graph                                 |                            ✓                             | (Python code) | (Python code) |        (JS code)         |       —        |\n| Schema validation of flow                              |                            ✓                             |       —       |       —       |         partial          |       —        |\n| Persistent state across runs                           |                            ✓                             |       —       |       —       |            —             |       —        |\n| Self-evolution (advisor)                               |                            ✓                             |       —       |       —       |            —             |       —        |\n| Calls Claude Code / Codex / Gemini                     |                            ✓                             |       —       |       —       |            —             |    (is one)    |\n| Callable AS MCP tool                                   |                            ✓                             |       —       |       —       |            —             | (consumes MCP) |\n| 6 heterogeneous node kinds                             |                            ✓                             |  (functions)  | (agents only) |      (agents only)       |       —        |\n| Multiple LLM providers                                 | ✓ (Anthropic + OpenAI + any OpenAI-compatible self-host) |       ✓       |       ✓       |       (Anthropic)        |  (Anthropic)   |\n| Parallel + 429-aware                                   |                            ✓                             |       ✓       |    partial    |         unknown          |       —        |\n| One-keyword authoring (`oe ultra` / `/ultraexpertise`) |                            ✓                             |       —       |       —       |     ✓ (`ultrawork`)      |       —        |\n\nFull write-up: [`docs/comparison.md`](docs/comparison.md).\n\n---\n\n## Where OpenExpertise fits in the ecosystem\n\n```\n                    ┌────────────────────────────────────────┐\n                    │   OpenExpertise — workflow orchestrator │\n                    │   YAML graph · SQLite · scheduler · evolve │\n                    └──────────────────┬─────────────────────┘\n                                       │ composes\n        ┌──────────────────────────────┼──────────────────────────────┐\n        ▼                              ▼                              ▼\n   ┌──────────┐                  ┌──────────┐              ┌──────────────────────┐\n   │   MCP    │                  │  Skills  │              │  Autonomous agents   │\n   │ protocol │                  │ SKILL.md │              │  (executors)         │\n   │ for tools│                  │ reusable │              │  Claude Code · Codex │\n   │ + data   │                  │ LLM units│              │  · Gemini CLI        │\n   │          │                  │          │              │  + OSS frameworks    │\n   └──────────┘                  └──────────┘              └──────────────────────┘\n\n        ▲                              ▲                              ▲\n        └──────────────────────────────┼──────────────────────────────┘\n                                       │\n                  OE composes all three into one durable, replayable graph.\n                  Plus it exposes ITSELF as MCP tools (`oe-mcp`) so any agent\n                  can call OpenExpertise from inside its own session.\n```\n\nOE 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.\n\n### vs MCP — protocol bus, OE speaks both sides\n\nMCP is a protocol for exposing tools, data, and prompts to LLMs. OpenExpertise rides on top:\n\n- **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).\n- **Exposes MCP** — [`@openexpertise/mcp-server`](https://www.npmjs.com/package/@openexpertise/mcp-server) (binary `oe-mcp`) ships 6 tools (`oe_run`, `oe_validate`, `oe_state`, `oe_inspect`, `oe_evolve`, `oe_ultra`) so any MCP client — Claude Code, Codex, Gemini, or anything else — can run OpenExpertise experiences from inside its own session.\n\nMCP is the wire format; OE is the workflow on top of the wire, AND offered ON the wire.\n\n### vs Skills (Anthropic SKILL.md packages) — units, OE composes\n\nA Skill is a packaged LLM capability: a `SKILL.md` system prompt + scripts + references + assets. Reusable across sessions, across projects.\n\nOE has a `skill` node kind — runs SKILL.md as a graph step. Three of the bundled examples are direct YAML translations of Anthropic skills:\n\n| Skill                  | Translated to OE                                                               | What it adds                                                                 |\n| ---------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |\n| `systematic-debugging` | [`examples/systematic-debugging`](examples/systematic-debugging)               | Persistent hypothesis log + replay + auto-evolve the hypothesis prompt       |\n| `brainstorming`        | [`examples/brainstorming`](examples/brainstorming)                             | 3-angle fan-out + per-cluster critique + synthesizable picks across sessions |\n| `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`.  |\n\nSkills 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.\n\n### vs Anthropic /workflows — different tradeoffs\n\nAnthropic'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.\n\nOE 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).\n\nDifferent 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\".\n\n### vs autonomous agents — executors, OE wraps and chains them\n\n\"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.\n\nAn 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.\n\nOE'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`, `autogen`, `crewai`, `openclaw`, `hermes`, `openhuman` providers is roadmap work, not a re-architecture.\n\n**Bidirectional integration is the point.** Any agent can call OE back via `oe-mcp` (or just `oe run` in their shell). So you can run a Claude Code session that, when it hits \"I need the team's SOP for incident triage\", calls `oe_run` on `examples/oncall-runbook` — and the result of THAT graph (which itself called Gemini and Codex along the way) flows back into the Claude Code conversation. Each layer remembers, each layer is replayable, and the same graph improves itself over time.\n\nThe two categories don't compete. Agents execute. OpenExpertise orchestrates, persists, and evolves.\n\n---\n\n## Verified end-to-end (not just unit-tested)\n\nEvery built-in example has been smoke-run against **real APIs** — not just mocks. Three real framework bugs surfaced by the live runs and all three were fixed + regression-tested before this README was written.\n\n| Provider                                                       | Status | Verified path                                                                                                                                                      |\n| -------------------------------------------------------------- | :----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| **Anthropic** (`claude-sonnet-4-6`, `claude-opus-4-7`)         |   ✓    | Default `agent` kind. 429-aware exponential retry.                                                                                                                 |\n| **OpenAI** (`gpt-4o-2024-11-20`)                               |   ✓    | `--llm openai`. Same `llm-factory`, same lazy proxy.                                                                                                               |\n| **Any OpenAI-compatible endpoint** (vLLM / Ollama / LM Studio) |   ✓    | Smoke-tested live against vLLM-served reasoning model. Set `OPENAI_BASE_URL=...` and go.                                                                           |\n| **Claude Code CLI** (`claude -p`)                              |   ✓    | `cli-agent` provider. Lets the graph delegate a step to a Claude Code subprocess.                                                                                  |\n| **OpenAI Codex CLI** (`codex exec`)                            |   ✓    | `cli-agent` provider. Same.                                                                                                                                        |\n| **Gemini CLI** (`gemini --prompt`)                             |   ✓    | `cli-agent` provider. Live-tested in a 3-CLI chain: Claude summarized → Codex critiqued → **Gemini delivered the final verdict**, state flowing between all three. |\n\n**Smoke-test coverage:** all **9 example experiences** (`hello-tool`, `dataset-aggregate`, `agent-echo`, `oncall-runbook`, `issue-triage`, `review-branch`, `cli-orchestration`, `release-gates`, **`tri-cli-orchestration`**) pass end-to-end with real APIs and real CLIs. The mocked e2e suites are the safety net; the live smokes are the proof.\n\n### One graph, three rival AI coding CLIs talking to each other\n\nNo other workflow framework does this today. The hero `cli-agent` demo:\n\n```yaml\n# examples/tri-cli-orchestration/experience.yaml (excerpt)\ngraph:\n  nodes:\n    - {\n        id: summarize,\n        kind: cli-agent,\n        provider: claude-code,\n        prompt: 'Summarize this topic in one sentence: {{topic}}',\n        args: { topic: 'In-memory caching for HTTP APIs' },\n        writes: [summary],\n      }\n    - {\n        id: critique,\n        kind: cli-agent,\n        provider: codex,\n        prompt: 'What does this summary miss? {{summary}}',\n        reads: [summary],\n        writes: [critique],\n      }\n    - {\n        id: verdict,\n        kind: cli-agent,\n        provider: gemini,\n        prompt: 'Verdict on production-readiness given: {{summary}} + {{critique}}',\n        reads: [summary, critique],\n        writes: [verdict],\n      }\n  edges:\n    - { from: summarize, to: critique }\n    - { from: critique, to: verdict }\n```\n\nReal run (state captured live, 37s wall time):\n\n\u003e **Claude Code →** _\"In-memory caching strategies for HTTP APIs store frequently requested response data directly in application memory to reduce latency, lower backend load, and improve throughput, using techniques like time-based expiration, LRU eviction, and cache invalidation on writes.\"_\n\u003e\n\u003e **Codex →** _\"It misses that in-memory caches are per-process, so horizontally scaled APIs can serve inconsistent or stale data across instances unless you add coordination or use a distributed cache.\"_\n\u003e\n\u003e **Gemini →** _\"**No**; specify that in-memory caches are per-process, which can lead to data inconsistency across horizontally scaled API instances.\"_\n\nOne DAG, three vendors, shared SQLite state, replayable event log. Run it yourself: [`examples/tri-cli-orchestration/`](examples/tri-cli-orchestration/).\n\n### Self-host your LLM\n\nBecause `--llm openai` honors `OPENAI_BASE_URL`, anything that speaks the OpenAI chat-completions API works as a drop-in — vLLM, Ollama, LM Studio, llama.cpp's server, your own internal endpoint. No code change needed in OpenExpertise.\n\n```bash\nexport OPENAI_API_KEY=anything-the-server-accepts\nexport OPENAI_BASE_URL=http://your-vllm-host:8000/v1\noe run examples/oncall-runbook --llm openai\n```\n\nThat same flow handles reasoning-style models that prefix tool-call arguments with `\u003cthink\u003e...\u003c/think\u003e` blocks (auto-stripped by the client) and Claude Code's JSON envelopes (auto-unwrapped by the cli-agent parser).\n\n---\n\n## Install \u0026 first run (under 60 seconds)\n\n```bash\nnpm install -g @openexpertise/cli\noe doctor                              # verify env\noe init my-first-experience            # scaffold a minimal flow (no API key needed)\ncd my-first-experience \u0026\u0026 oe run .\n# → finalState: { greeting: \"Hello, OpenExpertise!\" }\n```\n\nWant one of the bundled flagship flows? `oe registry` lists 5 curated experiences (`oe install deep-research`, `review-branch`, etc.) — those need an API key. Or pull any GitHub repo: `oe install gh:owner/repo`.\n\nPrefer source? Clone + build for hacking on the runtime:\n\n```bash\ngit clone https://github.com/xingchengxu/OpenExpertise \u0026\u0026 cd OpenExpertise\npnpm install \u0026\u0026 pnpm -r build\nnode packages/cli/dist/bin.js run examples/hello-tool\n```\n\n---\n\n## Built-in examples\n\n\u003e Pick the one closest to your use case. Each ships with fixtures and a mocked-LLM e2e test in `e2e/` — no real API key required to validate the structure.\n\n| Example                                                      | What it shows                                                                                                      | Nodes                             |\n| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | --------------------------------- |\n| [`hello-tool`](examples/hello-tool/)                         | Smallest possible flow. No LLM.                                                                                    | `tool`                            |\n| [`dataset-aggregate`](examples/dataset-aggregate/)           | Load CSV → aggregate.                                                                                              | `dataset` + `tool`                |\n| [`agent-echo`](examples/agent-echo/)                         | Single agent with structured output.                                                                               | `agent`                           |\n| [`review-branch`](examples/review-branch/) ★                 | The hero demo. Multi-dim review + verifier + score + evolution.                                                    | `tool` + `agent` ×3               |\n| [`oncall-runbook`](examples/oncall-runbook/)                 | Investigate an incident across 3 dimensions via `for_each` fan-out.                                                | `tool` + `agent`                  |\n| [`issue-triage`](examples/issue-triage/)                     | Classify → search dupes → conditional dedup → route. Shows `when:` edges.                                          | `tool` + `agent`                  |\n| [`release-gates`](examples/release-gates/)                   | License + changelog + coverage + Claude-Code security scan → release gate.                                         | `tool` + `cli-agent` + `agent`    |\n| [`cli-orchestration`](examples/cli-orchestration/)           | Claude Code summarizes; Codex critiques. Two providers in one flow.                                                | `cli-agent` ×2                    |\n| [`tri-cli-orchestration`](examples/tri-cli-orchestration/) ★ | Claude → Codex → Gemini in one DAG. The headline cross-vendor demo.                                                | `cli-agent` ×3                    |\n| [`deep-research`](examples/deep-research/)                   | Multi-vendor research: Claude Code WebSearch + Gemini Google Search → cited synthesis.                             | `tool` + `agent` + `cli-agent` ×2 |\n| [`systematic-debugging`](examples/systematic-debugging/)     | The superpowers `systematic-debugging` skill as a YAML flow. Hypothesize → verify → fix via Claude Code → re-test. | `tool` ×2 + `agent` + `cli-agent` |\n| [`brainstorming`](examples/brainstorming/)                   | The superpowers `brainstorming` skill as a YAML flow. Diverge → cluster → critique → synthesize top 3.             | `tool` + `cli-agent` ×2 + `agent` |\n\n---\n\n## Architecture at a glance\n\n```\n                  experience.yaml                 .openexpertise/\n                                                  ├─ state.sqlite   (typed blackboard, persistent)\n                                                  ├─ runs/\u003cid\u003e.jsonl (event log, replayable)\n                                                  ├─ cache/         (per-node memo, resume-able)\n                                                  └─ evolution/     (advisor proposals)\n                            │\n                            ▼\n            ┌─────────────────────────────────────┐\n            │  Sequential or Parallel Scheduler   │ ◀── --concurrency N\n            │  (topological waves, bounded)        │      runtime.concurrency in YAML\n            └─────────────────────────────────────┘\n                            │\n        ┌───────────┬───────┼────────┬───────────────┐\n        ▼           ▼       ▼        ▼               ▼\n   ┌────────┐ ┌────────┐ ┌─────┐ ┌────────┐  ┌──────────────┐\n   │ tool   │ │ agent  │ │skill│ │dataset │  │  cli-agent   │\n   │        │ │ (LLM)  │ │     │ │(file/  │  │ (claude-code │\n   │        │ │        │ │     │ │sqlite/ │  │  / codex /   │\n   │        │ │        │ │     │ │ http)  │  │  gemini)     │\n   └────────┘ └────────┘ └─────┘ └────────┘  └──────────────┘\n        │           │      │        │               │\n        └───────────┴──────┼────────┴───────────────┘\n                            ▼\n                   state writes + events\n                   (merge: array_append | set_once | last_wins)\n```\n\nLLM clients (`@openexpertise/node-kinds-agent`, `@openexpertise/llm-openai`) retry on HTTP 429 with exponential backoff. Both wire through the same `llm-factory` used by `oe run`, `oe evolve`, AND `oe ultra` (authoring) — author/run/evolve is one closed loop.\n\n---\n\n## Two ways to author\n\n### 1. Hand-write the YAML (full control)\n\n```yaml\nname: my-sop\nversion: 0.1.0\nstate:\n  schema:\n    input: { type: string }\n    output: { type: string }\ngraph:\n  nodes:\n    - id: do_thing\n      kind: tool\n      impl: ./tools/do_thing.mjs\n      writes: [output]\n  edges: []\n```\n\n`oe validate` checks it; `oe run` executes it.\n\n### 2. One-keyword authoring (LLM writes the YAML)\n\n```bash\noe ultra \"Review pull requests for SOC2 compliance and produce a risk score\"\n```\n\nBehind the scenes, two LLM passes — **analyze** (decompose into phases + nodes + state schema) then **synthesize** (emit experience.yaml + tool stubs + prompts) — land a validated draft in `.openexpertise/drafts/\u003cslug\u003e/`. Inspect, run, promote with `mv`.\n\nFrom Claude Code:\n\n```\n/ultraexpertise Review pull requests for SOC2 compliance\n```\n\nReference: [`docs/ultraexpertise.md`](docs/ultraexpertise.md).\n\n---\n\n## Use OpenExpertise FROM Claude Code (and Codex, Gemini)\n\nRegister the MCP server once:\n\n```bash\nclaude mcp add openexpertise -- node $PWD/packages/mcp-server/dist/bin.js\n```\n\nThen inside any Claude Code session:\n\n\u003e _\"Use oe_run on examples/review-branch\"_\n\u003e _\"Use oe_evolve on the last run id\"_\n\nSix MCP tools are exposed: `oe_validate`, `oe_state`, `oe_inspect`, `oe_run`, `oe_evolve`, `oe_ultra`. Reference: [`docs/mcp-server.md`](docs/mcp-server.md).\n\n---\n\n## CLI reference\n\n\u003e First time? Run `oe doctor` to verify your environment.\n\n| Command                | Purpose                                                                                   |\n| ---------------------- | ----------------------------------------------------------------------------------------- |\n| `oe doctor`            | Check environment readiness (Node, pnpm, CLIs, API keys, writable dirs)                   |\n| `oe init \u003cname\u003e`       | Scaffold a new experience directory                                                       |\n| `oe validate [path]`   | Validate `experience.yaml`                                                                |\n| `oe run [path]`        | Execute an experience (`--tui`, `--evolve`, `--concurrency N`, `--llm anthropic\\|openai`) |\n| `oe resume \u003crun-id\u003e`   | Re-run with cache replay                                                                  |\n| `oe inspect \u003crun-id\u003e`  | Replay a run's event log (sorted by ts)                                                   |\n| `oe state [field]`     | Inspect blackboard                                                                        |\n| `oe reset-state --yes` | Wipe blackboard                                                                           |\n| `oe evolve \u003crun-id\u003e`   | Generate evolution proposals                                                              |\n| `oe diff`              | List pending evolution proposals                                                          |\n| `oe ultra \"\u003ctask\u003e\"`    | LLM authors a new experience from natural language                                        |\n\n### `--tui` dashboard\n\nA live ink-based dashboard showing each node's status, current activity (`calling claude-sonnet-4-6`, `spawning codex`, `parsing JSON output`), accumulated per-node tokens, and a header line with the run total. htop-grade observability for graph runs.\n\n### `--concurrency N`\n\nIndependent DAG nodes (and `for_each` iterations whose `concurrency: N` is set) run in parallel up to the ceiling. Defaults to 1. Combine with `runtime.concurrency: N` in YAML to make a flow parallel-by-default.\n\n---\n\n## Docs\n\n**📖 Full docs site: https://xingchengxu.github.io/OpenExpertise/** — 90 pages across 11 sections (guide, concepts, examples, cookbook, reference, comparisons, operations, FAQ, glossary, roadmap).\n\nIn-repo quick references:\n\n| Doc                                                                              | What's inside                                                              |\n| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |\n| [Docs site `/guide`](https://xingchengxu.github.io/OpenExpertise/guide/)         | Hands-on path: install → first experience → authoring → running → evolving |\n| [Docs site `/examples`](https://xingchengxu.github.io/OpenExpertise/examples/)   | Walkthroughs for all 12 shipped examples + gallery                         |\n| [Docs site `/cookbook`](https://xingchengxu.github.io/OpenExpertise/cookbook/)   | 10 self-contained recipes — copy/paste YAML for common patterns            |\n| [Docs site `/compare`](https://xingchengxu.github.io/OpenExpertise/compare/)     | vs LangGraph / CrewAI / Mastra / Inngest / Workflows / Claude Code         |\n| [`docs/cli-agent.md`](docs/cli-agent.md)                                         | `cli-agent` node kind: providers, command shapes, JSON-mode caveats        |\n| [`docs/mcp-server.md`](docs/mcp-server.md)                                       | MCP server tools + per-CLI registration                                    |\n| [`docs/ultraexpertise.md`](docs/ultraexpertise.md)                               | Auto-SOP authoring — `oe ultra`, slash command, MCP `oe_ultra`             |\n| [`docs/registry.md`](docs/registry.md)                                           | `oe install` / `oe registry` and how to submit your experience             |\n| [Docs site `/concepts`](https://xingchengxu.github.io/OpenExpertise/concepts/)   | Mental model: code-as-law, state, dispatchers, control flow, 6 node kinds  |\n| [Docs site `/reference`](https://xingchengxu.github.io/OpenExpertise/reference/) | CLI command pages + API surface + full YAML schema                         |\n\n---\n\n## Should I use OpenExpertise?\n\n```\nAre you trying to ...\n\n   automate a recurring, multi-step process\n   that mixes deterministic logic + LLM judgment?\n                          │\n                  ┌───────┴────────┐\n                 YES               NO\n                  │                 │\n           ┌──────┴──────┐    Use Claude Code\n           │             │    or Codex directly.\n   Need it durable,     One-shot\n   reproducible,        exploration?\n   evolvable?           │\n   │                    └─ Use Claude Code.\n   └─ ▶ Use OpenExpertise.\n```\n\nIf your team has a SOP that someone has to follow every Monday morning — code review, incident triage, release gates, compliance check, customer onboarding — and you want it to **run the same way every time, leave a trail, and get better at it** — OpenExpertise is for you.\n\nIf you want a chat-based assistant or one-off task automation, use the underlying CLI directly (Claude Code, Codex, Gemini). OpenExpertise sits **above** those tools, not next to them.\n\n---\n\n## Development\n\n```bash\npnpm test            # 265 unit + e2e tests\npnpm typecheck       # strict TS across all packages\npnpm lint            # eslint (0 errors)\npnpm format:check    # prettier\npnpm format          # prettier --write\npnpm -r build        # tsc -b across the monorepo\n```\n\nThe repo is a pnpm workspace with 15 publishable packages. New features land via spec → plan → subagent-driven execution (see [`CONTRIBUTING.md`](CONTRIBUTING.md)).\n\n---\n\n## Contributing\n\nPRs welcome. The path of least friction:\n\n1. Open an issue describing the use case or bug.\n2. For features, expect to brainstorm a spec before implementation.\n3. For bug fixes, a failing test + minimal patch.\n\nThis project is built largely via [Claude Code](https://claude.com/claude-code)-driven [superpowers](https://github.com/anthropics/claude-superpowers) workflows; subagent dispatch + two-stage review per task. The same discipline applies to community contributions.\n\n---\n\n## Community\n\n- [Contributing guide](CONTRIBUTING.md) — setup, conventions, the spec → plan → execute rhythm.\n- [Code of Conduct](CODE_OF_CONDUCT.md) — we follow Contributor Covenant 2.1.\n- [Security policy](SECURITY.md) — how to report vulnerabilities.\n- [Changelog](CHANGELOG.md) — what's in each release.\n\n---\n\n## License\n\n[MIT](LICENSE) © 2026 OpenExpertise.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\nIf OpenExpertise saved you from writing the same workflow twice — **★ the repo**.\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxingchengxu%2Fopenexpertise","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxingchengxu%2Fopenexpertise","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxingchengxu%2Fopenexpertise/lists"}