crewyard

Ship together. Merge safely.

The local-first coordination engine for independent AI coding agents.
One workflow for planning, parallel execution, review, and integration.

Get started   ·   How it works   ·   Architecture   ·   Documentation

_{In development toward v1.0 · MIT licensed · No hosted backend required}

[!NOTE] Pre-1.0 software. Crewyard is being developed toward v1.0, and commands and configuration may still change between minor versions. Run crew <command> --help to see what your installed version supports, and check the changelog before upgrading.

Coding agents are good at writing code. Coordinating them is the hard part.

Running multiple independent agents on one repository creates a new set of engineering problems: duplicated work, conflicting edits, stale context, overflowing PR queues, repeated reviews, and merges that invalidate work already in flight.

Crewyard is the coordination layer between your agents and your repository. It gives independent agents a shared, durable workflow—without forcing them to use the same model, provider, or chat session.

One workflow. From goal to merge.

flowchart LR
    A["01 · Plan"] --> B["02 · Schedule"]
    B --> C["03 · Execute"]
    C --> D["04 · Review"]
    D --> E["05 · Integrate"]
    E --> F["06 · Reconcile"]
    F -. "Unblock dependent work" .-> B

    classDef default fill:#18181b,color:#fafafa,stroke:#52525b,stroke-width:1px;
    classDef finish fill:#134e4a,color:#f0fdfa,stroke:#2dd4bf,stroke-width:1px;
    class F finish;

1. Plan with dependencies. Turn a goal into a validated task graph and approve the plan before execution.
2. Schedule safely. Dispatch ready tasks subject to concurrency limits, dependencies, and reservations.
3. Run independently. Assign work to Codex, Claude Code, OpenCode, or another compatible process in isolated worktrees.
4. Review with evidence. Collect structured handoffs, tests, and review findings associated with the work being proposed.
5. Integrate deliberately. Coordinate pull requests and validation without bypassing repository protections.
6. Recover and continue. Persist events, reconcile remote state, re-index the base, and unblock downstream tasks.

Built for real engineering workflows

Installation

Crewyard targets Linux (x64, arm64), macOS (Apple Silicon, Intel), and Windows (x64). You need Git 2.38+, at least one compatible coding-agent CLI, and the authenticated GitHub CLI for GitHub integration.

Install with npm

npm install --global crewyard
crew version

npm installs a prebuilt binary for your platform; Node.js 22+ is only needed for the small launcher. Standalone binaries that need neither Node.js nor Bun are attached to every GitHub release.

Install from source

Requires Bun 1.4.4+.

git clone https://github.com/orafaelfragoso/crewyard.git
cd crewyard
bun install --frozen-lockfile
bun run crew doctor

In a source checkout, run bun run crew from the repository root wherever this README uses crew.

See installation and upgrades for supported platforms, direct binary installs, checksums, backups, and removal.

Quick start

New to Crewyard? The getting-started guide walks through every step and what each one does.

# 1. Register your repository
cd ~/src/my-repo
crew doctor
crew init --repo .

# 2. Add an account: reuse the Claude Code login you already have
crew account add --provider claude --name personal --use-default-config
crew account test claude/personal

# 3. Create agents that use it, and turn on AI review
crew agent create --name architect --role architect --account claude/personal
crew agent create --name engineer  --account claude/personal
crew agent create --name reviewer  --role reviewer  --account claude/personal
crew config set review.reviewer_agent reviewer --yes

# 4. Give it a goal, review the plan, approve it
crew goal create --title "Add JWT authentication" --description-file goal.md
crew goal plan GOAL-1 --agent architect
crew goal status GOAL-1
crew goal approve GOAL-1 --yes

# 5. Let it work, and watch
crew service start
crew dashboard

GOAL-1 is the ID that goal create prints. Codex and OpenCode work the same way with --provider codex or --provider opencode. For separate logins, several accounts or API keys, see Accounts; to change or remove agents, see Agents and policies.

To let Claude Code, Codex and OpenCode sessions you start yourself use Crewyard's tasks and tools, run crew install (add --dry-run first to see the changes). The guide lists where it installs the MCP server and Skills.

The background service keeps dispatching ready tasks; the MCP server alone does not keep work running after its host exits.

Getting started →  ·  Accounts →  ·  Agents →  ·  CLI reference →

How it works

Crewyard is a local orchestration system, not an LLM gateway. It coordinates tools you already use while maintaining its own authoritative task and integration state.

flowchart TB
    DEV["Developer / automation"] --> CLI["CLI & terminal dashboard"]
    AG["Codex · Claude Code · OpenCode · Other"] --> MCP["MCP server & Agent Skills"]

    CLI --> APP["Shared application services"]
    MCP --> APP

    APP --> PLAN["Task graph & scheduler"]
    APP --> CTX["Versioned index & context"]
    APP --> REV["Review & integration"]
    APP --> EVT["Events & observability"]

    PLAN --> WORK["Isolated Git worktrees"]
    REV <--> GH["GitHub & CI"]
    PLAN --> DB[("Local SQLite")]
    CTX --> DB
    REV --> DB
    EVT --> DB

    classDef default fill:#18181b,color:#fafafa,stroke:#52525b,stroke-width:1px;
    classDef store fill:#134e4a,color:#f0fdfa,stroke:#2dd4bf;
    class DB store;

The architecture is deliberately provider-agnostic. The CLI and MCP server are thin interfaces over shared application services. SQLite WAL provides durable coordination; external GitHub and process side effects are reconciled rather than treated as a single database transaction.

For an engineering-level explanation, see the architecture overview, indexing model, and task/lease design.

Interfaces

Safety is an architectural boundary

Autonomous agents should not be able to bypass coordination simply by asking for it.

• Fenced task leases prevent stale workers from submitting work as the current owner.
• Scoped worktrees separate parallel tasks and protect developer checkouts.
• Approval and policy gates control high-impact transitions.
• GitHub branch protections remain authoritative during integration.
• Idempotent outbox operations support retries and recovery after interruption.
• Local credential handling keeps secrets out of repository configuration and orchestration event logs.

Security properties depend on configuration and implementation maturity. Read the security model and default policies before enabling unattended workflows.

Documentation

Development

The codebase is a Bun/TypeScript monorepo with packages for scheduling, providers, indexing, reviews, integration, storage, and telemetry.

bun install --frozen-lockfile
bun run typecheck
bun run lint
bun test
bun run build:binaries  # platform binaries, manifest and checksums
bun run build:npm       # npm tarballs, after binaries have been built

See AGENTS.md for code conventions, the architecture documentation for package boundaries, and the release process for distribution.

Contributing

Contributions are welcome. Read the contributing guide and the code of conduct, and use GitHub Issues for bug reports and feature requests. Report vulnerabilities privately as described in the security policy.

Project status & licensing

Crewyard is under active development toward v1.0. Releases are cut automatically from main with release-please; every release is listed in the changelog and on the releases page. See the release process for how npm packages and platform binaries are built and published.

Licensed under the MIT License. Copyright © 2026 Rafael Fragoso.