Skip to content
atretyak1985Public

About

Local control plane for Claude Code: see every session, approve permission prompts from one queue, delegate tasks to headless agents in git worktrees — plus a plugin marketplace that ships one agent framework to every project.

Topics

Resources

Contributing

Security policy

Stars

8 stars

Watchers

2 watching

Forks

Repository files navigation

Swarmery

Swarmery

Run your Claude Code agents like a fleet — not like a pile of terminal tabs.

English · Українська

A local-first control plane for Claude Code sessions: plan the work through an interview, run it in isolated worktrees, answer every waiting agent from one queue, and see what it cost. One Go binary, no cloud, no account — plus a versioned plugin marketplace so your agents live in one place and every project pulls them with /plugin update.

Website · Features · Videos · Plugins · Get started · Docs · Blog · X @SwarmeryDev

Framework: Apache-2.0 Control plane: PolyForm NC Marketplace CI Control plane CI Local only Go React

Swarmery dashboard loop: every session live, the Inbox of decisions waiting on you, a plan phased and handed off, and the cost before the bill

Every session. Every decision. Every plan. Every dollar. — the 75-second tour and six feature episodes play on the website.

Quick start

curl -fsSL https://raw.githubusercontent.com/atretyak1985/swarmery/main/scripts/install.sh | bash
swarmery serve                            # listens on :7777
curl -s http://localhost:7777/api/health  # → {"status":"ok",…}
open http://localhost:7777

Sessions you have already run show up immediately — the daemon backfills from the JSONL transcripts Claude Code already writes under ~/.claude/projects/. Nothing to instrument, nothing leaves the machine. Prefer to read what you run (a piped script executes whatever the server returns):

url=https://raw.githubusercontent.com/atretyak1985/swarmery/main/scripts/install.sh
curl -fsSL "$url" -o install.sh && less install.sh && bash install.sh

Then set up a project — one command writes its .claude/ config.

What it does

  • See everything — every session across every project, live: tool calls, diffs, cost, sub-agents, errors.
  • Stop being the bottleneck — approve or deny permission prompts from one Inbox; turn a recurring prompt into an auto-approve rule; an agent clears the part that never needed you.
  • Delegate, don't babysit — run a phase, or the whole plan, from Plans; a headless agent executes it in its own git worktree, ticks the acceptance criteria as it goes, and a verifier grades the result.
  • Improve the system, not the prompt — per-agent scorecards, a rule-based advisor with evidence, lessons drawn from runs that missed their forecast, and agent-rewrite proposals you review as a diff.
  • Ship agents once — a real Claude Code plugin marketplace: core + opt-in domain packs, semver'd, adopted with /plugin update.

Each place below has its own page and episode on the website; the full place-by-place tour is docs/TOUR.md. Screenshots use fictional projects (TrailMap, Ledgerly API).

Planning — episode 1

Describe what you want in prose. A planner interviews you one question at a time while the plan rebuilds beside it, then lands as phase documents with acceptance criteria, forecasts and dependencies. Run one phase or the whole graph; a phase that lands far from its forecast gets a proposed fix you review as a diff.

The planner interviews you: options with pros, cons and a recommended pick
The planner interviews you: options with pros, cons and a recommended pick
The plan lands as docs: goal, decisions from the interview, phases and dependencies
The plan lands as docs: goal, decisions from the interview, phases and dependencies

Inbox — episode 2

Permission prompts, agent questions, lesson candidates, advisor findings, agent-change proposals and classifier checks — one queue worked from the keyboard (j/k, e, x, s). A triage agent labels and closes what it can and leaves a suggestion on the rest; approvals, agent changes and alerts always wait for you.

Every decision that waits on you, in one queue
Every decision that waits on you, in one queue
Agent questions as real choices, not a yes or no
Agent questions as real choices, not a yes or no

Health — episode 3

One date range reduced to one sentence about the fleet and the agents that moved it. Scorecards against the previous window, the friction you can remove today — denied tools, repeated errors, time agents waited on you — and an advisor whose every recommendation carries its evidence. Cost and tokens pivot by project, model or agent.

