agent-builder is a mother agent you add to Claude Code, OpenAI Codex, or GitHub Copilot. Those hosts interview you, compile a spec, and emit a reusable standalone agent.
It is a plugin / custom agent. It is not a skill, not a command-line product, not a web app, and not a wrapper around LangGraph, LangChain, or CrewAI.
Beginners write a markdown outline. Pros write YAML. Both compile to the same graph. Every generated agent copies in a small Python kernel so the result can leave this repository and still run.
- A mother agent that asks and probes until Goal, Users, Inputs, Outputs, Agents, Tools, Flow, Approvals, Hard limits, and Done when are complete
- A strong refuse (no generation) when the picture is still incomplete
- Generated agents that are standalone: copied kernel, host files for Claude Code / Codex / Copilot, tests, docs
- First-class graphs: series, fan-out/join, supervisor/workers, critic loop, conditional router, human gate, nested sub-agent
- Guardrails that tests actually execute: tool allowlists, schema checks, bounded loops, traces, human gates that cannot be skipped
This repository is a Claude Code plugin (manifest in .claude-plugin/plugin.json) and a one-plugin marketplace.
/plugin marketplace add rmkr-dev/agent-builder
/plugin install agent-builder@agent-builder
Local checkout:
/plugin marketplace add /path/to/agent-builder
/plugin install agent-builder@agent-builder
Or launch with --plugin-dir /path/to/agent-builder. Then ask Claude to build an agent, or invoke the agent-builder agent.
Open this repository, or copy AGENTS.md into the project where you want to design agents. Codex loads AGENTS.md. Ask it to interview you and generate a standalone agent.
Open this repository (or copy .github/agents/agent-builder.agent.md into your project). Select the agent-builder custom agent. .github/copilot-instructions.md points Copilot at the same playbook.
Use the headings in docs/beginner-markdown.md. A short paragraph is a start, not a spec: the mother agent will interview you until the outline is complete. Example: examples/series-summarizer/spec.md.
Same fields, typed. See docs/pro-yaml.md. Example: examples/research-brief/spec.yaml.
| Field | Meaning |
|---|---|
| Goal | What the generated agent must accomplish |
| Users | Who it is for |
| Inputs | Named inputs, types, required/optional |
| Outputs | Named outputs and quality bar |
| Agents | Each worker's name and job |
| Tools | Explicit grants only (or none) |
| Flow | Series, split/join, loop, handoff, approval, nested |
| Approvals | Where a human must say yes (or none) |
| Hard limits | max_steps, max_loops, tool allowlist |
| Done when | Measurable exit conditions |
Details: docs/spec-fields.md.
The mother agent writes a directory that contains:
spec.yaml/spec.json— compiled graphkernel/— copied graph runner (Python 3.11+, standard library)agents/,AGENTS.md,.github/agents/— host surfaces for Claude Code, Codex, Copilottests/— real graph tests with scripted adapters (no live model)docs/— spec + reliability rules
How to add that generated agent to a host is in its own README.md.
There is no agent-builder CLI. Hosts import the library or write files from the playbook. Generated agents use python -m pytest in tests and CI only.
The kernel runs the graph you specified. Branching is not a comment in a prompt.
| Pattern | Kernel node |
|---|---|
| Fan-out / join | parallel with join: all or join: any |
| Supervisor / workers | supervisor with bounded max_dispatch |
| Critic loop | critic with retry and max_iters |
| Conditional router | router with routes |
| Human gate | human_gate (cannot be skipped) |
| Nested sub-agent | nested inline spec |
| Series | task nodes with next |
Reliability rules (enforced in tests): traces on every hop, tool allowlists, schema checks, step/loop budgets, critic/loop bounds. See docs/reliability.md and docs/branching.md.
Canonical example, used in docs and tests:
planner → parallel specialists → join → critic → approval → finalizer
Simple series:
Python 3.11+. Hosts and CI import it; users do not run a product CLI.
from pathlib import Path
from agent_builder import load_yaml, emit
spec = load_yaml(Path("examples/research-brief/spec.yaml"))
emit(spec, Path("generated/research-brief"))Markdown beginners:
from pathlib import Path
from agent_builder.generate import load_and_emit
load_and_emit(Path("examples/series-summarizer/spec.md"), Path("generated/series-summarizer"))python -m pip install -e ".[dev]"
python -m pytest
No live model is contacted. Kernel tests drive scripted agents, tools, and human gates.
MIT. See LICENSE.