# OpenExpertise > AI-era Makefile, codify expert workflows as YAML graphs - **Type:** MCP server - **Install:** `agentstack add mcp-xingchengxu-openexpertise` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [xingchengxu](https://agentstack.voostack.com/s/xingchengxu) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [xingchengxu](https://github.com/xingchengxu) - **Source:** https://github.com/xingchengxu/OpenExpertise - **Website:** https://xingchengxu.github.io/OpenExpertise/ ## Install ```sh agentstack add mcp-xingchengxu-openexpertise ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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 →**](https://xingchengxu.github.io/OpenExpertise/) --- ## 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.** ```yaml # 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 ```bash 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](https://xingchengxu.github.io/OpenExpertise/guide/authoring-ultra). > **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. ### 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). ```bash oe graph examples/review-branch ``` ```mermaid 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`: ```bash 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 ```bash 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: ```bash 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`](https://www.npmjs.com/package/@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](https://github.com/xingchengxu) - **Source:** [xingchengxu/OpenExpertise](https://github.com/xingchengxu/OpenExpertise) - **License:** MIT - **Homepage:** https://xingchengxu.github.io/OpenExpertise/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** yes - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-xingchengxu-openexpertise - Seller: https://agentstack.voostack.com/s/xingchengxu - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.