Crewplane

Agents do the work. You own the workflow.

Define the whole process in Markdown — the prompts, stages, agents, handoffs, and rules for what happens next. Crewplane runs Claude Code, Codex, Copilot CLI, Gemini, Kilo, or another CLI. Review becomes a gate, completed work survives failure, and every workflow handoff stays on disk.

Watch the workflow run. Keep the full record after the terminal closes.

⭐ If this is how you think coding-agent workflows should work, click Star in the top-right to keep Crewplane in your toolbox — and help more developers find it.

Try it without API keys  ·  See example workflows  ·  Read the documentation

Your agents are automated. Your workflow usually isn't.

Coding-agent CLIs can plan, write, test, and review code. But the process around them often still lives across prompts, terminal tabs, copy-paste, and memory.

You decide what runs next. You carry plans and findings between tools. You make sure review actually happens. When a later step fails, you reconstruct what already worked.

Crewplane turns that manual coordination into a workflow your repository owns. Make review a gate, not a promise buried in a prompt. If a later stage fails, Crewplane keeps the completed work it can validate instead of making you start over.

Without Crewplane	With Crewplane
Prompts, sessions, and terminal habits define the process	Versioned Markdown defines the process
You relay plans, findings, and context between agents	Each stage receives explicit, saved handoffs
One session or provider tends to own the whole chain	Assign the right CLI to each stage
Parallel work and review happen ad hoc	Fan work out, then bring it back through review and bounded fixes
A late failure makes you replay work that already passed	Resume from completed stages Crewplane can validate
Terminal scrollback becomes the history	Keep a readable record of every stage, handoff, finding, and result

Note

Bring the agent setup you already trust. Crewplane invokes the coding-agent CLIs you already use; their models, tools, skills, MCP servers, repository instructions, authentication, and permissions remain under their native control.

Quick start

Install Crewplane and run the generated workflow inside any project. The first run lets you see the workflow and its run record before spending a token:

uv tool install crewplane

cd path/to/your-project
crewplane init
crewplane validate
crewplane run

Important

The first run uses Crewplane's deterministic mock provider. No provider CLI. No API key. No provider account. No token spend. No configuration changes.

Inspect the resulting run record:

.crewplane/
├── execution-results/<run-key>/   # findings and final results
└── execution-stages/<run-key>/    # inputs, outputs, logs, events, and manifests

The output is mocked. The workflow machinery is not. The run-record structure is the same one used for provider-backed workflows, so you can see how Crewplane validates stages, passes work forward, and records the run before connecting a real agent.

Ready to put one of the CLIs already installed on your machine behind the workflow?

crewplane onboarding
crewplane run

crewplane onboarding finds the supported provider CLIs already installed on your machine, lets you choose one, and configures Crewplane to use it. Crewplane does not install provider software or manage provider credentials.

See exactly what your first run creates and keeps

crewplane init creates .crewplane/config.yml, a default workflow, and additional example templates under .crewplane/workflows/example-templates/.

When output is attached to a terminal and tmux is available, Crewplane opens the compact live dashboard for DAG progress, node status, and live log tails.

Note: install tmux via brew install tmux on macOS or sudo apt install tmux on Ubuntu/Debian.

Pass --no-live when you want to omit the live dashboard.

After the first run, the full artifact layout looks like:

.crewplane/
├── execution-results/                  # final outputs you care about
│   └── <run-key>/
│       ├── review.project-findings.md  # findings from the review node
│       └── review.project-result.md    # final result from the review node
├── execution-stages/                   # per-stage raw artifacts
│   └── <run-key>/
│       ├── preflight/                  # plan, dependency graph, render plans
│       ├── logs/                       # events.ndjson, summary
│       └── review.project/             # per-node rendered input, output, logs
├── workflows/                          # your workflow definitions, preloaded with example workflows
│   └── single-agent-review.task.md
└── config.yml                          # provider wiring and settings

These files are the same shape you will see with real providers: each step has rendered inputs, outputs, logs, manifests, and final results you can inspect or diff with normal tools.

Because the first run already wrote a successful result, a later identical run may print Identical context detected (Crewplane reuses the saved result for identical inputs). Use crewplane run --force to start fresh.

Prefer to watch? Jump to the full demo walkthrough →

Build the workflow your work actually needs

