coxswain
Agents pull the oars. You hold the tiller.
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 repository. Interfaces are still moving; see the release notes for what each version changes.
towpath, Coxswain's terminal home: the chair, the machines and every run on one screen.
Install
One package, coxswain. One command, cox.
brew install ppfenning/coxswain/cox # or: uv tool install --python 3.14 coxswain
cox install --team my-team
mkdir -p <workspace>/work <workspace>/runs <workspace>/intake <workspace>/cartridges
git -C <workspace> init
cartridge init my-team --cartridges-dir <workspace>/cartridges
cox setup doctor
When the home has no checkout, cox install clones one at the release tag matching its own version, such as v2026.10.1, into ~/.local/share/coxswain/installs/coxswain. That one checkout is the whole install: cox install reads its manifest.toml, creates one venv inside it, installs cox editable from it, writes this machine's profile and links the crew. <workspace> is ~/.local/share/coxswain/workspaces/main unless you pass --workspace. The profile starts on the shipped provider profile; a team keeps its own outside the checkout, in <home>/providers/ or the workspace (see the install guide). The install's closing doctor may report the missing workspace and cartridge until the mkdir, git init and cartridge init steps are done.
cox setup doctor tells you whether this machine can run an epic and what is missing. The install guide covers a fresh machine end to end.
Upgrade
brew upgrade cox # or: uv tool upgrade coxswain
cox upgrade
The first updates cox itself. cox upgrade moves the checkout to the newest release, syncs its venv, reinstalls cox from it and relinks the crew.
Coming from 0.47 or earlier? Those releases installed a checkout per component. On each machine:
cox host drain <host> # if the host is active in the hosts table
brew upgrade cox # Homebrew; with uv, the next two lines instead
uv tool uninstall coxswain-tools agent-cartridges
uv tool install --python 3.14 'coxswain[postgres,traces,parquet,lake]' # the extras this machine uses
cox setup migrate # the plan; changes nothing
cox setup migrate --apply
cox setup doctor
cox host activate <host>
cox setup migrate copies a team provider profile the old cartridges checkout does not track to <home>/providers/ and points provider_profile at it; copy catalog.yaml beside it yourself, and edit by hand any of your own scripts that name an old checkout path. Old checkouts are moved to installs/.retired-<date>/, never deleted. From 0.47 to the monorepo has every step and the known issues in 2026.10.0.
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.
Layout
| Folder | What it holds |
|---|---|
src/tools |
The cox command: install, doctor, route, runs, land, the setup screens. |
src/graphs |
What runs: the graphs as pure functions, and the harness that budgets, reviews, checks and records them. |
src/cartridges |
Who a run works for: roles, skills, budgets, policy, provider profiles, the plugin marketplace. |
crew |
The seats: who speaks, with what authority, in what voice. |
docs/, devtools/, tests/ |
The docs site, the release tooling, and the root suite. |
The dashboard, towpath, is a separate Rust repository, coxswain-dash; cox install --with dash adds it, and the Homebrew formula includes it.
Each folder runs its own suite: cd src/tools && uv run pytest -q, and the same in src/graphs and src/cartridges. The root suite is uv run pytest -q from the repository root.
Versions
Releases are CalVer, YYYY.M.N, tagged vYYYY.M.N: the year, the month, and a count of releases in that month from 0. The first is 2026.10.0. A release is one tag, one PyPI publish, one GitHub release and one Homebrew formula update. The number does not promise compatibility; the store and workspace schema and cox setup migrate carry that. 0.47.0 was the last release of the old multi-repository line.
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 lands as a pull request, most of them built by the platform itself. Ruff runs in CI and pre-commit 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.
1 maintainer
Metadata
1 maintainer
Release files for coxswain 2026.10.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| coxswain-2026.10.2.tar.gz | 1.2 MB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| coxswain-2026.10.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.5 MB
Release files / coxswain-2026.10.2.tar.gz
| Download URL | coxswain-2026.10.2.tar.gz |
|---|---|
| Size | 1.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1ece1cd0dea0d14b789d26f07d6deabce90c064d2c2bf98256446ee5bc8b363e
|
|
BLAKE2b-256 checksum How to use checksums |
3aeaf3aaea71ddb75c105d4aa8c7c1b23f13292c2b5bd05b7d53f67da4f6cb6c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 23, 2026.
Transparency logRelease files / coxswain-2026.10.2-py3-none-any.whl
| Download URL | coxswain-2026.10.2-py3-none-any.whl |
|---|---|
| Size | 1.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8b1e7c3116773773368ffab61a9f8195b7c55d17243511da018ebfbc726ef038
|
|
BLAKE2b-256 checksum How to use checksums |
c91496c782997544da737d3c2f6936038e1457522276cf55a77febec63d32dc9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 23, 2026.
Transparency logSecurity for coxswain 2026.10.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for coxswain-2026.10.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 23, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