One sentence about the fleet, and friction you can remove today
One sentence about the fleet, and friction you can remove today
Advisor recommendations with evidence, and agent proposals
Advisor recommendations with evidence, and agent proposals

Sessions — episode 4

Every session the daemon indexes, newest first, with a now: line that says what the agent is doing this second and a chip that tells working from stuck. Open one as Chat, Timeline and Diffs, reply from the dashboard, and read the rail of models, call tree, files changed and cost.

One session: status, cost, chat and the side panel
One session: status, cost, chat and the side panel
Diffs: every file changed, changes outside the plan flagged
Diffs: every file changed, changes outside the plan flagged

Learning — episode 5

A run that lands far from its forecast becomes a lesson candidate with the evidence attached; nothing becomes active without your accept, and active lessons are re-measured and retired when they stop earning their place. A local classifier watches until its answers match yours, and forecast honesty shows who over-promises.

Lesson candidates with cause and evidence, and a retirement proposal
Lesson candidates with cause and evidence, and a retirement proposal
The local classifier and how often it matches you
The local classifier and how often it matches you

Knowledge — episode 6

What one project knows about itself: its instructions, auto-memory and Serena notes in one editor with a conflict guard and a stale-fact lint, and the architecture map embedded with a staleness badge and a one-click rebuild — plus the Serena and Graphify dashboards when their packs are enabled.

Memory: project instructions, auto-memory and Serena notes in one editor
Memory: project instructions, auto-memory and Serena notes in one editor
Architecture map with a flow traced step by step
Architecture map with a flow traced step by step

Why

You open five Claude Code sessions across three repos. One is waiting on a permission prompt you never saw. One burned $20 re-running the same failing test. One finished an hour ago. You find out by cycling through terminal tabs.

Swarmery gives that fleet a single window — and then closes the loop.


Set up a project

The installer downloads the release binary for your platform (macOS and Linux, amd64 and arm64), verifies it against SHA256SUMS, and drops it in ~/.local/bin (SWARMERY_INSTALL_DIR to change that, SWARMERY_VERSION to pin a release). Prebuilt binaries are on the Releases page; building from source is under Working on swarmery itself.

swarmery install registers a launchd service (macOS) or a systemd --user unit (Linux) so the daemon starts with your machine. Re-run it after each release install: the service and the project hooks run the copy it keeps under ~/.swarmery/bin, not the one the installer just replaced (details).

The claude CLI is what swarmery watches — install it separately if you have not already.

1 — Onboard a project

From any repo, one idempotent command writes its .claude/ config and carves a workspace namespace:

cd /path/to/your/project
swarmery onboard <project-slug> [pack ...]
#   packs: web-pack | iot-pack | uav-pack | infra-pack | lsp-pack
#          claude-eng-pack | graphify-pack | graft-pack | architecture-pack
#          jira-pack | accounts-pack | design-pack | review-pack

Then open a fresh Claude Code session, accept the swarmery marketplace trust prompt, and the project is live in the dashboard. (scripts/init.sh is the pure-bash twin of this command.)

Work artifacts — plans, task dirs, retrospectives — land under $HOME/swarmery-workspace by default; point it anywhere with SWARMERY_WORKSPACE_ROOT (daemon) / AGENT_WORKSPACE_ROOT (plugins).

Tip

