coxswain-tools

Deterministic tools the agent seats call instead of spending tokens. Anything a seat would otherwise do by reading a file wholesale and reasoning about it — summing a run's cost, counting what a traced node did, cleaning up after a run, serving a plan — is a function here that reads it and answers.

The mould, every time: a pure core with no I/O, the filesystem and the network at the edges, dry-run by default where a write is involved, and tests that never touch a real run.

The fifth repository

Tools that read coxswain-graphs' records belong to neither; a seat routes to them by name the way it routes to skills. Nothing here names an employer, a tracker, or a person — CI refuses it.

Install

See docs/getting-started.md for the full setup, from cloning all three repositories to a verified first run.

Not yet on PyPI: once the first tag ships, this package will be coxswain-tools, installable as pip install coxswain-tools or uv tool install coxswain-tools.

git clone https://github.com/ppfenning/coxswain-tools ~/repos/coxswain-tools
cd ~/repos/coxswain-tools && uv venv && uv pip install -e ".[dev]"
uv tool install -e .            # `coxswain-tools` on PATH for every seat

Commands

Bare cox, with no subcommand, opens the coxswain session: a real Claude Code session with the coxswain plugin loaded, working directory at the profile's workspace_dir. It also takes the chair lock under chair-<YYYY-MM-DD> before starting; a live foreign holder is printed, not stolen, and the session starts anyway. agent-tools still works this release as a deprecated alias for cox.

