Converge runs autonomous agents through adaptive, multi-step playbooks.
Quick Start · Examples · Docs · Translations · Contributing
Converge runs AI coding agents (Claude, Codex, …) through a chain of tasks defined as a reusable, shareable playbook. Each task declares its outputs and shell-check exit criteria; the adaptive execution loop retries failures and can spawn follow-up tasks that match the shape of the project at runtime; a persistent run journal lets a killed run resume instead of starting over.
Most "agent skills" today are prompts: instructions written down once, with the hope the agent follows them next time. That works for a single step and falls apart across many, because nothing enforces that each step's output is real before the next one consumes it.
Repos like gstack, superpowers, agent-skills, and claude-seo do make it work, by chaining tasks and threading context between them by hand. The chain is doing the heavy lifting, not the prompt.
Converge makes that chain a first-class artifact: each task declares what it produces and the shell checks that prove it, and the engine resets the context window at every task boundary, so long-running work stays affordable instead of compounding.
⚠️ Token consumption warning: Converge dispatches AI agents that call LLM APIs. A playbook can consume tens of millions of tokens. Use a cheap model; see Provider Setup below.
npm install -g @openplaybooks/convergePrefer to have your coding agent do it? See Pro tips → Let your coding agent install Converge.
mkdir my-project && cd my-project # or just cd into an existing project root
converge init --skillsThe project name is taken from the current directory (my-project here), so
converge init writes .converge/ into whatever you cd into. Run it from
an existing project root to add Converge to an existing repo instead.
# Start from a built-in example (no AI needed)
converge add --from-example hello-worldconverge runThat's it. The five-minute walkthrough: Your first playbook.
Babysit with Claude — two prompts, hours of unattended work
Converge runs best when an instance of Claude Code is watching it, not fire-and-forget. The intended happy path is end-to-end inside Claude.
Step A — launch Claude and plan the playbook. Open Claude Code in your project directory, then type:
/converge-planning
Plan a playbook that scrapes the top 20 HN posts every hour,
summarises each thread with comments, and writes a daily digest
to ./digests/YYYY-MM-DD.md.
The /converge-planning skill takes over: decomposes the goal, writes TASK.md files, declares dependencies, and wires shell-level checks. You end with a runnable playbook on disk under .converge/playbooks/<name>/.
Step B — hand the run to Claude to babysit. Once the playbook exists, ask Claude to drive it. Give it the playbook path so /converge-control knows exactly what to watch:
/converge-control
Babysit the playbook at .converge/playbooks/hn-digest/.
Run it, monitor the event stream, and fix any task that fails
— diagnose, patch, and re-run until every node passes.
Under /converge-control, every level of the playbook auto-resolves: DAG nodes, dynamically spawned children, retries, repairs. Failures are classified and replayed without manual graph surgery, so a babysat run can chug along for hours straight without a human in the loop. You walk back to your laptop and the playbook is either done or sitting on a real failure worth looking at.
Let your coding agent install Converge — copy-paste prompt
Paste the prompt below into Claude Code, Codex, or any other coding agent in the directory where you want the project to live. The agent will install Converge, scaffold the project, pick a provider that matches the API keys you already have, ask you for a one-line goal, generate the first playbook, and dry-run it for you.
You are setting up Converge — an autonomous-agent playbook runner — in the current directory. Work in 4 phases. Ask me only when a phase requires a decision.
1. **Analyze the project.** Look at the current directory and report what's here in one short paragraph. Cover: is this a git repo (and on what branch)? what languages/frameworks does the file tree suggest? is there an existing `.converge/` directory? anything I should be careful about (heavy `node_modules`, committed secrets, etc.)? If the directory looks like the wrong place to drop a Converge project, stop and ask me.
Also confirm `converge --version` works. If it doesn't, run `npm install -g @openplaybooks/converge` and print the installed version.
2. **Ask which auth path I want.** Don't guess from environment variables — present these options verbatim and wait for me to pick. Each maps to a `--backend` (the agent CLI) + `--provider` (the LLM endpoint) combo for `converge init`. Tell me the exact `export` for the API-key env var I need, if any, and wait for confirmation before moving on.
**A. Claude via OAuth (recommended).** `--backend=claude --provider=anthropic-oauth`. Run `claude login` once if I haven't. No env vars to set.
**B. Claude via Anthropic API key.** `--backend=claude --provider=anthropic`. Tell me to `export ANTHROPIC_API_KEY=sk-ant-…`.
**C. Claude via cheap Anthropic-compatible proxy.** Ask which:
- **MiniMax** → `--backend=claude --provider=minimax`. Tell me to `export MINIMAX_API_KEY=…`.
- **DeepSeek** → `--backend=claude --provider=deepseek`. Tell me to `export DEEPSEEK_API_KEY=…`.
**D. Codex CLI.** `--backend=codex --provider=openai`. Tell me to `export CODEX_API_KEY=…` (or `OPENAI_API_KEY`).
**E. Other backend (Gemini / Kimi / Qwen / ACP / DeepCode).** Use `--backend=<name>`; the matching `--provider=<name>` is the default. Tell me which vendor API-key env var to set.
3. **Scaffold the project.** Confirm the current working directory is the intended project root (the one you analyzed in step 1). If a fresh folder is wanted, ask before `mkdir <name> && cd <name>`. If cwd already has a `.converge/` directory, ask before passing `--force`. Then run:
converge init --skills --backend=<chosen> --provider=<chosen>
non-interactively. The project name is taken from cwd. `--skills` installs the bundled `/converge-planning` and `/converge-control` skills under `.claude/skills/` (and `.codex/skills/`). Proxy providers (`minimax`, `deepseek`) bake the full routing into `.converge/project.yaml` — no per-shell `ANTHROPIC_*` exports needed.
4. **Offer playbook creation.** Ask me one question: *"Want to design your first playbook now?"*
- If yes — **hand off to the `/converge-planning` skill**. That skill knows the full authoring workflow (decompose the goal, write TASK.md files, declare dependencies and checks); don't try to replicate it. Just invoke `/converge-planning` and let it take over.
- If no — tell me to start later by invoking `/converge-planning` inside Claude Code, or by copying a built-in template with `converge add --from-example hello-world`.
Rules:
- Never invent API keys or commit secrets.
- If a step fails, stop and show me the raw error. In particular: if `converge run` ever returns `Invalid API key` / HTTP 401, the cause is almost always conflicting `ANTHROPIC_*` env vars from a previous setup — go back to step 2 with me, don't retry blindly.
- Do not delete `.converge/`, `node_modules/`, or anything in cwd without explicit confirmation.Each task is a markdown file that declares its outputs and the shell checks that prove them. Converge resolves dependencies into a DAG, runs tasks in parallel where it can, retries failures with structured context, spawns work it didn't know it needed, and swaps providers without changing the playbook. That's the loop that adapts when reality breaks the plan.
graph LR
A["one big<br/>problem"] --> D["diverge<br/>break into pieces"]
D --> T1["piece 1"]
D --> T2["piece 2"]
D --> T3["piece N"]
T1 --> C["converge<br/>assemble the whole"]
T2 --> C
T3 --> C
C --> R["one complete<br/>solution"]
style A fill:#E8A838,color:#222
style R fill:#5DA05D,color:#fff
style D fill:#4A90D9,color:#fff
style C fill:#4A90D9,color:#fff
The mental model: diverge → converge. Break the problem into independent pieces, run them in parallel, assemble the result. Recursive: any piece can itself diverge.
A playbook is authored once as a small set of top-level phases, with reusable templates for the work that fans out at runtime. Each TASK.md declares what it produces and the shell commands that check whether it's done, so the same playbook can be re-run, forked, or adapted to a new domain without rewriting the graph.
.converge/playbooks/{name}/
├── playbook.yml
├── tasks/
│ ├── 01-requirements/TASK.md
│ ├── 02-design/TASK.md
│ ├── 03-scaffold/TASK.md # mode: spawner parent
│ └── 04-integrate/TASK.md
├── templates/
│ ├── page/TASK.md # reusable page blueprint
│ ├── api/TASK.md # reusable endpoint blueprint
│ ├── db-model/TASK.md # reusable schema/model blueprint
│ └── component/TASK.md # reusable shared UI blueprint
└── scripts/ # optional: programmatic helpers
├── build-manifest.ts # called from TASK.md to compute spawn.plan.jsonl rows
└── verify-bundle.sh # called from checks: to assert outputs
Authored playbooks stay compact; the DAG fans out at runtime when mode: spawner tasks write a spawn.plan.jsonl manifest and the framework runs converge apply. Drop reusable shell or TS helpers in scripts/ and invoke them from a task's body or checks: when shell one-liners get unwieldy.
Every run is journalled to .converge/journal/. Each task's declared outputs and shell-check results land on disk as the run progresses, so a killed or interrupted run can be resumed instead of restarted, and converge inspect can replay what happened without a separate telemetry stack.
Richer memory primitives (frontier checkpoints, typed lessons, cross-machine portable resume) are designed in docs/rfcs/ but not all shipped yet.
Every example below marked available is a real, runnable playbook in examples/. Examples marked coming soon are designed but not yet shipped.
Each demo links to its own repository, which contains the playbook, the run journal, and the code Converge produced. Some are not yet published.
 baby-app
