Coxswain

Agents pull the oars. You hold the tiller.

Docs · Releases · PyPI

Coxswain is a platform that builds software with a crew of AI agents and keeps a person on the tiller. You describe a change; it is filed as a work item, planned, built in a worktree under a dollar budget, reviewed by two independent reviewers who are made to disagree, arbitrated, checked against the project's own tests as evidence, and handed to you as a pull request. You merge. Every step leaves a record you can read back.

Status: beta. The loop runs itself daily on its own repositories. Interfaces are still moving; see the release notes for what each version changes.

Install

uv tool install coxswain-tools
cox setup doctor

cox setup doctor tells you whether this machine can run an epic and what is missing. cox install sets up every component from the manifest in this repository; cox setup is a screen over the same steps. The install guide covers a fresh machine end to end.

The loop, in one screen

cox route file  --repo R --title T --body FILE   # a work item, from a sentence or a file
cox route launch epic --initiative work/<id>     # plan → build → review ×2 → arbitrate → check → validate
cox runs top                                     # every run in flight, live
cox runs land <run> --repo R --apply             # rebase, PR, merge on green, clean up

A run is a detached process. It plans one task at a time, builds it in a worktree it owns, runs the real tests, and asks two reviewers — one holding the change to the team's written charter, one whose job is to find what is wrong — before an arbiter decides. A task that fails its budget is split, never given more money. Nothing merges to a default branch without a person.

What is in the box

This repository is the umbrella: the docs site, the version manifest that pins every component in lockstep, and the installer. The components are their own repositories, tagged together at every release.

The manifest is manifest.toml. cox versions reports every installed component against it.

Make it yours

Everything a stranger needs is a command in a public repository; everything that makes it yours is a file the command reads. A cartridge is that file for your team — which skills each role carries, what budget a build gets, what a reviewer holds code to. A profile is that file for your machine. Neither is code. cartridge init <team> writes one that inherits everything and lets you tighten what you care about; the customize guide walks through it.

Contributing

Every change to any component lands as a pull request, most of them built by the platform itself. Ruff runs in CI and pre-commit on every repository with one shared rule set; pre-commit install mirrors it locally. Ideas go in as intake items and are decomposed before they are built.

License

MIT. See LICENSE.