Ignore .serena/ and .swarmery/ machine-wide, not per project. .serena/ (Serena MCP language-server state, lsp-pack) and .swarmery/ (this repo's own plan-doc lending into a phase-run worktree — internal/worktree/plandoc.go — torn down with the worktree, never meant to survive) can both land inside any onboarded project's tree, not just the one you first notice it in. Neither is gitignored by default, so a broad git add -A — or a headless run's own commit — can sweep one in for real; it has happened. Add both to your global git ignore instead of each project's own tracked .gitignore:

**/.serena/
**/.swarmery/

Git reads ~/.config/git/ignore by default with no core.excludesfile config needed.

2 — Route permission prompts to the dashboard (optional)

swarmery hooks install       # installs the PreToolUse / Stop hook shim

Now every permission request and AskUserQuestion appears in the dashboard's Inbox with the full context, wherever you are. The shim is fail-open: if the daemon is down it exits silently and Claude Code prompts you in the terminal as usual.

Enable the in-dashboard “+ new project” button

Writing .claude/ into an arbitrary path is opt-in, so the onboarding endpoint stays disabled until you allow-list the parent directories it may write under:

SWARMERY_ONBOARD_ROOTS="$HOME/projects" ./tools/swarmery/swarmery serve
# persist it into the launchd service (macOS):
./tools/swarmery/swarmery install --onboard-roots "$HOME/projects"

Without it the button (and POST /api/projects/onboard) return 403 onboarding is disabled. The CLI swarmery onboard always works.


A place-by-place tour of the dashboard — Today, Inbox, Needs you, Sessions, Plans, Health, Learning, Knowledge, Docs, System, Settings — lives in docs/TOUR.md; the website has a page and an episode per feature.


How the loop closes

flowchart LR
    CC["Claude Code session"] -->|JSONL transcript| ING[Ingest]
    CC -->|PreToolUse hook| APPR[Inbox approvals]
    ING --> DB[(local SQLite)]
    APPR --> DB
    DB --> UI["Dashboard :7777"]
    UI -->|approve / deny| CC
    UI -->|Run phase| DISP[Dispatcher]
    DISP -->|git worktree| AGENT["headless claude -p"]
    AGENT --> VER[Verify]
    VER --> DB
    DB --> ADV[Health advisor]
    ADV -->|agent-rewrite proposal| REVIEW["you review the diff"]
    REVIEW --> PLUGINS["plugins/** → /plugin update"]
    PLUGINS --> CC
Loading

Sessions produce evidence; evidence produces recommendations; recommendations become reviewed changes to the agents themselves; the marketplace ships those changes to every project.


The plugin marketplace

The other half of the repo. Copying an agent system between projects rots fast: substitutions pile up, files drift, every improvement has to be ported N times. Swarmery replaces that with the native Claude Code plugin mechanism — semver-versioned, namespaced (core:tech-lead), updatable (/plugin update). Projects pin a known-good version and adopt on bump.

Plugin What's inside
core The vendor-neutral framework every consumer enables: 13 judgment-style agents (tech-lead, planner, architect, implementation-agent, code-reviewer, … — see plugins/core/AGENTS.md), 37 progressively-disclosed skills, 8 commands, lifecycle/safety hooks, the statusline, and the project-aware agent-work workspace CLI.
uav-pack UAV/drone domain pack: MAVLink-style telemetry, mission planning, embedded/edge runtime.
iot-pack IoT domain pack: BLE communication, device telemetry, health-metrics processing.
web-pack Web/marketing domain pack: SEO, i18n, landing-page CRO, Figma-to-code styling.
infra-pack Infrastructure & delivery domain pack: Kubernetes/Helm, GitOps promotion, IaC, GitLab CI, cloud CI auth (GCP + AWS), Keycloak.
lsp-pack Semantic code-navigation pack: Serena LSP MCP server. Requires the serena binary (uv) on the machine.
claude-eng-pack Claude-engineering pack: skills for building/auditing Claude agent systems — agent architecture, tool/MCP design, prompt engineering, Claude Code config, context reliability.
graft-pack Context-graph pack: the graft skill plus two hooks — coverage-gated file:line locators injected into a prompt before the first grep, and a blast-radius note after every edit. Requires the graft CLI on the machine.
graphify-pack Knowledge-graph pack: the /graphify skill — repo/folder → persistent knowledge graph with query/path/affected tools and HTML/JSON/Neo4j exports. Requires the graphify CLI on the machine.
architecture-pack Repo-wide architecture map: /architecture-map generates a machine-readable JSON contract (layers, modules, file-anchored flows) + self-contained HTML viewer, freshness-stamped per commit; the swarmery dashboard serves both on its Architecture page. Also /visualize: turn a document or an explanation into one interactive, self-contained HTML explainer page.
jira-pack Issue-tracker pack: /jira-fix drives any Jira ticket end-to-end — access preflight, defect-or-change triage, reproduction or test-first evidence, delegated fix/implementation, evidence comment, QA transition. Requires an Atlassian MCP provider enabled on the machine.
accounts-pack Multi-account pack: bind a project to one of several Claude Code accounts and run every session under it — /account, a shell wrapper, an optional shell function, and a wrong-account warning. The binding is machine-local, and a binding file committed to git is ignored. Requires the swarmery CLI.
design-pack Design-handoff pack: /design-implement takes an exported design and re-expresses it in the project's stack pixel-accurately — computed-style token inventory, reuse-vs-create recon, an approval gate, and a measured pixel diff as the completion criterion.
review-pack Pull-request review pack: /pr-review reviews a GitHub PR and posts verified inline findings, or triages the reviewer comments on it — verify each against the code, fix the valid ones behind the repo's gates, rebut the rest with file:line evidence, reply in-thread. Requires the gh CLI.
swarmery-link Live-session sensor mod (function hooks): reports turn boundaries, tool calls by name and input hash, context fill, rate limits and cost to a local swarmery daemon over its token-guarded link API. The sensor never blocks or rewrites anything; silent when the daemon's token file is absent. With the opt-in control option the dashboard can stop the session's running turn and send it prompts; with the opt-in forecast option one haiku call per user turn predicts what the turn will touch and the daemon scores the forecast against the actual (paths and numbers only); with the opt-in approvals option a permission ask goes to the swarmery approvals queue first and an AskUserQuestion can be answered from the dashboard, the shim or the native dialog taking over whenever the daemon does not decide; with the opt-in swarm option it logs messages between sessions, keeps a shared registry of the files each session is editing (an advisory line when two live sessions edit one file), and lets the dashboard message a session; with the opt-in planBand option a band above the prompt shows the session's swarmery plan phase and its checklist (/phase opens it, criteria tick from the terminal) and a line under the answer flags an editing turn that looks off the running phase. Requires the swarmery daemon.
guard-pack Guard mod pack (function hooks): keeps file tools inside the project's roots, redacts secret-shaped values in tool results before Claude sees them (the raw output may still be kept in the local transcript; see the pack README's Limits), routes production-deploy shell commands to the native ask dialog, and can hide agents of packs the project has not enabled. Policy comes from .claude/project.json at runtime. Needs neither core nor the swarmery daemon.

