swarm

module

v0.13.22 Latest Latest Go to latest Published: Sep 2, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/Nathandela/swarm

Links

Open Source Insights

README ¶

swarm

Every coding agent on your machine. One calm, keyboard-driven view.

Run agents in the background, see what needs you, and keep every session alive when the terminal closes or the daemon upgrades.

swarm brings Claude Code, Codex, and other coding-agent CLIs into one Agent View-style terminal dashboard. Sessions sort themselves by what they need from you and run under durable per-session supervisors, so closing the wrong tab no longer kills the work.

Inspired by Claude Code's Agent View, but agent-agnostic and open source.

Why swarm

One view for every agent. Watch supported CLIs from a single board instead of a wall of terminal tabs.
Attention comes first. Needs input, Working, Ready for review, and Completed keep the next human action obvious.
Background by default. Each session owns a real PTY through its own shim process and continues after the TUI exits.
Safe daemon upgrades. Restart or upgrade swarm while agents are running; the replacement daemon finds and reconnects to them.
Keyboard-native control. Launch, attach, rename, hand off work, and stop sessions without leaving the terminal.
Remote companion. The Android app in this repository can securely watch and control agents running on your computer.

How it works

A disposable swarm TUI reaches a central replaceable daemon, which reconnects to three independent persistent session shims

One binary plays a few clear roles:

swarm is the thin terminal client. On first run it starts swarm daemon automatically.
The daemon owns the protocol, registry, status engine, and CLI adapters.
Every agent session gets a tiny shim process that owns its PTY, VT screen grid, and transcript.
Session metadata is written to disk, allowing a replacement daemon to rebuild the registry and reconnect safely.

Clients never talk to shims directly. Everything crosses the daemon's versioned Unix-socket protocol—the same product spine used by the remote companion.

Why sessions survive

One uninterrupted session trail continues after the terminal closes and while a replacement daemon reconnects

The terminal is only a view, and the daemon is replaceable. The per-session shim is the durable process: it keeps the agent, PTY, screen state, and transcript alive. After a restart, the daemon reads each session's meta.json, verifies process identity by PID and start time, and reconnects without taking ownership away from the shim.

Install

swarm ships as a single static binary with no runtime dependencies.

# Homebrew · macOS
brew install --cask Nathandela/swarm/swarm

# Go · macOS or Linux
go install github.com/Nathandela/swarm/cmd/swarm@latest

Or download a signed archive and checksum from the releases page. See docs/install.md for platform details and upgrade notes.

swarm version

Quickstart

swarm

The daemon starts automatically and opens the session board.

Key	Action
↑ ↓	Move through sessions
⏎	Attach to the selected agent; ctrl+q returns to swarm
n	Start a session and choose its CLI and working directory
e	Rename the selected session
h	Hand work to another supported CLI
ctrl+x	Kill a live session or delete a finished one; confirm with y
esc	Close the TUI while agents keep running

Attach mode is raw passthrough: the agent's native full-screen interface remains untouched. swarm adds only a thin session header, which can be hidden. Ended sessions offer r to resume as a fresh linked session where the adapter supports it.

Status is the interface

Four ordered lights represent Needs input, Working, Ready for review, and Completed

swarm combines process, turn, and interaction signals into one actionable group:

Group	What it means
Needs input	The agent asked a question or requested permission. Always sorted first.
Working	A turn is active. The last meaningful output appears underneath.
Ready for review	The turn finished. Attach, review the diff, or send the next prompt.
Completed	The process exited or was lost. It remains until you delete it.

Structured events are preferred when a CLI exposes them—Claude Code uses configured hooks. Otherwise swarm reads the emulated screen grid and applies adapter-specific detection; it never guesses from arbitrary raw byte fragments.

The terminal board

The swarm terminal board listing coding-agent sessions grouped by status, with Needs input first

Bring existing Claude sessions into swarm

Inspect Claude Agent View background sessions that can be adopted:

