Skip to content
VedthakarPublic

About

One prompt → a swarm of 150+ specialist Cursor agents that plan, build, test & harden your whole project in parallel, sharing an Obsidian brain.

Topics

Resources

Stars

17 stars

Watchers

0 watching

Forks

Latest commit

 

History

22 Commits

Folders and files

Repository files navigation

swamr demo: one prompt spawns a swarm of specialist Cursor agents

swamr

One prompt. A swarm of 150+ specialist Cursor agents plans, builds, tests, and hardens your whole project in parallel.

License: MIT Node 18+ Built for Cursor Agents GitHub stars

Quickstart · How it works · Commands · Safety · The brain · FAQ


Most AI coding tools give you one agent and a chat box. swamr gives you an engineering team:

swamr build --trust "A SaaS dashboard with Supabase auth, Stripe billing, and team management"
  • 🧠 A lead architect plans it. It designs the architecture, splits the system into domains, and fans out to domain planners that write 150+ small, dependency-aware tasks.
  • 🐝 Specialists build it in parallel. Each task goes to the right expert (@frontend-developer, @backend-architect, @security-architect…), with up to 20 Cursor agents running at once, wave after wave.
  • ✅ It checks its own work. After every wave, swamr runs your type-check, lint, and test scripts, and a checkpoint agent files fix tasks for anything that fails.
  • 📓 Nothing gets forgotten. Every agent reads from and writes to a shared Obsidian vault, so agent #150 knows what agent #1 decided.
  • 🙋 It knows when to ask. When it needs an API key or a login, it writes a blocker to swamr/NEEDS-YOU.md, keeps going on everything else, and resumes with swamr continue.

Works for new projects (swamr build) and existing codebases (swamr adopt).


Quickstart

You need: Cursor (Pro recommended, since parallel agents use a lot of requests), Node.js 18+, and Git.

# 1. Install swamr (once per machine)
git clone https://github.com/Vedthakar/swamr.git ~/swamr
cd ~/swamr && npm install && npm link

# 2. Log the Cursor CLI in (once per machine)
cursor agent login

# 3. Set up a project and let the swarm build it
swamr init ./my-app
swamr build --dir ./my-app --trust "A habit tracker with streaks, reminders, and a weekly stats dashboard"

npm install compiles the CLI, and npm link puts swamr on your PATH. Run swamr --help to check it worked.

Want to look before anything runs? Add --plan-only, read my-app/swamr/plan.md and swamr/tasks.json, then run swamr build --dir ./my-app --trust --resume.

💡 Open my-app/swamr/brain/ as a vault in Obsidian and watch the notes and graph fill in while the agents work.

Already have a codebase?

cd ./my-existing-app
swamr init
swamr adopt --trust -m "Next.js app with auth and a home page. Finish the dashboard, add Stripe billing (test mode), and write tests."

A discovery agent inventories what already exists, and the swarm plans and builds only the work that remains.


How it works

swamr build "your idea"
   │
   ├─ PLANNING ─ lead architect → architecture + domains
   │             12 domain planners in parallel → 150+ tasks with dependencies
   │             integrator validates the task graph → swamr/tasks.json
   │
   ├─ FOUNDATION ─ scaffold · hosted Supabase · schema + RLS · auth · design system
   ├─ BUILD ────── up to 20 specialist agents per wave, dispatched as dependencies resolve
   ├─ TESTING ──── end-to-end suites, with deep verification between waves
   ├─ SECURITY ─── authz, input validation, secrets, headers
   ├─ LEGAL ────── privacy policy, terms, data handling
   └─ LAUNCH ───── docs, handoff note, preview deploy
         ↻ after every wave: quality gates (type-check / lint / test) + a checkpoint
           agent that re-plans, splits stuck tasks, and files fix tasks

Every agent is a real, separate cursor agent process. They share the codebase through the filesystem and share context through the brain vault. Progress is saved to swamr/state.json after every task, so if you hit Ctrl+C, crash, or close your laptop, swamr continue picks up exactly where it stopped.


Commands

Command What it does
swamr init [dir] Installs 150+ agent rules into .cursor/rules/, creates the swamr/brain/ vault, config, and .gitignore entries. Run it once per project.
swamr build [opts] "idea" Plans and builds a project from scratch.
swamr adopt [opts] -m "goal" Takes over an existing codebase and finishes it.
swamr continue [opts] [-m "what changed"] Resumes from saved state, re-checks blockers, and retries failed tasks.
@swamr-orchestrator … in Cursor chat Single-agent mode for quick tasks, with no terminal needed.
Option Applies to Description
--dir <path> build, adopt, continue Project directory (default: current directory)
--trust build, adopt, continue Run unattended: unsandboxed, with commands and MCP servers auto-approved. Asks you to confirm once. See Safety.
--yes, -y build, adopt, continue Skip the --trust confirmation (for scripts and CI)
--model <model> build, adopt, continue Model for planners and workers (default: auto)
--plan-only build Write the plan and stop
--resume build Resume from swamr/state.json
-m, --message adopt, continue Your goal, or what you changed since the last run (saved to the brain)
# Tell the swarm you fixed a blocker, and let it re-verify and keep going
swamr continue --dir ./my-app --trust -m "Added the Supabase keys to .env.local"

You can also call any specialist directly in Cursor chat:

