Build your own AI agent, step by step

What you are building

An agent that does one kind of job well, every time, without you explaining it again. Ours is todo-triager: it reads a repository, finds every TODO and FIXME, says how big each fix is and which to do first, and changes nothing. Swap in your own: a release-notes writer, a dependency checker, an invoice reader, a site checker.

You need an Ubuntu 24.04 x86-64 machine (your PC, a VPS or a cloud VM) and a model: your ChatGPT plan, your Claude plan through Claude Code, or an API key. We used a fresh Google Cloud VM and a Gemini API key.

1. Install Swarm

One line, from your own account. On our fresh VM it took 70 seconds and installed Swarm v0.1.59, listening on 127.0.0.1 only.

curl -fsSL https://swarmagent.dev/install | sudo bash

Or skip the typing: paste "Read swarmagent.dev/llms.txt and set up Swarm on this machine for me" into Claude Code, Codex or ChatGPT, and it runs the install itself.

2. Connect your AI and a model

Your AI drives Swarm through its MCP tools. In Claude Code:

claude plugin marketplace add swarm-agent/swarm
claude plugin install swarm@swarm

Then connect a model. Your AI starts the ChatGPT sign-in or the Claude Code one for you; an API key you add yourself, so it never passes through chat:

sudo bash /var/lib/swarm-headless/install.sh key google < key-file

Swarm then picks a recommended model for each role. On our machine: Gemini 3.8 Flash for the coder, finder and designer, Gemini 4 Argon for the reviewer.

3. Tell Swarm where your work is

A project is a name and your folders. Nothing in them changes; Swarm reads them and writes a project.md that every job sees.

4. Create the agent

Say what it does, in plain words. Your AI turns that into one call: a name, a role and standing instructions. The role decides what it may do: a finder reads and reports, a coder changes code on its own branch, a designer works on pages and copy, a reviewer checks other agents' work.

{
  "name": "todo-triager",
  "role": "finder",
  "instructions": "You triage TODO and FIXME comments. Find every TODO and FIXME in the repository. For each one, say where it is, what it asks for, how big the fix is (small, medium, large) and which one to do first. Change nothing. End with a short ranked list.",
  "budget": { "daily_usd": 2 }
}

Swarm answered with the new worker, active, on the finder's default model:

{"deployed": true, "worker": {"id": "worker_35fdf250…", "name": "todo-triager", "role": "finder",
  "lifecycle_state": "active", "model": {"provider": "google", "model": "gemini-3.8-flash", "thinking": "low"}}}

5. Give it a job

The job starts at once and runs on its own branch, so your folder is never touched while it works. Your AI waits on it and reads the result. Ours came back with:

An excerpt of its report, unedited:

1. tally.sh:13 (FIXME: the total line is printed even for a single file)
   Small (Fix first: bug fix addressing incorrect output behavior).
2. tally.sh:8 (TODO: skip binary files instead of counting them)
   Medium (Fix second: feature addition requiring detection mechanism and test coverage).

6. Make it run without you

• On a schedule: "Run todo-triager every Monday at 9." Your AI calls swarm_schedule_job with a cron and your timezone. See AI agents on a schedule.
• With a reviewer: "After every coder job, have a reviewer check it and send it back if it is wrong." That is a workflow; see agentic workflows.
• Changing code: give your agent the coder role and it works on its own branch; you merge what you like. See build an AI coding agent.
• Inside your app: a support chat or an assistant for your customers is a different kind of agent, with only the tools your app gives it. See an AI agent for your website.

Keeping it safe and cheap

• The budget stops the worker for the day once it reaches its limit. swarm_list_workers shows what it spent today.
• A finder only reads and reports. Only a coder (or designer) changes files, and only on its own branch until you merge.
• Keys stay out of chat: you type them into Swarm yourself, and agents see stand-ins.