简体中文 | English
Busytok routes delegated tasks to an explicit provider/model binding through a persistent logical subagent identity. It is local-first: the desktop app and busytok CLI coordinate task execution, queueing, and diagnostics on your machine while the existing audit dashboard remains available for local agent usage metadata.
Different tasks need different models, and a stable role should keep using the same routing decision until you intentionally change it. Busytok lets a caller choose a provider and model for a logical subagent, delegate one task, then wait, poll, cancel, or inspect the result without silently rebinding that role.
- Explicit provider/model binding sourced from the live catalog
- Persistent logical subagent identities for role-oriented workflows
create,reuse, andfailreuse policies with no silent rebinding- Synchronous
--waitcompletion or asynchronous JSON submission and polling - Per-subagent task serialization, queueing, and sidecar session reuse
- Queue reasons, cancellation, task history, and structured error diagnostics
- Local SQLite persistence and a desktop dashboard for local agent metadata
Download the latest universal DMG from Releases, open it, and drag Busytok.app to /Applications. Apple Silicon and Intel are both supported.
Start the app, then verify that the local service is ready and inspect the enabled provider/model catalog:
busytok status
busytok models --jsonConfigure at least one provider and enabled model in the GUI or with the CLI.
Use the provider_id and model_id returned by busytok models --json; do not
assume a fixed provider or catalog order.
Replace <PROVIDER_ID> and <MODEL_ID> with IDs from the live catalog:
busytok delegate \
--subagent "reviewer-001" \
--profile "pi/review-cheap" \
--bind-provider "<PROVIDER_ID>" \
--bind-model "<MODEL_ID>" \
--reuse-policy create \
--output json \
--wait \
--wait-timeout 120 \
"Review the repository's open TODOs and return the three highest-impact items."The response is machine-readable JSON on stdout. Keep stderr separate for diagnostics; do not merge the streams in automation.
Busytok ships the same Busytok: Subagent Offloading skill
(subagent-offloading) in the open Agent Skills
format, plus native Codex and
Claude Code plugin manifests. Copy this
single sentence to a coding agent to install and configure the integration:
Install Busytok's
Busytok: Subagent Offloadingskill (subagent-offloading) from https://github.com/BalianWang/busytok, verifybusytok statusis ready andbusytok models --jsoncontains an enabled model, then use it for delegated tasks; if installation, service readiness, or catalog selection is blocked, report the blocker instead of silently working locally.
The cross-agent installer is:
npx skills add BalianWang/busytok \
--skill subagent-offloading \
--agent codex --agent claude-code --yesFor native plugin installation:
# Codex: add the repository marketplace, then install the plugin.
codex plugin marketplace add BalianWang/busytok
codex plugin add busytok@busytok
# Claude Code:
claude plugin marketplace add BalianWang/busytok
claude plugin install busytok@busytokStart a new Codex/Claude Code session after installation. The skill is an
instruction layer; the installed busytok binary remains the execution and
task-lifecycle boundary. The plugin package version is independent from the
desktop app version; bump the plugin and marketplace manifest versions together
when the skill contract changes. The canonical skill file lives under
skills/subagent-offloading/; the Codex and Claude manifests both package
this same source.
After installing the integration, tell Codex or Claude Code explicitly when a task should run through Busytok:
Use the
Busytok: Subagent Offloadingskill (subagent-offloading) to perform a read-only code review of this repository. Delegate the review to a Busytok subagent, wait for the result, and report findings grouped by severity with file/line evidence and suggested fixes. Do not review locally; if delegation is blocked, report the exact blocker and stop.
This is useful for an independent review pass before merging a branch, opening a pull request, or releasing a package. The Agent handles catalog selection, explicit binding, polling, and failure diagnostics; you only need to provide the review scope and acceptance criteria.
For longer work, submit without --wait, read the returned task_id, and poll
the task until its status is terminal:
busytok delegate \
--subagent "reviewer-async-001" \
--profile "pi/review-cheap" \
--bind-provider "<PROVIDER_ID>" \
--bind-model "<MODEL_ID>" \
--reuse-policy create \
--output json \
"Review the repository's open TODOs and return the three highest-impact items."
busytok subagent task --task-id "<TASK_ID>" --output jsoncompleted is success; queued and running are still in progress; failed
and cancelled should be surfaced with their structured error or cancellation
context. See the integration guide for deterministic catalog selection, prompt channels, and cancellation flows.
Each logical subagent can be bound to a provider UUID (--bind-provider) and a
model ID (--bind-model). The live catalog from busytok models --json is the
source of truth. A one-task --model override is distinct from a persistent
binding.
--subagent is a stable, role-oriented identity. Use:
--reuse-policy createto create a new routing identity--reuse-policy reuseto intentionally use the existing binding--reuse-policy failto reject a name collision
Reusing a name never silently rebinds it. To route the role to a different provider/model, create a new logical subagent name.
The runtime serializes work for one logical subagent, queues tasks when needed, and can reuse its sidecar session. Use task polling, cancellation, and history commands to manage work after submission; structured queue reasons and errors make failures diagnosable.
Busytok is local-first and stores application data in local SQLite. Providers and models are configured by you in the GUI or CLI, and delegation is explicit. It is not a transparent proxy for all Claude/Codex traffic, does not intercept TLS, and does not manage external agent OAuth/API sessions. It does not promise cloud hosting, automatic routing of every external agent request, or a fixed provider catalog.
For imported Claude Code and Codex usage logs, the desktop app keeps
token/usage metadata rather than prompt/response bodies. Delegated task
prompts/results and prompt-palette templates are separate local app data. The
desktop UI exposes Overview, Usage, Prompt Palette, Providers, Subagents, and
Settings views.
Press Cmd+Option+K to open the optional prompt palette for saving and
reusing local prompt templates.
| Topic | Guide |
|---|---|
| Agent integration and CLI contract | Subagent delegation guide |
| Subagent testing and isolation | Subagent testing guide |
| Product design | Design · Design system |
| Releases | Release workflow |
| Development and contribution | Contributing |
| Security reporting | Security policy |
| License | Apache-2.0 |
apps/gui: React + Tauri desktop applicationapps/gui/src-tauri: Tauri Rust host crate and bundle configurationapps/service: Rust background serviceapps/cli: Rust administrative CLIcrates/busytok-*: Rust workspace crates
Run the local acceptance gate before a pull request:
./scripts/verify_acceptance.shFor a release rehearsal on macOS:
DEVELOPER_ID_APPLICATION="Developer ID Application: ..." ./scripts/verify_release.shThe naming check is:
bash scripts/check-busytok-naming.shBusytok is 0.x: real and usable, but minor releases may break. macOS
releases use the universal DMG and may auto-update; reinstall manually from
Releases when needed.
See CONTRIBUTING.md for the toolchain, branch model, and
required CI checks. Pull requests target main and should use Conventional
Commit titles.
See SECURITY.md. Report vulnerabilities through GitHub Private
Vulnerability Reporting;
do not open a public issue for a security report.