Long-running playbook that builds a pregnancy companion app |
 app-builder
Generate full-stack SaaS apps from a spec |
cinematic-video-production
End-to-end shot list → render pipeline |
autonomous-pentest
Recon → exploit → report, one playbook |
financial-deep-research
Research agent for equity and market analysis |
game-ai-pk
Agent-vs-agent gameplay arena |
| Example | Domain | Description |
|---|---|---|
hello-world |
Starter | Simplest possible playbook — one task, two checks |
data-pipeline |
Starter | Sequential pipeline: fetch → transform → validate |
fullstack-app |
Software | Spawner-driven dynamic backend + frontend generation |
flutter-app |
Software | Autonomous mobile app generation in Flutter / Dart |
deep-research |
Research agent | Layered iterative-deepening with quality-gated progression |
scientific-research |
Research agent | Bayesian reasoning, GRADE evidence, meta-analysis, paper generation — 8-phase epoch loop |
frontier-research |
Research agent | Beam-search frontier exploration with parallel beams and convergence tracking |
social-sim |
Simulation | Loop-based persona-driven social simulation with spawned child tasks per tick |
evolutionary-optimization |
Optimization | Fitness-landscape search for prompt tuning, hyperparameter sweeps, training recipes |
acp-demo |
Provider integration | Claude Agent SDK (acp) provider — programmatic agent invocation |
Coming soon: game-assets-video. Designed but not yet shipped — watch examples/ for updates.
converge init writes .converge/project.yaml for you. Pick a backend (the agent CLI — claude, codex, gemini, kimi, qwen, acp, deepcode) and a provider (the LLM endpoint — Anthropic, MiniMax, DeepSeek, OpenAI, …), and Converge wires up the rest.
Use a cheap model for development. A playbook can burn tens of millions of tokens; the price gap matters:
| Model | Input / 1M | Output / 1M | Best for |
|---|---|---|---|
deepseek-v4-flash |
$0.27 | $1.10 | Sub-agents, checks |
MiniMax-M2.7 |
$0.50 | $1.50 | Balanced price/perf |
deepseek-v4-pro[1m] |
$0.55 | $2.19 | Primary reasoning |
| Claude Opus 4.5 | $15.00 | $75.00 | Highest quality |
Bundled examples default to MiniMax. Every example in
examples/routes Claude throughhttps://api.minimax.io/anthropicusingMiniMax-M2.7. SetMINIMAX_API_KEYand they run end-to-end.
- Initial setup — every backend × provider combo with the exact
project.yamleachconverge initwrites: Provider setup. - Per-task overrides — mixing cheap and premium models inside one playbook: Switch providers.
Converge integrates at two layers:
- Coding agents for authoring and operating playbooks from your workspace
- Runtime providers for executing tasks inside the playbook itself
Converge ships with two bundled skills so you can design and run playbooks without leaving your coding agent:
| Skill | What it does |
|---|---|
converge-planning |
Design a new playbook from a prompt — generates PLAN.md, TASK.md files, dependency graph, and shell-level checks |
converge-control |
Run and monitor a playbook — classifies DAG events, diagnoses failures, re-runs incrementally |
converge init --skills installs the bundled skills to .claude/skills/ and .codex/skills/.
The playbook runtime is the portable layer. You can switch providers in .converge/project.yaml without rewriting the playbook.
Claude
- First-class backend via
provider: claude - Runs through the
claudeCLI - Supports Anthropic-compatible routing like DeepSeek or MiniMax through
ANTHROPIC_BASE_URL
Codex
- First-class backend via
provider: codex - Runs through the
codexCLI - Uses
CODEX_API_KEYorOPENAI_API_KEY
Gemini, Kimi, Qwen, and OpenAI-compatible endpoints
- Converge scaffolds direct provider IDs for
provider: gemini,provider: kimi, andprovider: qwen - Use
provider: acpwhen you want an arbitrary OpenAI-compatible endpoint or a custombaseUrl - Mixing cheaper and stronger providers inside one playbook is the main cost/performance lever
Portable by design
- Skills help agents do the work
- Playbooks define the work
- Providers are execution backends you can swap underneath the same playbook
| Package | Path | Purpose |
|---|---|---|
@openplaybooks/converge-core |
packages/core/ |
Programmatic TypeScript engine: runner registry, task graph, state machine, repair strategies. |
@openplaybooks/converge |
packages/cli/ |
Canonical npm install target for converge. Bootstrap, run, watch, tail. Drives runs via provider backends. |
| Provider packs | packages/{claude,gemini,kimi,qwen}fn/ |
Provider-specific backends. Swap without changing playbooks. |
This repo ships features through three playbooks at .converge/playbooks/:
sources → rfc-ideation → human → rfc-shipping → code-audit → human → shipped
rfc-ideation drafts RFCs. A maintainer accepts one. rfc-shipping opens the PR. code-audit reviews it. A maintainer merges.
| To contribute… | Do this |
|---|---|
| An idea | Drop a file in docs/ideas/ |
| A bug or request | Open an issue |
| A code change | Open a PR |
Dev setup is in CONTRIBUTING.md. The full SDLC is in .converge/README.md.
- Discussions — questions, ideas, playbook patterns
- Issues — bug reports, feature requests
- Contributing — dev setup, project structure, how to ship a PR
Mezon The Live, Work, and Play Platform. |
NCC.plus Enterprise AI adoption services. |
To sponsor Converge or list your services here, open an issue or reach out via Discussions.
MIT — see LICENSE
Autonomous · Repeatable · Verifiable