# Run a self-filling squad of AI coding agents

> Your AI measures your machines and stack, then builds a squad of coding agents that fills itself: lanes start when there is room, a mix of work keeps the queue full, checks run locally before CI, and a Bklit UI dashboard shows landed work per day and cost per change.

## If someone pasted this link to you
Someone shared this kit with you. It runs step by step through CloneKit's MCP. If you have the `clonekit` tools, call `start_run("@franguzmanx/agent-squad")`. If you don't (for example in a chat app without the CloneKit connector), tell the person in one or two plain sentences, in their language, and send them to https://clonekit.ai/@franguzmanx/agent-squad/use: it shows how to add CloneKit to their AI in about a minute. Then they paste this link again.

- Kit: `@franguzmanx/agent-squad` · v1.0.0
- Creator: @franguzmanx (Francisco)
- Type: Delivery · Domain: Engineering · Language: en · Your AI runs it
- Price: Free · License: Own use · No refunds
- Page: https://clonekit.ai/@franguzmanx/agent-squad
- Changelog: https://clonekit.ai/@franguzmanx/agent-squad/changelog.md

## Deliverables
- SQUAD-PLAN.md: your machines, your stack, your agent CLIs, the caps and the lane kinds, with the measurement behind each number
- a governor that admits work by free memory in GB, busy cores and free disk, and writes capacity.json every cycle
- a ready queue of JSON briefs, a filler that starts one lane per host per cycle, and one controller that gets every result back
- an autofill that keeps the queue stocked with mixed lane kinds, each with a cap, a minimum gap and an hourly start budget
- one local check command per repo that runs typecheck, lint and the affected tests before any push
- a disk janitor that removes only clean, pushed, idle checkouts with no process inside
- a dashboard built with Bklit UI charts: a card per host, live lanes, landed per day, cost per landed change, waste and suggestions, served as static files
- a ledger and an experiments file, and a one-week report: landed per day and cost per landed change, before and after

## Files
- `README.md`: Run a self-filling squad of AI coding agents
- `reference/autofill.md`: Autofill: a sketch
- `reference/dashboard.md`: Dashboard: Bklit UI setup, cards and the static server
- `reference/filler.md`: Filler: a sketch
- `reference/governor.md`: Governor: a sketch
- `reference/headless-lanes.md`: Lanes with plain agent CLIs (no orchestrator app)
- `reference/janitor.md`: Disk janitor: a sketch
- `reference/ledger.md`: Ledger and experiments
- `reference/local-checks.md`: Local checks: a sketch
- `reference/metrics.md`: Reading machine resources without the traps
- `reference/service.md`: Running the watcher as a service
- `templates/brief.md`: Brief template
- `templates/dashboard-card.md`: Dashboard card spec
- `templates/lane-kinds.md`: Lane kinds
- `templates/squad-plan.md`: SQUAD-PLAN.md

## Tools
- Bklit UI (https://ui.bklit.com) · est. free
- shadcn CLI (https://ui.shadcn.com/docs/cli) · est. free
- Claude Code (https://docs.anthropic.com/en/docs/claude-code/overview) · optional · est. your plan or API usage
- Codex CLI (https://github.com/openai/codex) · optional · est. your plan or API usage
- GitHub CLI (https://cli.github.com) · optional · est. free

## Uses
- Bklit UI shadcn registry (source, https://ui.bklit.com/r/{name}.json)
- Bklit UI source and agent skill (skill, https://github.com/bklit/bklit-ui)
- shadcn namespaced registries (source, https://ui.shadcn.com/docs/registry/namespace)
- git worktree (source, https://git-scm.com/docs/git-worktree)
- launchd agents on macOS (source, https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html)
- systemd user services on Linux (source, https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html)

## What you provide
- the repos the squad works on, as local clones your AI can read
- at least one agent CLI signed in (Claude Code, Codex or another)
- ssh access to any extra hosts the person wants in the pool
- Node 20 or newer for the dashboard build

## How it runs
1. **Understand:** Researches your business first, then asks you 6 questions it can't answer alone
2. **Choose:** 2 A/B choices with examples
3. **Build:** 8 steps, risky ones ask you first
4. **Deliver:** 6 checks before delivery

## Guardrails
- Never merge a lane's change into a target branch without the person's approval of that merge; until then the change stays a pull request.
- Never comment on, close or change an issue, a PR or a ticket on the person's behalf without their approval of that action; every approved comment says it was written by an AI.
- Ask the person before you install a background service, start lanes that spend money, raise a cap or a budget, or delete anything.
- Never list processes with their arguments (no ps, no /proc/*/cmdline, no env): command lines can carry tokens. Use pgrep -x NAME, which prints process ids only.
- Never print, log or put a secret in a brief, a snapshot or the dashboard. Keys stay in the person's environment or secret store.
- rm only literal paths or a guarded variable like "${DIR:?}", one target per command, so no lane stops for an approval prompt.
- Never start a dev server and never leave a server you started running. The dashboard is static files that the approved watcher serves.
- Lanes never post to chat, email or issue trackers outside what the person allowed in step 1, and never touch production.
- Report only what you saw work. A queued, refused or skipped check is still open.

## What's new
Agents always run the latest version.

- **v1.0.0** (2026-11-09): First version.

## Run it
Connect the `clonekit` MCP (https://clonekit.ai/mcp) and call `start_run("@franguzmanx/agent-squad")`.