Metadata-Version: 2.4
Name: coxswain-tools
Version: 0.15.0
Summary: The coxswain's operator tools behind the `cox` command; `agent-tools` is a deprecated alias for one release.
License: MIT License
        
        Copyright (c) 2026 Patrick Pfenning
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Repository, https://github.com/ppfenning/coxswain-tools
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# 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

| Repository | Owns |
|---|---|
| [`coxswain-cartridges`](https://github.com/ppfenning/coxswain-cartridges) | who a run works for |
| [`coxswain-graphs`](https://github.com/ppfenning/coxswain-graphs) | what runs, and the harness that runs it |
| [`coxswain-crew`](https://github.com/ppfenning/coxswain-crew) | who speaks |
| **`coxswain-tools`** | what the seats run so they do not have to think |

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`](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`.

```bash
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`.

<!-- commands:begin (generated by `python -m devtools commands render`; do not edit) -->
```
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 review --pr PR [--profile PROFILE]   review a contributor PR with the review graph and post the verdict
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 runs cause RUN_ID TASK_ID ticket|code|harness|unknown [--note NOTE] [--runs-dir RUNS_DIR] [--profile PROFILE]   record why one run's attempt at a task was quarantined
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 stats chair [RUNS_DIR] [--since SINCE] [--json] [--session SESSION] [--work-store-root WORK_STORE_ROOT] [--projects-dir PROJECTS_DIR] [--profile PROFILE]   harness PRs and $, chair $ per PR, hand-finished lands and quarantine $ by cause
cox stats examples [RUNS_DIR] --role ROLE [--out OUT] [--since SINCE]   the local system-one backend's training file (JSON lines) from task records
cox stats system-one [RUNS_DIR] [--role ROLE] [--since SINCE] [--json] [--propose] [--plans-dir PLANS_DIR]   shadow-to-on graduation report per role, and a proposal for the maintainer to approve
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 pull [--profile PROFILE] [--source SOURCE] [--dry-run]   file intake tickets from a source, once per link
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
```
<!-- commands:end -->

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.

```jsonc
// ~/.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` moved: run `uv run --frozen python -m devtools <command> ...` from the coxswain checkout (from 0.15.0); `cox dev` and `cox release` print that pointer and exit 2.

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.