cox runs usage RUN_ID [--runs-dir RUNS_DIR] [--json]   usage stats and cost for one run
cox runs trace RUN_ID [--runs-dir RUNS_DIR] [--role ROLE] [-v]   the tool-call trace for one run
cox runs clean RUN_ID --repo REPO [--worktree-root WORKTREE_ROOT] [--runs-dir RUNS_DIR] [--profile PROFILE] [--apply] [--force]   delete a run's worktree and branches locally
cox runs land RUN_ID --repo REPO [--task TASK] [--phase PHASE] [--label LABEL] [--force] [--no-claim] [--worktree-root WORKTREE_ROOT] [--apply] [--no-merge] [--runs-dir RUNS_DIR] [--profile PROFILE] [--gate ticket|phase|epic|full]   merge a run's branch into the target repo
cox runs recover RUN_ID TASK_ID --repo REPO [--runs-dir RUNS_DIR] [--profile PROFILE] [--dry-run]   merge an approved task's commit into its phase branch after an escalated merge
cox runs series [--runs-dir RUNS_DIR] [--json] [--append APPEND]   per-run summary rows across a runs directory
cox runs events [--runs-dir RUNS_DIR] [--follow] [--json]   poll a run's log for structured events
cox runs top [--runs-dir RUNS_DIR] [--interval INTERVAL] [--once]   live table of runs in flight; --once prints it and exits
cox runs bar [--runs-dir RUNS_DIR]   one Waybar JSON line: runs in flight, cost, class idle|running|attention
cox runs notify [--runs-dir RUNS_DIR] [--once] [--interval INTERVAL] [--replay]   desktop notifications for exits, quarantines, budget stops and cost
cox runs detail RUN_ID [--runs-dir RUNS_DIR] [--json]   one run's timeline, objection and last tool calls
cox runs stranded [--runs-dir RUNS_DIR] [--profile PROFILE] [--json]   every approved task record whose work item is not done, with its remedy
cox courier send REF --to TO --note NOTE [--profile PROFILE]   append a bus entry naming a courier reference
cox courier inbox [--label LABEL] [--profile PROFILE]   list this label's unacknowledged bus entries
cox courier ack ID [--profile PROFILE]   acknowledge one bus entry by id
cox versions [--root ROOT] [--manifest MANIFEST]   component versions against the manifest
cox install --root ROOT [--manifest MANIFEST] [--provider PROVIDER] [--with FLAG] [--team TEAM] [--workspace WORKSPACE] [--edge] [--dry-run]   clone/update coxswain components against the manifest
cox upgrade --root ROOT [--manifest MANIFEST] [--provider PROVIDER] [--with FLAG] [--team TEAM] [--workspace WORKSPACE] [--to TO] [--dry-run]   fetch and check out newer pinned versions; refuses dirty checkouts
cox home [--profile PROFILE]   the live dashboard: runs, leader, backlog
cox stats ingest [RUNS_DIR] [--db DB] [--work-store-root WORK_STORE_ROOT] [--cartridges-repo CARTRIDGES_REPO]   load usage, task, node and launch records into stats.db
cox stats roles [--db DB] [--json] [--cartridge-sha CARTRIDGE_SHA] [--provider-profile PROVIDER_PROFILE]   landed rate, attempts-to-land and $/landed per role and model
cox stats explain ROLE [--db DB] [--json]   the failure-class breakdown behind one role
cox stats series [--db DB] [--json] [--cartridge-sha CARTRIDGE_SHA] [--provider-profile PROVIDER_PROFILE]   per-run summary rows read from the stats store
cox stats coverage [--db DB] [--json]   known/total provenance rows for runs, calls and tasks
cox stats bounds [--db DB] [--json] [--level strict|moderate|liberal] [--profile PROFILE] [--write WRITE]   n/p50/p95/max and strict/moderate/liberal candidate ceilings per role and model
cox stats spend-mix [--db DB] [--json]   per-model token counts and cost share by class, plus the build-only split
cox usage assess [--json] [--runs-dir RUNS_DIR] [--profile PROFILE]   the pacing verdict for the current spend window
cox plan serve DIR [--kind KIND] [--check] [--no-open]   serve a visual plan through the local bridge
cox epic watch PIDFILE [--log LOG] [--max-seconds MAX_SECONDS] [--interval INTERVAL] [--json]   poll a detached run's pidfile until it exits
cox route context [--profile PROFILE] [--json]   the routing profile's resolved context
cox route status [--profile PROFILE] [--json]   what is queued or running for this profile
cox route file [--profile PROFILE] [--repo REPO] [--title TITLE] [--body BODY] [--phase PHASE] [--intake] [--from-intake FROM_INTAKE]   file a new ticket for the harness
cox route lint INITIATIVE_DIR [--repo REPO]   static ticket lint over a filed initiative, work-shape.md §3
cox route groups [--profile PROFILE]   print the newest plans/intake-groups/<date>.md file, work-shape.md §5
cox router select --role ROLE [--db DB] [--profile PROFILE] [--json]   the effective tier for a role under the profile's router: off|shadow|on flag
cox steward propose [--db DB] [--profile PROFILE] [--json]   write each candidate clearing the evidence bar as a new intake file; never edits a provider profile
cox setup doctor [--profile PROFILE] [--repo REPO] [--json]   check this machine's profile against what it needs
cox setup install --root ROOT --team TEAM --workspace WORKSPACE [--provider-profile PROVIDER_PROFILE] [--skills-root SKILLS_ROOT] [--assume a|r] [--plugins] [--hook] [--force-profile] [--dry-run] [--window-ceiling-usd WINDOW_CEILING_USD] [--weekly-ceiling-usd WEEKLY_CEILING_USD]   clone components and write a profile for this machine
cox dev release VERSION [--manifest MANIFEST] [--dry-run] [--root ROOT] [--checkout NAME=PATH] [--umbrella UMBRELLA] [--allow-doc-drift REASON]   the lockstep tag/bump-manifest/notes plan across coxswain's manifest, or (without --dry-run) tags and pushes every component
cox dev release-check [--manifest MANIFEST] [--root ROOT] [--json] [--checkout NAME=PATH]   gather facts and print drifts between the CLI, the manifest, the docs and the release notes
cox dev backfill-github-releases --root ROOT [--dry-run]   walk the umbrella's past docs/releases/<version>.md files oldest-first, creating or editing the GitHub Release for every tagged repo missing or drifted from one
cox dev commands render [--target all|pages|readme] [--pages-dir PAGES_DIR] [--readme README]   write the plugin's slash-command pages and the README's Commands section from the command table