swarm reattach --cli claude --all --dry-run

Transfer active sessions from Claude's background supervisor to swarm:

swarm reattach --cli claude --take-over

Add --all to include completed and stopped sessions. Interactive sessions are never imported. The operation is idempotent: swarm reuses a row with the same native Claude session ID instead of creating a duplicate.

Supervised handoff

Select a source session at an ordinary prompt or ready for review and press h. Choose the target CLI, model, and supervision mode. The source writes a context document, launches the linked child, and can monitor it with swarm watch, swarm peek, and swarm send.

swarm handoff --cli claude --model opus --supervision passive --context-file /tmp/handoff.md

Supervision modes:

passive — the daemon notifies the source when the child needs input, becomes ready for review, or completes.
manual — the source agent runs the watch/peek/send loop itself.
none — the source reports the child session ID and leaves supervision to you.

Permission requests are never approved by handoff automation; they remain explicit human decisions.

Supported agents

Agent	Status
Claude Code	Supported
Codex	Supported
agy / Antigravity CLI	Supported
OpenCode	Supported
Hermes Agent	Supported on Apple Silicon macOS and Linux

Every integration is a self-contained adapter covering detection, spawn arguments, status signals, and resume behavior. Characterization harnesses record real CLI output so adapters are tested against observed behavior rather than assumptions. See the Hermes adapter evidence for its current upstream limitations.

Android companion

The Android app pairs with a computer running swarm, displays the same session priorities, and supports encrypted remote observation and control. There is no swarm account: the phone and computer pair directly, and the relay transports encrypted envelopes it cannot read.

The application source lives under android/. Product, privacy, pairing, and self-hosted relay documentation is indexed from docs/INDEX.md.

Upgrading

The daemon keeps running when the binary on disk changes. After an upgrade, move it to the new build with:

swarm daemon restart

Running sessions survive and reconnect by design. See docs/install.md for the complete upgrade path.

Project status

Public and released—latest v0.13.8. Building requires Go 1.25 or newer.

The daemon, per-session shim supervision, TUI, VT emulator, status engine, worktree isolation, production CLI adapters, inter-session handoff, and Android remote-control foundation are implemented and covered by verification evidence under docs/verification/.

Known limitation: sessions make progress only while the host computer is awake. Sleep pauses agent processes; they resume automatically on wake with their state intact.

Documentation

Documentation index — every major document, one hop away
System specification — requirements, architecture, and scenarios
Build plan — ordered delivery plan and contracts
Architecture decisions — the decisions behind the process and protocol model
UI preview — navigable terminal design mockup
Brandbook v1 — Night Orchestra artwork, logo, icon, palette, and README asset system

Build and test

go build ./...
go test ./...
go vet ./...
golangci-lint run

All gates must pass before a feature closes. Contributions follow the TDD, evidence, and ADR conventions in AGENTS.md and CLAUDE.md.

License

