pilot-workers

Dispatch bounded tasks to isolated LLM workers. Your main AI agent (Claude, Codex, or any planner) stays in control of requirements, planning, and verification — the worker only executes what it's told.

CLI command: pw9 (alias: pilot-workers).

What it does

  • Provider isolation: each model (GLM, Kimi, DeepSeek, or your own) gets its own credentials, XDG directories, logs, and session storage. No cross-contamination.
  • Fixed routing: provider, model, and endpoint are locked per YAML config. Tasks cannot override them.
  • Security by default: API keys never appear in CLI args, environment variables, task contracts, or logs. Output is auto-redacted.
  • Five modes: code (edit), explore (read-only), test (run tests), review (read-only audit), resume (continue a prior code session).
  • Auto-fanout review/test: pw9 review and pw9 test automatically split work by configurable axes/layers and dispatch in parallel.
  • Pluggable runners: the runner adapter layer (Runner ABC) abstracts engine-specific details. Currently ships with OpenCode.
  • Observable: two-line JSON contract (started + structured verdict) for AI planners; human-readable latest.log for tail -f.

Install

pip install pilot-workers

Quick Start

# 1. Install the worker runtime
pw9 install runner opencode

# 2. Configure a provider's API key
pw9 key glm

# 3. Check status
pw9 status

# 4. Run a task (dispatch = run + a structured verdict and a report.md)
pw9 template code > /tmp/task.md   # fill it in first
pw9 dispatch --provider glm --mode code --workdir /path/to/project --task-file /tmp/task.md

# 5. Auto-fanout code review (5 axes in parallel)
pw9 review --provider glm --workdir .

# 6. Auto-fanout test execution
pw9 test --provider glm --workdir .

Adding a Provider

Drop a YAML file in data/providers/ with the required fields (key, provider_id, model_id, base_url, display_name, context_tokens, output_tokens), then pw9 key <key>.

Key Commands

Command Description
pw9 key <provider> Configure API key
pw9 status [--json] Provider credentials + runner state
pw9 dispatch --provider <key> --mode <mode> --workdir <dir> --task-file <file> Dispatch a single task; stdout = two JSON lines (started + verdict), plus a report.md on disk
pw9 run ... The inner primitive dispatch wraps — streams events, writes the log, but extracts no result
pw9 spec --provider <key> --workdir <dir> --requirement "..." Explore, then draft a code task contract to edit
pw9 discuss --provider <a>,<b> --workdir <dir> --question "..." One question, independent positions, shows where they split
pw9 runs / pw9 usage Dispatch history and token totals
pw9 fanout --workdir <dir> --job <provider:mode:file> ... Dispatch several jobs concurrently
pw9 review --provider <key> --workdir <dir> Auto-fanout code review by axes
pw9 test --provider <key> --workdir <dir> Auto-fanout test execution by layers
pw9 review show/add/edit/remove Manage review axes
pw9 test show/add/edit/remove Manage test layers
pw9 permissions add/remove/show <provider> ... Per-provider shell permission overrides
pw9 template <mode> Print the task template for a mode
pw9 install runner opencode Install the worker runtime
pw9 uninstall key <provider> Remove an API key

Development

python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

License

MIT

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.12.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for wuchengyang from gravatar.com wuchengyang

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Provides Extra

yaml dev

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pilot_workers-0.11.0.tar.gz (199.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

pilot_workers-0.11.0-py3-none-any.whl (142.9 kB view details)

Uploaded Python 3

File details

Details for the file pilot_workers-0.11.0.tar.gz.

File metadata

  • Download URL: pilot_workers-0.11.0.tar.gz
  • Upload date:
  • Size: 199.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pilot_workers-0.11.0.tar.gz
Algorithm Hash digest
SHA256 baf62695212a3fd5ba39516eb23546d5a58ffa3869e3717a00d98adb09ec8520
MD5 c6d423fd19d9332c2276cc377e476e91
BLAKE2b-256 03422c142fe4b746ba805fb1320ba36c09b9e4b69ce7e0cb198488bc09d02685

See more details on using hashes here.

Provenance

The following attestation bundles were made for pilot_workers-0.11.0.tar.gz:

Publisher: publish.yml on gWcyWoo/pilot-workers

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pilot_workers-0.11.0-py3-none-any.whl.

File metadata

  • Download URL: pilot_workers-0.11.0-py3-none-any.whl
  • Upload date:
  • Size: 142.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pilot_workers-0.11.0-py3-none-any.whl
Algorithm Hash digest
SHA256 2d129ea6ace78da9480a6816019a9c937f8a4c4544ad5d4e540e917604c8bdfc
MD5 6252d8e906478cb5d2d3b13f253e9cf2
BLAKE2b-256 1b7bd72af94c302c62be48f4c4359662502b21fe182a6eec033c6ce61ca3241a

See more details on using hashes here.

Provenance

The following attestation bundles were made for pilot_workers-0.11.0-py3-none-any.whl:

Publisher: publish.yml on gWcyWoo/pilot-workers

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page