Agent Swarm CLI

Agent Swarm CLI is a terminal app for running and testing Agency Swarm projects. It is built on the OpenCode codebase, with Agent Swarm-specific packaging, branding, auth, and TUI flows.

The main user path is Run mode: start the TUI from an Agency Swarm project, authenticate a model provider, connect to the local Agency Swarm server, and send prompts to your swarm.

Install

npm install -g agentswarm-cli
agentswarm --version

Or run it without installing:

npx @vrsen/agentswarm

Start

From an Agency Swarm project:

agentswarm .

You can also pass a project folder:

agentswarm /path/to/my-agency

On startup, the CLI can detect the project, prepare the project Python environment, start the local Agency Swarm server, and open the terminal UI.

Main TUI Flows

• /agents switches between Plan, Build, and Run.
• Build uses native OpenCode build behavior with Agent Swarm guidance.
• Plan is native OpenCode Plan mode for preparing work before Build.
• Run connects to or starts an Agency Swarm FastAPI server and sends prompts to the active swarm.
• /auth manages OpenAI and Anthropic credentials used by Agency Swarm runs.
• /connect chooses a local or external Agency Swarm server.
• /agents switches Plan, Build, Run, and the active swarm or agent from live Agency Swarm metadata.
• /models is limited in Run mode to providers that the Agency Swarm path supports.

Sharing

/share is still the upstream OpenCode share flow and currently posts to https://opncd.ai. This is intentional for now, so users can keep using upstream-compatible session links while a fork-hosted share service is not available.

Do not share sessions that contain secrets, private code, private customer data, or credentials.

Telemetry

Release builds may send privacy-safe product analytics to the official Agent Swarm PostHog project so maintainers can understand which Agent Swarm CLI and TUI features are used. Events cover app start, /auth provider setup, supported slash command usage, docs clicks, prompt submission shape, task success or failure, project initialization, agent creation, and selected add-ons. They do not include prompt text, slash command arguments, credentials, file paths, tool payloads, message content, raw model IDs, project IDs, session IDs, message IDs, source content, environment variables, raw error text, agent names, agent descriptions, generated prompts, tool inputs, or tool outputs.

Set ENABLE_TELEMETRY=0, OPEN_SWARM_TELEMETRY=0, AGENTSWARM_TELEMETRY=0, or pass --no-telemetry to disable this telemetry.

Every sent PostHog event sets $process_person_profile: false and includes safe base properties such as version (the Agent Swarm binary version), app, platform, arch, channel, and terminal when available.

Product launchers may attach an allowlisted package version as product_version and marketplace metadata as swarm_id, parent_swarm_id, and swarm_origin (original, fork, or unknown). swarm_id and parent_swarm_id must be GitHub owner/repo names, not repository URLs, git remotes, local paths, or generic slugs. Official release binaries use the embedded capture key; runtime PostHog key environment variables do not redirect production telemetry.

Supported events and properties:

• app_started: entrypoint, framework_mode, provider_id.
• agent_created: scope, mode, tool_count_bucket.
• provider_requested: provider_id, framework_mode, source, connected_before.
• provider_auth_started: provider_id, auth_method, framework_mode, source.
• provider_auth_configured: provider_id, auth_method, framework_mode, source.
• provider_auth_failed: provider_id, auth_method, framework_mode, source, step, error_bucket.
• project_initialized: source, vcs.
• ui_command_executed: docs clicks and supported slash commands; category, command (docs.open or the slash command name without /), keybind, source.
• ui_prompt_submitted: framework_mode, has_agent_parts, has_editor_selection, has_file_parts, mode, provider_id, type.
• task_succeeded: framework_mode, provider_id, mode, duration_bucket, has_agent_parts, has_file_parts.
• task_failed: framework_mode, provider_id, mode, duration_bucket, has_agent_parts, has_file_parts, error_bucket.
• integration_requested: provider_id, integration_id, source, already_configured.

Dashboard metrics are derived from those events where possible. first_run and D1/D7/D30 retention cohorts use app_started; sessions_per_user counts app_started; first_task_started uses ui_prompt_submitted with type=prompt; first_successful_task, time_to_first_success, and tasks_completed use task_succeeded; docs clicks use ui_command_executed with command=docs.open; slash command usage uses ui_command_executed with source=slash; provider_demand uses provider requested, started, configured, and failed events; project setup uses project_initialized; agent creation uses agent_created.

Deferred telemetry includes agent run internals, generated artifacts beyond safe agent creation shape, crashes, build or release failures, signup or demo funnels, book-demo flows, and Agent Swarm connect funnel metrics.

Customizing Agent Swarm CLI

This repository is useful if you want to build a custom CLI for your own Agent Swarm distribution. Keep these rules in mind:

• Keep fork-specific behavior small and easy to audit.
• Prefer reusing upstream OpenCode mechanisms over copying or rewriting them.
• Keep Agent Swarm-specific code in clearly named modules when that does not make the code worse.
• Update FORK_CHANGELOG.md when you intentionally keep behavior that differs from upstream.
• Update USER_FLOWS.md when a user-facing flow changes.
• Run the Agent Swarm-specific TUI tests before publishing your own build.

Development

Install dependencies:

bun install

Run focused tests from the package you changed:

cd packages/opencode
bun test test/cli/tui

Run type-checks before pushing:

bun typecheck

Run the contained Agent Swarm TUI e2e suite when TUI behavior changes:

cd packages/opencode
bun run test:agentswarm:e2e

Relationship To OpenCode

Agent Swarm CLI is a fork of OpenCode. OpenCode remains the upstream foundation for the TUI, session model, command system, and many developer workflows.

The fork keeps the MIT license and preserves the upstream copyright notice. Fork-specific changes are tracked in FORK_CHANGELOG.md so the project can keep merging upstream safely.

Links

• Agent Swarm CLI repository: https://github.com/VRSEN/agentswarm-cli
• Agency Swarm docs: https://agency-swarm.ai/
• Upstream OpenCode repository: https://github.com/anomalyco/opencode
• npm package: https://www.npmjs.com/package/agentswarm-cli