Every pack is opt-in per project and requires core, except guard-pack, which runs on its own.

Consuming it

One command from the project root (details in docs/ONBOARDING.md):

bash <swarmery-repo>/scripts/init.sh <project-slug> [pack ...]

Or by hand, in the project's .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "swarmery": { "source": { "source": "github", "repo": "atretyak1985/swarmery" } }
  },
  "enabledPlugins": {
    "core@swarmery": true,
    "web-pack@swarmery": true
  },
  "env": { "AGENT_PROJECT": "your-project" }
}

Then drop your flavor config into .claude/project.json (schema in overlays/_schema/, reference overlay in overlays/example/). Core agents, skills, and hooks read it at runtime for repos, the main app, cloud settings, and domain terms — nothing project-specific is ever baked into a plugin (policy: docs/NEUTRALITY.md, enforced in CI by scripts/scan-flavor.sh, which must report zero hits).

Mods

swarmery-link and guard-pack are mods: plugins of function hooks (one TypeScript hooks module each) that run inside the session rather than as shell scripts, on Claude Code 2.1.287 or later. swarmery-link gives the dashboard a live line into each session — status, context fill and cost the moment they change, and with its opt-in options Stop and Send prompt, approvals, swarm messages, the plan band above the prompt and a per-turn forecast. guard-pack keeps file tools inside the project, redacts secrets from tool results and asks before a production deploy, with no daemon at all. Both are off until a project enables them; options go in your user settings, not the project's. How to enable them, the token file, every option, what claude plugin validate reports and how each degrades: docs/MODS.md.

