Architecture and development
crates/├── core/ swarmed-core: projects, tasks, worktrees, agents, sessions, the store; no UI├── cli/ swarmed: the command, a thin front end over the core└── app/ swarmed-app: the desktop app, a Tauri shell over the coreui/ the app's front end: React and TypeScript, built by ViteOne core, two front ends
Section titled “One core, two front ends”Everything Swarmed does is in swarmed-core. The command and the app only drive it: the app’s
commands forward to the core and add nothing (crates/app/src/commands.rs), apart from what only
the window has, such as the count on its Dock icon.
The UI reaches the app through one interface, Api (ui/src/api/client.ts). tauri.ts calls
the app; mock.ts serves sample data, so pnpm dev runs the whole UI in a browser with a
scripted agent.
Sessions
Section titled “Sessions”A session is one agent at work in a task’s worktree. Agents sit behind one trait,
AgentBackend (crates/core/src/agent/):
| Backend | Speaks to |
|---|---|
ClaudeBackend |
the installed claude, over its line-delimited JSON (stream-json) |
AcpBackend |
any agent that speaks the Agent Client Protocol |
FakeBackend |
nobody: a scripted agent for tests, and for SWARMED_FAKE_AGENT=1 |
What an agent says becomes AgentEvents. The core stores each one before publishing it on one
stream (Core::subscribe) for every session, which the front end reads. The pieces of a reply
still being written are only published, never stored: the whole reply follows them.
Events are kept as JSON in a SQLite database, swarmed.db in the data directory. Their
variants and fields are only ever added, never renamed, and schema changes are appended to
MIGRATIONS in store.rs, never edited.
What runs where
Section titled “What runs where”- Git is the
gitprogram, never a library (git.rs). GitHub is the user’s owngh. The core links no HTTP client. - Whatever Swarmed starts (hooks, stacks, agents, the status line script) gets the
PATHof the user’s shell (shellenv.rs). An app opened from the Dock would otherwise have only the system’s and miss Homebrew, Nix and version managers. - Swarmed’s own tools for agents are an MCP server named
swarmed, served by the same program started with a hiddentool-serverargument (toolserver.rs). The agent starts it; it reaches the running Swarmed over a socket in the system’s temporary folder. - Two Swarmeds can share a data directory, such as the installed app beside a development
build (
presence.rs). The first to arrive holds a lock onrun/first.lock, and only it settles the sessions an earlier run left busy, and stops on quitting the stacks it did not start.
HTML views
Section titled “HTML views”An agent can answer with HTML. Swarmed shows it in a sandboxed frame (allow-scripts only) loaded
from swarmed-view://, a scheme the app serves with a policy of its own (VIEW_POLICY in
views.rs): no requests, no forms, nothing but inline styles, scripts, and images and fonts
from data:. The app’s own policy allows frames from that scheme and nowhere else. A link
pressed in a view is shown with its address and opened only when the user says so.
Building from source
Section titled “Building from source”Needs Rust (the version in rust-version in Cargo.toml) and Node with Corepack.
corepack enable && pnpm installpnpm app # the app, in developmentpnpm dev # the UI alone in a browser, on sample datapnpm app:build # Swarmed.app, in target/release/bundle/macoscargo run -p swarmed -- --help # the commandThe app crate embeds ui/dist when it compiles, so run pnpm build once before cargo clippy
or cargo test on the whole workspace.
Checks
Section titled “Checks”CI runs these, and a pull request passes them locally first:
cargo fmt --all -- --checkcargo clippy --workspace --all-targets --all-features -- -D warningscargo test --workspace --all-featuresRUSTDOCFLAGS="-D warnings" cargo doc --no-deps --workspace --all-featurescargo deny check && cargo shear && typos && taplo fmt --checkzizmor .github && actionlint && shellcheck install.sh scripts/*.shgitleaks git --redactpnpm lint && pnpm typecheck && pnpm complexity && pnpm testCodeQL also scans every pull request and main, in each language it reads (codeql.yml).
The lint policy, which forbids unsafe and holds functions to a cognitive complexity of 15 in
Rust and TypeScript alike, is in AGENTS.md. RELEASING.md says
how a release is made.