swarm is licensed under the MIT License. Bundled third-party components and assets remain subject to their respective license notices.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
android
gate Package gate holds the Go-side build gate for the Android client (Phase B slice S13).	Package gate holds the Go-side build gate for the Android client (Phase B slice S13).
cmd
swarm command Command swarm is the single distributed binary for the swarm system.	Command swarm is the single distributed binary for the swarm system.
swarm-char command Command swarm-char is the characterization harness (E9.3 / T-6): it drives a real agent CLI in a PTY and records a versioned fixture plus a capability matrix entry.	Command swarm-char is the characterization harness (E9.3 / T-6): it drives a real agent CLI in a PTY and records a versioned fixture plus a capability matrix entry.
swarm-char/hookprobe command Command hookprobe is a TEST-ONLY stand-in for a real agent CLI's hook.	Command hookprobe is a TEST-ONLY stand-in for a real agent CLI's hook.
swarm-fake-agent command Command swarm-fake-agent is a scripted stand-in for a real agent CLI, driven by internal/fakeagent.	Command swarm-fake-agent is a scripted stand-in for a real agent CLI, driven by internal/fakeagent.
swarm-fake-codex command Command swarm-fake-codex is a stand-in for the real `codex` binary IN ITS TWO MODES, so a test can drive the whole Wave R7 topology -- daemon -> shim -> app-server -> agent -- without a real ChatGPT account and without spending the owner's money (hard rule 10).	Command swarm-fake-codex is a stand-in for the real `codex` binary IN ITS TWO MODES, so a test can drive the whole Wave R7 topology -- daemon -> shim -> app-server -> agent -- without a real ChatGPT account and without spending the owner's money (hard rule 10).
swarm-publish command Command swarm-publish uploads an Android App Bundle to Google Play and promotes it to a track, replacing the manual Console upload.	Command swarm-publish uploads an Android App Bundle to Google Play and promotes it to a track, replacing the manual Console upload.
swarm-pushgw command Command swarm-pushgw boots the Swarm push gateway (docs/specifications/push-gateway-api.md, ADR-015).	Command swarm-pushgw boots the Swarm push gateway (docs/specifications/push-gateway-api.md, ADR-015).
swarm-relay command Command swarm-relay boots the untrusted rendezvous/mailbox/push relay from a single config file (R-REL.9).	Command swarm-relay boots the untrusted rendezvous/mailbox/push relay from a single config file (R-REL.9).
swarm-remote command Package main's config assembler for the gateway binary (slice G1): resolveGatewayParams reads the provisioned state (machine identity, relay.json, the paired-device registry) and returns everything remotegw.Service needs except the dialed relay Mailbox (that dial happens in slice G2).	Package main's config assembler for the gateway binary (slice G1): resolveGatewayParams reads the provisioned state (machine identity, relay.json, the paired-device registry) and returns everything remotegw.Service needs except the dialed relay Mailbox (that dial happens in slice G2).
internal
adapter Package adapter is the FROZEN anti-corruption boundary (Epic 9, T-1/T-5/T-6) between swarm's core (daemon/shim/wire/TUI) and the concrete agent CLIs it drives.	Package adapter is the FROZEN anti-corruption boundary (Epic 9, T-1/T-5/T-6) between swarm's core (daemon/shim/wire/TUI) and the concrete agent CLIs it drives.
adapter/agy Package agy is the Antigravity CLI (agy) adapter (v1.1 CLI duo, issue agents-tracker-5gv, plan .claude/tmp/cli-duo-implementation-plan.md Phase D): a stateless, goroutine-safe strategy object over the `agy` CLI.	Package agy is the Antigravity CLI (agy) adapter (v1.1 CLI duo, issue agents-tracker-5gv, plan .claude/tmp/cli-duo-implementation-plan.md Phase D): a stateless, goroutine-safe strategy object over the `agy` CLI.
adapter/claude Package claude is the Claude Code adapter (Epic 11, E11.2/E11.6/E11.8): a stateless, goroutine-safe strategy object over the `claude` CLI.	Package claude is the Claude Code adapter (Epic 11, E11.2/E11.6/E11.8): a stateless, goroutine-safe strategy object over the `claude` CLI.
adapter/codex Package codex is the Codex adapter (Epic 11, E11.4/E11.6/E11.8): a stateless, goroutine-safe strategy object over the `codex` CLI.	Package codex is the Codex adapter (Epic 11, E11.4/E11.6/E11.8): a stateless, goroutine-safe strategy object over the `codex` CLI.
adapter/detect Package detect is the host-I/O side of adapter detection (E9.1 / E9.2).	Package detect is the host-I/O side of adapter detection (E9.1 / E9.2).
adapter/fixtureio Package fixtureio is the DISK side of the fixture corpus (E9.2 / E9.4).	Package fixtureio is the DISK side of the fixture corpus (E9.2 / E9.4).
adapter/hermes Package hermes implements Swarm's pure adapter strategy for the NousResearch Hermes Agent classic CLI.	Package hermes implements Swarm's pure adapter strategy for the NousResearch Hermes Agent classic CLI.
adapter/opencode Package opencode is the opencode adapter (Phase E, R-E1..R-E8): a stateless, goroutine-safe strategy object over the `opencode` CLI.	Package opencode is the opencode adapter (Phase E, R-E1..R-E8): a stateless, goroutine-safe strategy object over the `opencode` CLI.
adapter/refadapter Package refadapter is the fixture-only REFERENCE ADAPTER (E9.5 / T-5).	Package refadapter is the fixture-only REFERENCE ADAPTER (E9.5 / T-5).
adapter/registry Package registry is the Epic 11 adapter registry: the single table mapping a stable agent name ("agy" / "claude" / "codex" / "hermes" / "opencode" / "reference") to the constructor that builds that adapter.Adapter.	Package registry is the Epic 11 adapter registry: the single table mapping a stable agent name ("agy" / "claude" / "codex" / "hermes" / "opencode" / "reference") to the constructor that builds that adapter.Adapter.
appserver Package appserver is the DAEMON-OWNED JSON-RPC client for `codex app-server --listen unix://PATH` (Wave R7, Mirror M4.2/M4.3; ADR-013 §R7.2d).	Package appserver is the DAEMON-OWNED JSON-RPC client for `codex app-server --listen unix://PATH` (Wave R7, Mirror M4.2/M4.3; ADR-013 §R7.2d).
attach Package attach is the Epic 8 PART A raw attach passthrough (E8.1-E8.5): the client-side loop that puts the controlling terminal in raw mode, paints the one snapshot (S10), then streams live frames straight to the terminal while forwarding keystrokes and resizes to the session — and ALWAYS gives the terminal back (on detach, session end, panic, and SIGINT/SIGTERM/SIGHUP).	Package attach is the Epic 8 PART A raw attach passthrough (E8.1-E8.5): the client-side loop that puts the controlling terminal in raw mode, paints the one snapshot (S10), then streams live frames straight to the terminal while forwarding keystrokes and resizes to the session — and ALWAYS gives the terminal back (on detach, session end, panic, and SIGINT/SIGTERM/SIGHUP).
contextguard Package contextguard contains the provider-independent, side-effect-free policy for ContextGuard auto-compaction.	Package contextguard contains the provider-independent, side-effect-free policy for ContextGuard auto-compaction.
converge Package converge decides, and then performs, `swarm daemon restart --unattended`: the nightly step that moves the RUNNING daemon and gateway onto the binary Homebrew has already installed (docs/specifications/auto-upgrade-plan.md revision 5, section 3, layer L2).	Package converge decides, and then performs, `swarm daemon restart --unattended`: the nightly step that moves the RUNNING daemon and gateway onto the binary Homebrew has already installed (docs/specifications/auto-upgrade-plan.md revision 5, section 3, layer L2).
daemon Package daemon is the Epic 5 daemon core: the lifecycle authority that can die (kill -9) and come back without losing any agent (S1).	Package daemon is the Epic 5 daemon core: the lifecycle authority that can die (kill -9) and come back without losing any agent (S1).
design PB-TOK-7: the colours this product COMPUTES rather than declares.	PB-TOK-7: the colours this product COMPUTES rather than declares.
engine Package engine is the Epic 10 status-detection engine: the single, CLI-agnostic authority that turns raw session signals into a session's authenticated, fresh, never-confidently-wrong status.	Package engine is the Epic 10 status-detection engine: the single, CLI-agnostic authority that turns raw session signals into a session's authenticated, fresh, never-confidently-wrong status.
fakeagent
hookclient Package hookclient is the Epic 10 hook transport (E10.1, G4): the thin poster that `swarm hook <event>` uses to send an authenticated status callback to the daemon socket, plus the daemon-side Decode that reverses it.	Package hookclient is the Epic 10 hook transport (E10.1, G4): the thin poster that `swarm hook <event>` uses to send an authenticated status callback to the daemon socket, plus the daemon-side Decode that reverses it.
idempotency Package idempotency is the daemon's two-phase durable idempotency store (ADR-007 D6, plan R-IDP, amendment D.0-A3): a crash-safe `prepared -> executing -> completed/failed` request record keyed by operation_id, fsync'd BEFORE the side effect, so a duplicate request replays the cached outcome and executes nothing, and a crash between the side effect and the commit never double-executes.	Package idempotency is the daemon's two-phase durable idempotency store (ADR-007 D6, plan R-IDP, amendment D.0-A3): a crash-safe `prepared -> executing -> completed/failed` request record keyed by operation_id, fsync'd BEFORE the side effect, so a duplicate request replays the cached outcome and executes nothing, and a crash between the side effect and the commit never double-executes.
journal Package journal is the daemon-owned durable event journal (ADR-007 D6, plan R-JRN): a single daemon-wide append-only log of versioned records (schema_version, monotonic cursor, ts, session_id, type, payload) under <stateDir>/journal/, written at the daemon's saveMetaLocked choke point (A7).	Package journal is the daemon-owned durable event journal (ADR-007 D6, plan R-JRN): a single daemon-wide append-only log of versioned records (schema_version, monotonic cursor, ts, session_id, type, payload) under <stateDir>/journal/, written at the daemon's saveMetaLocked choke point (A7).
persist Package persist is the durable source of truth for session state (ADR-003): one meta.json per session under <root>/<id>/, written atomically so a crash mid-write is observed as old-or-new and never torn, and so a single corrupt session file never prevents scanning the rest.	Package persist is the durable source of truth for session state (ADR-003): one meta.json per session under <root>/<id>/, written atomically so a crash mid-write is observed as old-or-new and never torn, and so a single corrupt session file never prevents scanning the rest.
phonecore Package phonecore is the gomobile-ready phone-side client logic for remote control (R-PHC): pairing, transport, command signing, and consuming the daemon journal -- all in Go, tested against itself on the build machine (ADR-007 D12).	Package phonecore is the gomobile-ready phone-side client logic for remote control (R-PHC): pairing, transport, command signing, and consuming the daemon journal -- all in Go, tested against itself on the build machine (ADR-007 D12).
phonesim Package phonesim is a simulated phone that drives the REAL phonecore over a REAL relay, with no mobile app in the loop.	Package phonesim is a simulated phone that drives the REAL phonecore over a REAL relay, with no mobile app in the loop.
play Package play uploads an Android App Bundle to Google Play through the Publishing API v3 (edits -> upload -> track -> commit), using only the standard library.	Package play uploads an Android App Bundle to Google Play through the Publishing API v3 (edits -> upload -> track -> commit), using only the standard library.
procstart Package procstart is the process-creation-time identity token shared by the daemon (which matches a shim by (pid, start-time), S3/D-4) and the shim (which records the same pair for its backend so a RESTARTED daemon can tell a live app-server from an unrelated process that inherited a recycled pid, ADR-013 §R7.2c).	Package procstart is the process-creation-time identity token shared by the daemon (which matches a shim by (pid, start-time), S3/D-4) and the shim (which records the same pair for its backend so a RESTARTED daemon can tell a live app-server from an unrelated process that inherited a recycled pid, ADR-013 §R7.2c).
protocol Package protocol is the Epic 6 client<->daemon control surface (ADR-002): a versioned, capability-negotiated RPC (JSON control ops in wire.TControl frames) plus a data plane (wire.TDataIn/TDataOut/TSnapshot binary frames), layered over the shared G1 frame envelope (internal/wire).	Package protocol is the Epic 6 client<->daemon control surface (ADR-002): a versioned, capability-negotiated RPC (JSON control ops in wire.TControl frames) plus a data plane (wire.TDataIn/TDataOut/TSnapshot binary frames), layered over the shared G1 frame envelope (internal/wire).