Design rules

  • Cross-project isolation. Enabling swarmery is additive: a project's own .claude/agents/ still wins by name — that's the intended override mechanism, not a fork. Work artifacts live in a per-project namespace (AGENT_WORKSPACE_ROOT + AGENT_PROJECT), so clients never share context.
  • Framework ≠ workspace. Plans, sessions, and task dirs live in a separate private workspace repo, never here.
  • Graduation rule (docs/EXTENDING.md): components are born project-local, promoted to a domain pack when a second project needs them, then to core when every project does. Flow goes up only.
  • Explicit semver in every plugin.json; a change pushed without a bump is a change no consumer will ever pull.

Configuration

CLI reference
Command Purpose
serve Run the daemon + dashboard on :7777.
onboard / offboard / attach Bring a directory under swarmery (writes .claude/), or reverse it.
hooks install|uninstall|status Install the permission/stop hook shim into Claude Code settings.
hook <permission-request|stop> The shim itself — invoked by Claude Code, always exits 0.
console Interactive TUI: live event feed, y/n approvals, dispatcher pause.
status / service-status Live daemon snapshot / launchd service state.
install / uninstall Register or remove the launchd auto-start service (macOS).
ingest / backfill / wscan / sysscan One-shot index passes (transcripts, workspace, machine config).
backup / prune / recost Snapshot the DB (safe while serving), roll up + delete old rows, re-price sessions.
Environment variables
Variable Default Effect
SWARMERY_PORT 7777 Listen port.
SWARMERY_PROJECTS_ROOTS ~/.claude/projects Comma-separated transcript roots — one per Claude Code config dir, for machines running several subscriptions via CLAUDE_CONFIG_DIR. auto = every ~/.claude*/projects that exists. A root that is missing on this machine is logged and skipped. Each session is stamped with the account its root names (~/.claude-work → work, plain ~/.claude → the default), so the sessions list can filter by subscription and GET /api/stats/breakdown?by=account splits cost per plan.
SWARMERY_PROJECTS_ROOT (unset) Legacy singular form of the above; honored as a one-element list.
SWARMERY_WORKSPACE_ROOT ~/swarmery-workspace Private workspace repo root (plans, tasks).
SWARMERY_EXCLUDE /tmp/*,/private/tmp/* Comma-separated project paths to ignore.
SWARMERY_ONBOARD_ROOTS (empty — disabled) Allow-list of parents the dashboard may onboard under.
SWARMERY_SETTINGS_OVERLAYS ~/.swarmery/overlays.json Path to a descriptor of settings files that also apply to given project roots — for projects whose plugin set is injected at CLI precedence (claude --settings <file>) instead of being committed to the repo. See Settings overlays below. A missing or malformed file silently degrades to repo-only detection. Superseded by the estate binding (swarmery.estate in .claude/settings.local.json); retained for pre-estate setups.
SWARMERY_SYSTEM_READONLY 0 1 refuses all config and memory writes — safe for shared machines.
SWARMERY_DISPATCH on 0/false/off disables the board→agent dispatcher.
SWARMERY_AUTOVERIFY / SWARMERY_ROUTINES / SWARMERY_AUTOPROVISION on Kill-switches for verification, routines, pack auto-provisioning.
SWARMERY_MAX_CONCURRENT / SWARMERY_MAX_WORKTREES 2 / 4 Dispatcher concurrency and worktree ceiling.
SWARMERY_DISPATCH_TIMEOUT_MIN 45 Hard timeout per dispatched agent run.
SWARMERY_MICRO_PLANS on 0/false/off stops writing a one-phase plan for each dispatched card into the project's workspace.
SWARMERY_NOTIFY_URL / _EVENTS / _TELEGRAM_CHAT — Outbound webhook notifications (e.g. when an approval is waiting).
SWARMERY_CLAUDE_BIN claude Path to the Claude Code CLI the daemon spawns.

swarmery install bakes any SWARMERY_* you have exported into the launchd plist. Flags mirror most of these (--port, --bind, --exclude-projects, --workspace-root, …); run swarmery help for the full list.

Settings overlays. swarmery normally decides whether a project is managed (and which packs it runs) from that project's own .claude/settings.json. If you start Claude Code through a launcher that injects a settings file at CLI precedence — claude --settings <file> — and deliberately keep enabledPlugins out of the repo, the daemon would report managed: false for a project running the full plugin set in every session.

Declare the extra settings file and the roots it applies to, and the dashboard merges it on top of the repo's own settings (the overlay wins on a key conflict, matching real session precedence):

// ~/.swarmery/overlays.json
{
  "overlays": [
    {
      "name": "acme",                                    // label echoed as provenance
      "settingsPath": "~/launcher/orgs/acme/settings.json",
      "roots": ["~/work/acme"]                           // this project and everything under it
    }
  ]
}

~ expands to your home directory. The affected API responses gain an overlaySources field naming the overlays that contributed, so a managed: true is always traceable to where it came from. Plugin drift detection stays repo-scoped on purpose (its repair writes the repo's settings.json), so a plugin enabled only by an overlay reports status unknown rather than a green ok — nothing checked it.


Scope and limits

Stated plainly, so nothing here surprises you later:

  • Single-user, localhost-only. The daemon binds 127.0.0.1; mutating endpoints are guarded by a local-origin check. There is no authentication and no multi-user model — don't expose it.
  • Agent-level cost is not attributed. Claude Code's transcripts don't record sub-agent turns, so agents and skills carry run counts, not dollars. Session- and project-level cost is exact.
  • Planning runs are in-memory. A daemon restart forgets an in-flight planning session (the written plan survives — it's a file).
  • Playbooks are read + duplicate. Visual authoring isn't built; edit the copied file.
  • Graphify artifacts are served, not built. The daemon embeds an existing graph.html; generating it is the graphify CLI's job.
  • Auto-provisioning generates for architecture-pack only. Other packs are install-only.
  • macOS is the first-class host; Linux auto-start is supported. The daemon is portable Go. install / uninstall / service-status drive launchd on macOS and a systemd --user unit (~/.config/systemd/user/swarmery.service) on Linux; the Linux path is tested against a fake manager, not exercised in CI on a real one.

Working on swarmery itself

Prerequisites: git, Go ≥ 1.25 (older Go auto-downloads the pinned toolchain), Node ≥ 22.

git clone https://github.com/atretyak1985/swarmery.git
cd swarmery
bash scripts/install-swarmery.sh          # build the single embedded binary
./tools/swarmery/swarmery serve           # listens on :7777
cd tools/swarmery
make build          # snapshot docs → vite bundle → go:embed → single ./swarmery binary
make test           # go vet ./... && go test ./...
make dev            # go daemon + vite dev server (proxies /api to :7777)
make install        # rebuild + swap the service-managed binary and restart it (launchd on macOS, systemd --user on Linux)

Marketplace-side checks (mirrors ci.yml):

find plugins scripts -name '*.sh' -exec bash -n {} \;      # shell syntax
bash scripts/tests/protect-sensitive-files.test.sh          # hook behaviour
bash scripts/scan-flavor.sh                                 # neutrality ratchet — must be "✓ clean"

Installed plugins run from ~/.claude/plugins/cache, not from your checkout — test in-progress plugin changes with claude --plugin-dir plugins/core (repeatable per pack).

Further reading: docs/ONBOARDING.md · docs/PLUGINS.md · docs/EXTENDING.md · docs/NEUTRALITY.md · docs/WORKFLOW.md · ADR 0001 — agent defaults live upstream · control plane README · SECURITY.md


Follow the build

Website: atretyak1985.github.io/swarmery · build-in-public series on Substack · updates on X @SwarmeryDev. If Swarmery is useful to you, a ⭐ helps other people find it.

License

  • Plugins, scripts, overlays and docs — Apache-2.0 (LICENSE). Use them anywhere, including commercially.
  • The control plane (tools/swarmery/) — PolyForm Noncommercial 1.0.0 (tools/swarmery/LICENSE). Free for personal, educational and open-source use.

About

Local control plane for Claude Code: see every session, approve permission prompts from one queue, delegate tasks to headless agents in git worktrees — plus a plugin marketplace that ships one agent framework to every project.

Topics

Resources

Contributing

Security policy

Stars

8 stars

Watchers

2 watching

Forks

Releases

Packages

Used by

Contributors

Languages