Quick start · OpenFleet

01 · BEFORE YOU STARTWhat you need

Node.js 22 or later, and git, on macOS or Linux (on Windows, use WSL2).
A signed-in agent host: GitHub Copilot CLI or Claude Code 2.1.219 or later. Setup asks which one to use.
gh, signed in, if you want the run to end in draft PRs.

02 · INSTALLThree commands

Run them in a new, empty folder. That folder becomes your workspace.

MAKE A WORKSPACE

mkdir my-fleet && cd my-fleet

INSTALL OPENFLEET INTO IT

npm create @openfleet-tools@latest

DESCRIBE THE CHANGE

npx openfleet new account-id "Rename user_id to account_id everywhere"

Run npx openfleet inside your workspace folder. There it runs the OpenFleet CLI that setup installed. Outside it, npx would offer to download a different, unrelated npm package that is also named openfleet. From anywhere else, use npx @openfleet-tools/cli <command>.

Want to see it work first? Run pnpm demo from a checkout of the repo to try a toy example.

03 · YOUR REPOSTell it where your code lives

repos.json lists the repos and packages a change can touch, with their build and test commands. A repo can be a local path or a git url that OpenFleet clones for you. You don’t have to write it by hand: the grill suggests repos, finds their commands and confirms them with you.

{
  "v": 1,
  "repos": {
    "api": { "path": "../api", "build": "pnpm build", "test": "pnpm test" },
    "app": {
      "path": "../app",
      "test": "pnpm test",
      "e2e": "pnpm test:e2e",
      "env": ["AUTH_CLIENT_ID", "AUTH_CLIENT_SECRET"],
      "copyFiles": [".env.local"]
    },
    "web": {
      "url": "git@github.com:acme/web.git",
      "packages": { "ui": { "path": "packages/ui", "test": "pnpm -F ui test" } }
    }
  }
}

env names the variables a repo needs, never their values. copyFiles lists git-ignored files, such as .env.local, to copy into every worktree; they are never committed and are redacted from the event log.

04 · THE RUNAnswer once, then step away

Grill. The coordinator asks about the change: which repos, which parts of an app, the contracts between them, what to test first, and how the run should finish.
Spec. It writes spec.md and asks one last question, “anything to change?”. Your answer starts the run.
Plan and agree. Every planner runs at once. No code is written until the plans agree with the spec and with each other.
Build and test. In dependency order, each child gets an optional baseline, an implementer and a tester. A repo split into parts merges them into one branch.
Finish. Changes come back staged in each worktree, or as draft PRs that link to each other. summary.md lists every assumption, failure and follow-up.

Watch an example run, event by event.

05 · FROM SCRATCHNo repos yet? Describe the system

Ask for something new with npx openfleet new invoices "…", for example “create an invoice and payment tracking website with microservices and a frontend”, and the grill builds it from nothing. It proposes the services and their contracts, recommends one monorepo, asks about the stack once (with a recommendation for each answer), and offers a private GitHub repo.

A run builds an MVP slice: the core flows plus one end-to-end flow that proves them, such as create invoice → record payment → invoice shows paid. Everything else goes into the spec’s Follow-ups. The CLI enforces the limits (5 services, 12 children and 8 acceptance criteria per child by default), so the scope can’t quietly grow during the run.

Then the children run in order: setup scaffolds each repo with the official generators, contracts writes the schemas and generated clients, the services and the frontend build on them in parallel, and system adds docker-compose, seed data and the end-to-end test. The work lands on main, or in one draft PR, only when that test passes. npx openfleet continue invoices starts the next slice from the Follow-ups.

06 · PERMISSIONSKnow what it can touch

Inside the workspace and the repos you list, tools run without asking, so the run doesn’t stop for every edit. Any other path, and every URL, still prompts. Pass --ask to new or resume to be asked before every tool.

07 · COMMANDSStart it, check on it, pick it back up

Every command runs from the workspace folder.

npx openfleet new <name> ["<request>"]: Create a project and start the grill
npx openfleet status [name] [--json]: Each child’s phase, retries and open questions, grouped by repo
npx openfleet resume <name> [--fresh]: Continue a project, optionally in a new agent session
npx openfleet list: All projects in the workspace
npx openfleet clean <name> [--branches]: Remove the project’s worktrees, and optionally its branches
npx openfleet config: Show workspace settings, such as how many agents may work at once
npx openfleet init: Create the workspace in the current folder and choose its host (Copilot CLI or Claude Code)
npx openfleet update: Update to the installed CLI version

Arguments after -- go straight to the agent CLI. Extension commands are on the Extensions page, and the full list is in the README.

08 · THE WORKSPACEWhere everything lives

Commit the settings and the repo list. Worktrees and patches stay out of git.

my-workspace/
  package.json  node_modules/
  openfleet.json          # workspace marker and settings
  repos.json              # repos, packages, build and test commands
  extensions/             # installed extensions
  projects/<name>/
    spec.md  state.json  events.jsonl  summary.md
    contracts/  plans/
    worktrees/<child>/    # one per child, plus one per merged repo

Ready when you are

Questions, ideas or a bug? The repo is open, and issues are welcome.

VIEW ON GITHUB SEE AN EXAMPLE RUN

Your first fleet in three commands.