Crewplane does not prescribe a lifecycle. It gives yours a home in the repository, whether that means one focused stage or a longer workflow with several agents and checkpoints.

For example:

• Deliver a change with independent checks. Brief → plan → implement → test → review → handoff.

• Compare approaches before choosing one. Ask several agents to explore the problem in parallel, then bring their proposals together for comparison and approval.

• Audit a codebase from several angles. Combine security, performance, architecture, and maintainability reviews into one consolidated result.

• Carry a complex change through controlled checkpoints. Inventory → design → migrate → validate → report.

• Turn a recurring team process into a reusable workflow. Keep the stages, agent assignments, handoffs, and review rules in the repository instead of rebuilding the process from terminal history.

These are examples, not built-in stages. Name the steps yourself, use one agent throughout, or assign different CLIs wherever their strengths fit best.

What a workflow looks like

A Crewplane workflow is Markdown you can read in a code review: YAML frontmatter declares the execution graph, and ordinary Markdown defines the instructions for each stage.

This is the real thing, not a hello-world toy: one file, three stages, explicit handoffs, and a review loop you can rerun.

---
schema_version: "1.0"
name: "Feature Delivery"
description: "Plan, implement, review, and prepare a final handoff."

nodes:
  - id: plan
    mode: parallel
    providers: [claude, codex]

  - id: implement
    mode: sequential
    needs: [plan]
    providers:
      - provider: codex
        role: executor
      - provider: claude
        role: reviewer

  - id: handoff
    mode: parallel
    needs: [implement]
    providers: [gemini]
---

## plan

Turn the request into a concrete plan with scope, risks, and validation steps.

## implement

Use the plan:

{{plan.output}}

<!-- crewplane:executor -->
Implement the change and run the relevant checks.
<!-- /crewplane:executor -->

<!-- crewplane:reviewer -->
Review the candidate for correctness, regressions, and missing validation.
<!-- /crewplane:reviewer -->

## handoff

Prepare a concise handoff from the reviewed implementation:

{{implement.output}}

In this example:

• needs defines which stages wait for upstream work.
• providers assigns configured agents to each stage.
• {{plan.output}} creates an explicit handoff rather than relying on hidden session context.
• The sequential executor/reviewer node can approve the candidate or send blocking feedback into a bounded fix attempt.
• The final stage receives the reviewed result, not an informal summary carried between terminal sessions.

plan, implement, and handoff are examples — not built-in lifecycle stages. Rename them, add more nodes, remove stages, fan work out, compose another workflow, or route every stage to the same CLI.

See the workflow syntax reference for the complete authoring contract.

Important

The agents keep their native tools and behavior. The workflow no longer has to live inside any one agent session.

Every run leaves receipts

A final answer tells you what an agent said. A run record tells you how the work actually happened. Crewplane keeps the answers to questions that disappear when the process lives only inside terminal sessions:

• Which workflow and compiled execution plan ran?
• Which configured agent and role handled each stage?
• What rendered context did that stage receive?
• What output and findings did it produce?
• Which reviewers approved or blocked the candidate?
• Which nodes succeeded, failed, were skipped, or were resumed?
• Which provider-reported usage totals were available?
• Which prior result supplied reused work?

Check the results for each node:

.crewplane/execution-results/<run-key>/

When needed, inspect the run-level records:

.crewplane/execution-stages/<run-key>/

See where the tokens went

At the end of a workflow, Crewplane displays the total token consumption in the run summary. It also records each node's consumption in the runtime logs, so you can see both the overall usage and where the tokens went. These figures appear whenever the provider reports them.

Tip

The files are ordinary local artifacts. Inspect them, diff them, archive them, attach them to a review, or delete them like other build output.

See:

• Watch runs live and inspect results
• Inspect run records
• Artifact reference

When one agent is enough

Crewplane is not a reason to orchestrate everything.

For a quick question, one-off patch, or exploratory session, use the provider directly.

Crewplane begins to earn its place when agent work becomes a process: multiple stages, provider handoffs, parallel work, review loops, repeated runs, or work that must survive failure and remain inspectable afterward.

A useful shell script may also be the right answer for a simple one-time handoff. Crewplane is for the point where the process itself needs to be reviewed, reused, shared, measured, or recovered.

Where Crewplane fits

Crewplane is the control plane around your coding-agent CLIs.