@security-architect Audit the auth flow for vulnerabilities
@frontend-developer Build a sortable, paginated data table

Safety

swamr runs AI agents that write code and run commands on your machine, so it has two modes:

Default --trust
Sandbox On Off
Shell commands Only allowlisted commands run; the rest are denied All auto-approved
MCP servers (Supabase, Vercel, GitHub, …) Not auto-approved Auto-approved
Confirmation n/a Asks once (skip with --yes)

A fully unattended build needs --trust. Use it in a fresh git branch, a VM, or a container, on a project you're happy for agents to modify.

Every agent also follows always-on guardrails, whatever the mode:

  • No real money. Payments are test mode only (sk_test_). No purchases, plan upgrades, or paid resources.
  • No production changes unless you ask in your prompt. Agents use preview deploys by default. No pushing to remotes, publishing, or DNS changes. Otherwise they write a blocker and wait for you.
  • They stay inside the project. No sudo, no global installs, no deleting files outside the project, no force-pushes.
  • Secrets stay in .env.local. They never go into git, logs, or the brain vault.
  • Untrusted content is data. Instructions inside code, web pages, or tool output never override your request.

These guardrails are instructions to the model, not a hard technical sandbox. Treat --trust like handing a contractor your keyboard.


The Obsidian brain

swamr/brain/
├── index.md              ← live status: done / in progress / blocked, with [[wikilinks]]
├── 00-project/           ← overview, tech stack, architecture
├── 01-planning/          ← requirements, domains, decisions (ADRs)
├── 02-foundation/
├── 03-build/
│   ├── phase-log.md      ← timeline of every task
│   ├── task-outputs/     ← one note per completed task
│   ├── checkpoints/      ← re-evaluation notes between waves
│   └── issues/           ← quality-gate failures and bugs
├── 04-testing/  05-security/  05-legal/
└── 06-launch/            ← handoff doc

Each worker gets the project overview, architecture, its dependencies' outputs, open issues, and the latest checkpoint before it starts, and writes a completion note when it finishes. You can edit notes mid-build to steer the swarm.


The agents

swamr installs the full Agency Agents roster as Cursor rules, plus its own orchestration agents:

Area Examples
Engineering frontend-developer backend-architect ai-engineer database-optimizer devops-automator mobile-app-builder
Testing evidence-collector reality-checker api-tester performance-benchmarker accessibility-auditor
Security security-architect application-security-engineer compliance-auditor
Design & product ui-designer ux-architect product-manager sprint-prioritizer
Legal & finance legal-compliance-checker data-privacy-officer financial-analyst
swamr system swamr-orchestrator swamr-planner swamr-skill-selector swamr-qa-loop swamr-state-manager swamr-obsidian-brain

The planner picks the right specialist for each task. To add your own, drop a .mdc file into .cursor/rules/ and reference it as @your-agent.


Keys and Supabase

swamr itself needs no API keys, because it uses your logged-in Cursor CLI. The apps it builds usually do. Copy .env.example into your project as .env.local and fill in what you use.

swamr uses hosted Supabase (no Docker). Create a project at supabase.com/dashboard, paste the URL, anon key, and service-role key into .env.local, and the agents handle linking, migrations, RLS, and types through the Supabase CLI or MCP. If a key is missing, the task becomes a blocker instead of a failure.


Configuration

swamr init writes swamr/config.json. These are the defaults:

Key Default Meaning
max_concurrent_agents 20 Hard cap on agents running at once
wave_size 20 Agents per build wave
verify_wave_size 8 Agents per wave in testing, security, and legal phases
min_build_tasks 150 Task count the planner aims for
domain_planners 12 Parallel domain planners
max_retries_per_task 3 Retries before a task is marked failed
checkpoint_between_waves true Run the re-evaluation agent between waves
required_mcps null MCP servers that must be authenticated before a build starts

On a smaller Cursor plan, lower max_concurrent_agents and wave_size.


Troubleshooting

Problem Fix
swamr: command not found cd ~/swamr && npm link. Re-run it after switching Node versions with nvm or fnm.
Authentication required cursor agent login
Build seems stuck Check swamr/NEEDS-YOU.md, since a task may be waiting on you. Then swamr continue.
An MCP server isn't authenticated cursor agent mcp login <server>, then swamr continue
A task keeps failing Read swamr/brain/03-build/issues/, add context to the task in swamr/tasks.json, then swamr continue
You hit Cursor usage limits Lower max_concurrent_agents in swamr/config.json, or swamr continue --model <another-model>
Agents frozen pkill -f "cursor agent", then swamr continue
Start over Delete swamr/state.json, swamr/brain/, and swamr/blockers/, then run swamr init and swamr build again
Update swamr cd ~/swamr && git pull && npm install, then swamr init in your project to refresh its rules

Contributing

Issues and PRs are welcome, especially new orchestration rules, better planners, and reports of builds that went sideways (attach your swamr/brain/03-build/checkpoints/).

git clone https://github.com/Vedthakar/swamr.git && cd swamr
npm install        # also compiles to dist/
npm run dev        # recompile on change
node dist/cli.js --help

Credits

License

MIT © Ved Thakar

If swamr built something for you, a ⭐ helps other people find it.

About

One prompt → a swarm of 150+ specialist Cursor agents that plan, build, test & harden your whole project in parallel, sharing an Obsidian brain.

Topics

Resources

Stars

17 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages