OpenCastle

Works with GitHub Copilot, Cursor, Claude Code, and OpenCode.

One command sets up specialized agents that decompose tasks, work in parallel, and verify each other's output.

One command. Any repo. Any IDE.

Quick Start

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.

What gets generated

| IDE | Output | |-----|--------| | VS Code | .github/ — agents, skills, workflows, prompts | | Cursor | .cursorrules + .cursor/rules/ | | Claude Code | CLAUDE.md + .claude/ | | OpenCode | AGENTS.md + .opencode/ + opencode.json |

MCP servers are auto-configured for your stack in each IDE's native format.

CLI

| 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 plan | Generate a convoy spec from a task description | | opencastle run | Run the Convoy Engine (deterministic, crash-recoverable orchestrator) | | opencastle dashboard | Open the observability dashboard | | opencastle doctor | Validate your setup and surface issues |

Add --dry-run to any command to preview what it would change without writing files.

📖 Full CLI documentation →

What's Inside

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.

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.

Dashboard

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 →

Doctor

npx opencastle doctor

Runs multiple health checks — manifest, configs, skills, observability logs, IDE settings, MCP setup, and environment variables. Useful in CI or after upgrading.

📖 Doctor CLI documentation →

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-code
branch: feat/reviews

tasks:
  - id: migrate-db
    agent: database-engineer
    prompt: "Create a reviews table migration."

  - id: build-component
    agent: ui-ux-expert
    prompt: "Build a ReviewCard component."

  - id: wire-page
    agent: developer
    prompt: "Add reviews to the place detail page."
    depends_on: [migrate-db, build-component]

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, and OpenCode in the same convoy.

Generate a convoy spec from a plain text description — no YAML by hand:

npx opencastle plan --file task.txt

📖 Full Convoy Engine documentation →

Architecture

See ARCHITECTURE.md for the full diagram, workflow templates, and quality gates.

Contributing

1. Fork the repo
2. Create a branch — feat/your-feature or fix/your-fix
3. Make changes and ensure npm run build:cli passes
4. Open a PR

For large changes, open an issue first.

Support

OpenCastle is free and open-source.

For corporate sponsorship inquiries, open a GitHub Discussion.

License

MIT — Filip Mares, 2026