It does not replace their models, tools, sessions, permissions, credentials, or native execution behavior. It controls the process around them: what runs, in what order, with which context, under which review rules, and what remains afterward.

┌──────────────────────────────────────────────┐
│ Workflow owned by your repository            │
│ Markdown · instructions · policies · inputs  │  ← Markdown defines the workflow.
└──────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────┐
│ Crewplane                                    │
│ validate · render · route · review           │
│ resume · observe · record                    │  ← Crewplane enforces the workflow.
└──────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────┐
│ Provider-native coding-agent CLIs            │
│ Claude Code · Codex · Copilot CLI · Gemini   │  ← Agents execute the stages.
└──────────────────────────────────────────────┘
                    ↕
┌──────────────────────────────────────────────┐
│ Repository · filesystem · CI                 │
│ source · tests · logs · manifests · results  │  ← Artifacts stay on disk.
└──────────────────────────────────────────────┘

The agents do the work. Crewplane runs the declared process. Your repository remains the system of record.

Installation and updates

The recommended installation is:

uv tool install crewplane

Update the active installation and confirm its version:

crewplane --update
crewplane --version

Other supported installation paths include pip, pipx, Homebrew, the install script, an npm wrapper, and a local source checkout. See the installation guide for exact commands, update behavior, troubleshooting, and removal.

Note

Crewplane requires Python 3.13 or later and supports Linux, macOS, and WSL. Native Windows is not currently supported.

Important

Crewplane does not install, authenticate, or sandbox provider CLIs. Each provider runs with its own configuration and the permissions available in your environment.

Demo walkthrough

Watch the demo below for the full setup flow: install Crewplane, initialize a project, run the first mock workflow, inspect artifacts, and onboard a real provider.

install-to-run-demo.mp4

---

At this point you have seen the core path: install, run the generated mock workflow, inspect artifacts, and prepare a real provider when ready.

Documentation and examples

The full documentation starts at docs/index.md.

Just getting started? → follow the First Project Path to install Crewplane, run the mock workflow, inspect artifacts, and prepare a real provider.

Guided tour: → use the Guided Tutorial Track to walk through workflow runs, run records, authoring, provider roles, review loops, composition, validation, troubleshooting, and cleanup.

Want to see Crewplane at full strength? → start with one of the generated workflows:

• example-templates/code-review-example.task.md for parallel agent review and reviewer loops.
• example-templates/feature-implement-example.task.md for brief → plan → build → review → handoff.
• example-templates/composition/review-fix-composed-example.task.md for reusable workflow composition.

Run the full examples without starting provider CLIs

With settings.integrations.invoker.implementation: "mock", Crewplane validates those agent profiles but still writes deterministic mock output and does not start provider CLIs. Switch the invoker to cli only when you want real provider runs.

1. Uncomment the agents in the generated config (i.e. lines 22-148), keep the settings.integrations.invoker.implementation as mock so the workflow runs with mock. See how to turn mock on and off for details.

2. Copy and run any one of these commands:

crewplane run --tasks .crewplane/workflows/example-templates/code-review-example.task.md

crewplane run --tasks .crewplane/workflows/example-templates/feature-implement-example.task.md

crewplane run --tasks .crewplane/workflows/example-templates/composition/review-fix-composed-example.task.md

Ready to hook up a real provider? Run crewplane onboarding, or follow the provider setup guide.

Find the right guide for what you want to do next

Here is a quick reference table:

Goal	Start here
Complete the first project	First Project Path
Learn workflow authoring	Workflow syntax
Choose sequential or parallel execution	Node modes and provider roles
Add executor/reviewer behavior	Review loops
Configure real provider CLIs	Provider setup
Inspect stored execution records	Inspecting artifacts
Try generated workflows	Examples guide
Browse all documentation	Documentation home
Review changes between releases	Changelog

Contributing

Contributions, workflow ideas, and real-world failure cases are welcome.

• Read Contributing.
• Set up a local checkout with the development guide.
• Ask questions or propose workflow patterns in GitHub Discussions.

Have a coding-agent workflow that you do not want to leave to a free-running loop? Describe it in Discussions and we can all work together on it.

---

Agents do the work. You own the workflow.

⭐ Have a coding-agent process worth making repeatable? Click Star in the top-right to keep Crewplane in your toolbox.