Skip to main content

pitboss

Sweep a project’s pull requests, merge queue, local checkouts and worker slots, and say what each calls for.

pitboss reads the project’s state from GitHub (through gh api, with the session’s own authentication) and from the checkouts on the machine, and prints one line per thing that needs a look. Every line that calls for an action starts with a marker in capitals and says the action. Everything about one project (its repositories, review format, models, labels, paths) lives in that project’s configuration file; pitboss itself names no project.

Commands

pitboss sweep CONFIG

PRs, runner pressure, queue runs, stragglers, worktrees (it removes the finished ones that are safe to, [clean] worktrees), disk pressure, reminders, slots. Exits 1 on a red or conflicted PR.

pitboss pressure CONFIG

Records a look; one line; exits 1 under runner pressure and until the quiet period is over.

pitboss queued CONFIG

Records a queued job (restarts the quiet period).

pitboss push CONFIG [-- GIT_ARGUMENTS]

Pressure check, git push, record (--no-dry-run).

pitboss cancel-stale-runs CONFIG

Cancel superseded merge-queue runs (--no-dry-run).

pitboss clean-worktrees CONFIG

Remove the finished worktrees that are safe to (--no-dry-run).

pitboss clean-container CONFIG

List, then remove (--no-dry-run, in parts), the dead paths: finished checkouts, idle scratch, files in / written over an hour after the container started. Work only on this machine, links, mount points and anything marked live are kept; each path is checked again just before its removal.

pitboss review-form CONFIG REPOSITORY

The form a review comment there must take.

pitboss slots ACTION CONFIG ...

The worker-slot ledger, and what to start next.

pitboss analyze-red CONFIG ...

Read-only: the red runs of a workflow in a window (REPOSITORY WORKFLOW --last N --output FILE, or --since and --until) as one Markdown report: summary, causes, costs, synthesis, a page for each red run with a prompt for the judgement items, the open p0 tickets.

pitboss lint text FILE... --phrases FILE

Banned phrases: one finding per line, exit 1 on any. The shipped list is always used; --phrases adds a project’s (more than once if need be).

pitboss lint KIND FILE

The form of a PR body (pr-body), a review comment (review), a brief (brief) or an owner decision card (owner-card: it needs a How we got here section) (--head SHA, --config, --gated, --ticket FILE, --ruling URL FILE, --comments FILE): one finding per line naming its check, exit 1 on any.

pitboss lint event EVENT STATUS

The text-lint commit status of a pull request event, written as JSON to STATUS. The reusable workflow text-lint-check.yml posts it; callers copy templates/text-lint.yml.

sweep, pressure and slots first mount tracefs when it is not mounted (mount -t tracefs nodev /sys/kernel/tracing) and say so on one stderr line (tracefs: found mounted, tracefs: mounted or tracefs: NOT MOUNTED (...)); the tool makes the mount, not the environment’s setup script, which does not run after a container restart. Stdout is unchanged.

CONFIG is a path, or a name looked up as .claude/pitboss/<name>.toml in the current directory or a parent. doc/example.toml lists every key.

The sweep skill

The repository is also a Claude Code plugin marketplace with one plugin, pitboss, whose sweep skill says when to run pitboss and what to do about every line. A project enables it in its .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "pitboss": {"source": {"source": "github", "repo": "dev-skill-up/pitboss"}}
  },
  "enabledPlugins": {"pitboss@pitboss": true}
}

skill-zips/sweep.zip is the same skill for upload to claude.ai.

Development

pitboss nox is a worker’s local check (the tests of one Python version, the skills session, lint and mypy, stopping at the first failure; the rest is CI’s). nox runs every check: tests (100% branch coverage), lint (black and stolid), mypy, docs, skills (the skill’s files, the markers against the references, and skill-zips/), dry_release. The design, and how each value specific to one project became configuration, is in doc/design.rst.

Metadata

Release files for pitboss 2026.11.4.69962

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pitboss 2026.11.4.69962
File Size Uploaded Provenance Actions
pitboss-2026.11.4.69962.tar.gz 397.8 kB With provenance Details for pitboss-2026.11.4.69962.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pitboss 2026.11.4.69962
File Interpreter ABI Platform Actions
pitboss-2026.11.4.69962-py3-none-any.whl Python 3 none any Details for pitboss-2026.11.4.69962-py3-none-any.whl

Total release size: 908.3 kB

Release files / pitboss-2026.11.4.69962.tar.gz

Download URL pitboss-2026.11.4.69962.tar.gz
Size 397.8 kB
Tags Source
SHA-256 checksum
How to use checksums
fb6d0a423ee244e01826a8b1cc65f741f13a333a060d5d6c5d9632e06270b09e
BLAKE2b-256 checksum
How to use checksums
168ea34490378f7a1152ab31931713b1f88c4a40df25a52a75070f57fb280a3c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

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 Nov 4, 2026.

Transparency log

Release files / pitboss-2026.11.4.69962-py3-none-any.whl

Download URL pitboss-2026.11.4.69962-py3-none-any.whl
Size 510.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f6db42e949140497b4c1a0affe3e954d471d6c14b788960c6ea0b236e1186c8b
BLAKE2b-256 checksum
How to use checksums
53f7e8a43e92a0f305ac1a90f86c0ff59c72320dfba79d1a00d42017a80f3f88
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

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 Nov 4, 2026.

Transparency log

Security for pitboss 2026.11.4.69962

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

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pitboss-2026.11.4.69962.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 Nov 4, 2026.

Transparency log

A 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.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page