subagent-cli 0.1.3

Protocol-agnostic worker orchestration CLI

subagent-cli

Orchestrate worker agents from a parent controller, cleanly and safely.
subagent-cli gives manager agents (for example Codex or Claude Code) a practical control plane for starting workers, sending turns, handling approvals, and continuing handoffs. 🤖

The command interface is protocol-agnostic, and the current runtime backend is ACP-based (acp-stdio).

Why subagent-cli? 🚀

• Run multi-agent workflows from one place (worker start to worker continue).
• Keep control explicit with strict approval operations and structured event flow.
• Recover cleanly with runtime restart + session resume (session/load).
• Stay local-first and scriptable with a single CLI surface.

Current Scope 🧭

• Alpha (v0.1.x)
• Local single-host focused
• Python 3.11+

Features ✨

• Worker lifecycle: start, list, show, inspect, stop
• Turn operations: send, watch, wait, approve, cancel
• Handoff workflow: worker handoff and worker continue
• Strict approval flow with structured events
• ACP runtime integration (acp-stdio)

Install 📦

With uv (recommended):

uv tool install subagent-cli

From PyPI:

pip install subagent-cli

From local artifacts:

pip install dist/subagent_cli-*.whl

Quick Start ⚡

1. Bootstrap your local config.

subagent config init --scope user

2. Set launcher command/args/env in ~/.config/subagent/config.yaml.

3. Initialize a controller in your workspace.

subagent controller init --cwd .

4. Render manager guidance.

subagent prompt render --target manager

5. Hand off from here to your manager agent (Codex / Claude Code).
   Use this instruction template:

Act as the project manager for this repository.
Use subagent-cli as the control plane and progress this task by delegating to worker agents.

Required workflow:
1) Read and follow the output of `subagent prompt render --target manager`.
2) Check command help before execution (for example `subagent worker --help`, `subagent send --help`, `subagent approve --help`).
3) Break the task into small executable chunks.
4) Start/coordinate workers with subagent-cli.
5) Use send/watch/wait/approve to drive each turn.
6) Use handoff/continue when context gets large.
7) Verify results (tests or checks) before reporting completion.

Task to execute:
<your task here>

After handoff, the manager agent is expected to run the normal CLI lifecycle: worker start -> send -> watch -> approve -> handoff -> continue

For local simulation/testing without a real ACP launcher:

subagent worker start --cwd . --debug-mode

Troubleshooting 🛠️

• Ensure the runtime has the permissions required by your launcher (some launchers need outbound network access).
• Preflight launcher availability:

subagent launcher probe <launcher-name> --json

• If worker start fails with BACKEND_UNAVAILABLE, inspect runtime logs under ~/.local/share/subagent/runtimes/ (or $SUBAGENT_STATE_DIR/runtimes/ when overridden).
• For cut-down local testing without backend connectivity:

subagent worker start --cwd . --debug-mode

Configuration ⚙️

• Resolution order: --config > SUBAGENT_CONFIG > nearest <cwd-or-parent>/.subagent/config.yaml > ~/.config/subagent/config.yaml
• Generate user config: subagent config init --scope user
• Generate project config: subagent config init --scope project --cwd .
• Override config path: SUBAGENT_CONFIG=/path/to/config.yaml
• Example config: config.example.yaml

State 💾

• Default state DB: ~/.local/share/subagent/state.db
• Project hint file: <workspace>/.subagent/controller.json

Documentation 📚

• Architecture note: docs/ARCHITECTURE.md
• Examples: docs/examples
• Contributing and release process: CONTRIBUTING.md

License

MIT (LICENSE)