Turn your AI coding assistant into a multi-agent team.
Website · Docs · Quick Start · Architecture · Contributing
Works with GitHub Copilot, Cursor, Claude Code, OpenCode, Windsurf, Codex CLI, and Antigravity.
One command sets up specialized agents that decompose tasks, work in parallel, and verify each other's output — interactively through IDE chat or automated via the Convoy Engine.
Use it live in your IDE. Run it overnight with the CLI.
npx opencastle init
The CLI asks about your IDEs and stack. It installs agents, skills, and MCP servers tailored to your project.
You can select multiple IDEs and tools — the output is adapted for each one.
| IDE | Output |
|---|---|
| VS Code | .github/ — agents, skills, workflows, prompts |
| Cursor | .cursorrules + .cursor/rules/ |
| Claude Code | CLAUDE.md + .claude/ |
| OpenCode | AGENTS.md + .opencode/ + opencode.json |
| Windsurf | .windsurfrules + .windsurf/rules/ |
| Codex CLI | AGENTS.md + .codex/ |
| Antigravity | GEMINI.md + .gemini/ |
MCP servers are auto-configured for your stack in each IDE's native format.
| Command | Description |
|---|---|
opencastle init |
Set up agents in your project |
opencastle update |
Update framework files (keeps your customizations) |
opencastle eject |
Remove the dependency, keep all files |
opencastle destroy |
Remove ALL OpenCastle files (reverse of init) |
opencastle skills |
Skill refinement and failure tracking |
opencastle package |
Package orchestrator as a plugin for IDE marketplaces |
| Command | Description |
|---|---|
opencastle start |
Go from idea to convoy spec in one command (PRD → validate → convoy → validate → fix) |
opencastle plan |
Run a single prompt template step (generate PRD, convoy spec, or validate) |
opencastle validate |
Validate a convoy YAML spec file without executing it |
opencastle run |
Run the Convoy Engine (deterministic, crash-recoverable orchestrator) |
opencastle dispute |
Manage convoy dispute resolution |
| Command | Description |
|---|---|
opencastle dashboard |
Open the observability dashboard |
opencastle doctor |
Validate your setup and surface issues |
opencastle agents |
Manage persistent agent identities |
opencastle baselines |
Manage visual regression baselines |
opencastle log |
Append a structured event to the observability log |
opencastle lesson |
Append a structured lesson to LESSONS-LEARNED.md |
opencastle artifacts |
Manage filesystem artifact storage (prune old convoy artifacts) |
opencastle insights |
Analyze convoy execution history and generate recommendations |
Add --dry-run to any command to preview what it would change without writing files.
Specialist Agents. Developer, UI/UX, Database, Security, Testing, Reviewer, and more.
On-Demand Skills. Loaded on demand to keep context windows lean. Auto-selected during init based on your stack. All 51 skills and plugins scored 100% on the tessl Skill Evaluator.
Workflow Templates. Features, bug fixes, data pipelines, security audits — reproducible execution templates.
Quality gates. Fast review after every step. Panel majority vote for high-stakes changes. Lint, test, build checks.
Cost-aware routing. Picks the right model tier (Premium → Quality → Standard → Fast → Economy) based on task complexity.
Self-improving. Agents capture lessons and graduate them into permanent instructions.
Hybrid by design. Use OpenCastle interactively through IDE chat for hands-on development, or run automated batch jobs overnight via the Convoy Engine.
npx opencastle dashboard
Visualizes real agent data from your project — sessions, success rates, model usage, execution logs, and panel reviews.
Reads from the same NDJSON logs your agents already write. No setup needed.
📖 Dashboard CLI documentation →
npx opencastle doctorRuns multiple health checks — manifest, configs, skills, observability logs, IDE settings, MCP setup, and environment variables. Useful in CI or after upgrading.
## Convoy Engine
A deterministic, crash-recoverable orchestrator inspired by Steve Yegge's Gas Town. Define tasks in YAML, run overnight, resume after crashes.
npx opencastle run convoy.yml# convoy.yml
name: "Overnight feature batch"
version: 1
adapter: claude
branch: feat/reviews
tasks:
- id: migrate-db
agent: database-engineer
prompt: "Create a reviews table migration."
files: ["db/migrations/"]
- id: build-component
agent: ui-ux-expert
prompt: "Build a ReviewCard component."
files: ["src/components/reviews/"]
- id: wire-page
agent: developer
prompt: "Add reviews to the place detail page."
depends_on: [migrate-db, build-component]
files: ["src/pages/places/"]
gates:
- npm run lint
- npm run test- Crash-safe — SQLite WAL persistence survives crashes, power loss, OOM kills. Resume with
--resume. - Isolated — each worker runs in its own git worktree. Changes merge back in dependency order.
- Observable — real-time dashboard auto-starts during execution.
- Multi-runtime — mix Copilot, Claude Code, Cursor, OpenCode, Windsurf, Codex, and Antigravity in the same convoy.
Generate a validated convoy spec from a plain text description — no YAML by hand:
npx opencastle start --text "Add user reviews to the place detail page"The start command runs 7 steps automatically: generate PRD → validate PRD → auto-fix PRD if needed → assess complexity → generate convoy spec → validate spec → auto-fix spec if needed. For lower-level control, use opencastle plan to run individual steps.
📖 Full Convoy Engine documentation →
See ARCHITECTURE.md for the full diagram, workflow templates, and quality gates.
- Fork the repo
- Create a branch —
feat/your-featureorfix/your-fix - Make changes and ensure
npm run build:clipasses - Open a PR
For large changes, open an issue first.
OpenCastle is free and open-source.
For corporate sponsorship inquiries, open a GitHub Discussion.
BSL 1.1 — Free for non-commercial use. Commercial use requires a paid license. Each version converts to Apache 2.0 two years after its release.
