Busytok

简体中文 | 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.

Why task-level routing?

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.

Capabilities

• Explicit provider/model binding sourced from the live catalog
• Persistent logical subagent identities for role-oriented workflows
• create, reuse, and fail reuse policies with no silent rebinding
• Synchronous --wait completion 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

Quick start (macOS)

1. Install the app

Download the latest universal DMG from Releases, open it, and drag Busytok.app to /Applications. Apple Silicon and Intel are both supported.

2. Check service and catalog readiness

Start the app, then verify that the local service is ready and inspect the enabled provider/model catalog:

busytok status
busytok models --json

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

3. Delegate and wait

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.

Install the agent integration

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 Offloading skill (subagent-offloading) from https://github.com/BalianWang/busytok, verify busytok status is ready and busytok models --json contains 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 --yes

For 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@busytok

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

Example: delegate a code review

After installing the integration, tell Codex or Claude Code explicitly when a task should run through Busytok:

Use the Busytok: Subagent Offloading skill (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.

Asynchronous delegation

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 json

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

Core concepts

Provider/model bindings

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.

Logical subagents and reuse policies

--subagent is a stable, role-oriented identity. Use:

• --reuse-policy create to create a new routing identity
• --reuse-policy reuse to intentionally use the existing binding
• --reuse-policy fail to 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.

Task lifecycle

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.

Product boundaries

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.

Local desktop context

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.

Documentation

Workspace and verification

• apps/gui: React + Tauri desktop application
• apps/gui/src-tauri: Tauri Rust host crate and bundle configuration
• apps/service: Rust background service
• apps/cli: Rust administrative CLI
• crates/busytok-*: Rust workspace crates

Run the local acceptance gate before a pull request:

./scripts/verify_acceptance.sh

For a release rehearsal on macOS:

DEVELOPER_ID_APPLICATION="Developer ID Application: ..." ./scripts/verify_release.sh

The naming check is:

bash scripts/check-busytok-naming.sh

Stability contract

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

Contributing

See CONTRIBUTING.md for the toolchain, branch model, and required CI checks. Pull requests target main and should use Conventional Commit titles.

Security

See SECURITY.md. Report vulnerabilities through GitHub Private Vulnerability Reporting; do not open a public issue for a security report.

License

Apache-2.0