These route subcommands are built by hand in build_parser and are not yet rows in the command table, so the renderer does not emit them:

cox route launch epic --initiative DIR [--repo PATH] [--fix-attempts N] [--dry-run]   start the harness detached with a pidfile and log, and AGENT_GRAPHS_TRACE_DIR set to `<runs_dir>/<run-id>-trace` so every node writes a trace; exit 2 on a missing profile or harness venv, a missing initiative.md, a dirty repo, or a live run of the same initiative
cox route launch decompose --idea FILE --initiative-id ID [--dry-run]   start the harness detached; exit 2 on a missing profile, harness venv, or idea file
cox route launch cos [--dry-run]   start the chief of staff detached: it reads intake and runs, dispatches within the bound, and consumes what it dispatched
cox route sync [--item ID] [--project OWNER/N] [--dry-run]   one-way mirror of the work store onto a GitHub Projects board; exit 2 if gh is not authenticated
cox route sync --project OWNER/N                accept an existing project instead of creating one named "Coxswain" under the repo's owner
cox setup   a small terminal UI over setup doctor, setup install and cartridge init (needs a terminal)

cox runs bar is a Waybar custom module: one JSON line of {text, tooltip, class} per poll, class one of idle, running, attention (a run quarantined or budget-stopped since its last exit). Click launches the same floating window as the dotfiles' runs top chord; right-click opens the HUD.

// ~/.config/waybar/config.jsonc
"custom/runs": {
    "exec": "cox runs bar --runs-dir ~/runs",
    "return-type": "json",
    "interval": 5,
    "on-click": "runs-top-float",
    "on-click-right": "cox-hud"
}

Maintainers

cox dev holds commands a maintainer of the coxswain repositories runs; nothing here is needed to use Coxswain. cox release is a one-release alias that prints moved: use cox dev release and exits 2.

cox dev release VERSION [--dry-run] [--manifest PATH] [--root DIR] [--checkout NAME=PATH] [--umbrella PATH]   the lockstep plan: tag every component, bump the manifest (skipped on a first cut of the declared version), notes, tag_self; exit 2 on refuse (bad semver, an existing tag, a lesser version, or a checkout that is not a ppfenning/coxswain remote); without --dry-run, executes only a first-cut plan — tags and pushes every component and the umbrella in turn, refusing before tagging anything if a checkout is dirty, off its default branch, the release note is missing, or the plan still carries a bump_manifest step (bump and commit the manifest by hand first). A `lockstep = false` component with commits past its pinned tag rejoins this release (tagged at VERSION, same as a lockstep component) instead of getting a plain `pinned` step; an unchanged one stays pinned.
cox dev release-check [--json] [--root R] [--manifest PATH]   runs the registered docs checks over facts named by the manifest and prints their drifts; reports rather than blocks (exit 0), says how many checks ran, and refuses (exit 2) only when it cannot read the manifest

Every command that reads a record is pure over parsed data and unit-tested against fixtures; every command that writes is dry-run unless --apply.

The route group reads one profile, ~/.config/coxswain-tools/profile.yaml: team, cartridges_dir, skills_roots, provider_profile, harness_dir, workspace_dir, and assume, the gate answer detached runs are started with. --profile PATH overrides the location for one command, AGENT_TOOLS_PROFILE overrides it for a shell, and the default path is read when neither is set. Without a profile, route context prints one line and exits 0; file, launch and status exit 2 and name the path they looked for. --dry-run on either launch prints the argv, the pidfile and the log path and starts nothing.

Why this exists

One day of live epics found every defect by reading a usage file or a trace, by hand, in a chief-of-staff's own turns: summing costs, counting Bash calls, noticing a node read a 1,900-line file whole. Each of those readings cost tokens and produced the same answer every time. They are functions now, and the steward seat runs them.