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 [--runs-dir runs] [--json]   cost, turns, cache share — by role and by model
cox runs trace RUN [--role build] [-v]          per node: turns, cost, tools, reads, whole-file reads, commands
cox runs clean RUN --repo PATH [--apply] [--force]   the run's worktrees and scratch branches; phase branches kept; a task branch not landed and not on main is kept and printed, not deleted, unless --force; dry-run by default
cox runs land RUN --repo PATH [--task T] [--apply] [--no-merge]   plan and land an approved run: pick branch, cherry-pick, PR, merge on green, clean; dry-run by default
cox runs events [--runs-dir runs] [--follow] [--json]   tail a run's log, trace and usage files as a live event stream
cox runs top   — live table of runs in flight (next task wires the screen)
cox runs bar [--runs-dir runs]                  one Waybar custom-module JSON line: text, tooltip, class idle|running|attention
cox usage assess [--json] [--runs-dir runs]     the pacing verdict for the current spend window against the resolved `policy.pacing.json` in --runs-dir, or the unmeasured default when it is absent
                                                 prints the one-line reason (or the full Assessment as JSON); exit 0 go/go_degraded, 3 hold, 4 stop
cox epic watch PIDFILE [--log LOG]              block until a detached run exits (or the cap), then the outcome lines
cox plan serve DIR [--check] [--no-open]        lint, serve through the local bridge, open in Brave
cox route context [--json]                      what a session reads at start: team, queued intake, runs in flight, initiatives with ready work; exits 0 even with no profile
cox route status [--json]                       every run with a pidfile or a log: alive or exited, started, the log's outcome lines
cox route file --repo PATH --title TEXT [--body FILE|-] [--phase NAME] [--intake]   write a one-task initiative, or with --intake an intake item; exit 2 if a target path exists or the profile is missing
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 router select --role ROLE [--profile PATH] [--json]   the effective tier for ROLE under the profile's router: off|shadow|on flag — off returns the floor, shadow logs select_tier's tier as non-authoritative and still returns the floor, on returns select_tier's tier
cox steward propose [--profile PATH] [--json]   ceiling-change candidates clearing the evidence bar, written as new intake files under the profile's workspace; never opens or edits a provider profile
cox setup   a small terminal UI over setup doctor, setup install and cartridge init (needs a terminal)
cox setup doctor [--profile PATH] [--json]      read-only: profile, paths, harness venv, cartridge, skills, provider, workspace, schema (WARN on a MAJOR mismatch across cartridges/graphs/tools) — a table and an exit code
cox setup install --root DIR --team T --workspace DIR [--plugins] [--hook] [--force-profile] [--window-ceiling-usd N] [--dry-run]   venvs, coxswain-tools on PATH, the profile (with a spend: window_ceiling_usd block when --window-ceiling-usd is given, hard-stopping pacing at 99% of it), optionally the provider plugin and a session-start hook; dry-run prints the plan
cox install --root DIR [--manifest PATH] [--provider NAME] [--with FLAG] [--team T] [--workspace DIR] [--dry-run]   the plan over coxswain's manifest.toml: clone, fetch, skip or refuse per component, then setup_install, doctor, desktop; --dry-run only prints it, otherwise it runs each step and exits 0 only if every step ran clean
cox upgrade --root DIR [--manifest PATH] [--provider NAME] [--with FLAG] [--team T] [--workspace DIR] [--to VERSION] [--dry-run]   same plan as install, but refuses (exit 2, naming the directory) if any present checkout is dirty; --to overrides every component's pinned tag for this run
cox versions [--root DIR] [--manifest PATH]     pinned vs. installed tag per component, status: ok, drift, missing, extra, and a schema column (the cartridges/graphs/tools schema version, or "?")

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.