Build an AI coding agent that works on your own machine

Why build your own instead of using one as-is

Every codebase has its rules: run these tests, keep diffs small, update the docs, write commits this way. A general coding agent learns them again each session. A coding agent of your own carries them in its standing instructions, so every job starts from them.

1. Give it its rules

{
  "name": "tally-maintainer",
  "role": "coder",
  "instructions": "You maintain the tally CLI (bash). On every job: keep the change small and focused, match the existing style, add or update a check in test.sh for what you change, run ./test.sh until it prints ok, and update README.md when behavior changes. Commit with a short message that says what changed."
}

It runs on the coder role's model unless you pin another one (model on the same call). Ours used Gemini 3.8 Flash with high thinking.

2. Give it a job

It worked on its own branch for 101 model turns (83,617 tokens, $0.68), ran the tests until they passed, and came back with one commit, skip binary files with notice to stderr, touching three files. The heart of the change:

-  # TODO: skip binary files instead of counting them
+  if [ -s "$f" ] && [ "$(file -b -L --mime-encoding -- "$f")" = "binary" ]; then
+    echo "skipping binary file: $f" >&2
+    continue
+  fi

And, as its instructions require, the checks it added to test.sh:

+printf 'bin\0data\n' > "$tmp/b.bin"
+err=$(./tally.sh "$tmp/b.bin" 2>&1 >/dev/null)
+echo "$err" | grep -q "b.bin" || { echo "FAIL: stderr should name skipped file"; exit 1; }
+out=$(./tally.sh "$tmp/a.txt" "$tmp/b.bin" 2>/dev/null)
+echo "$out" | grep -q 'b.bin' && { echo "FAIL: binary file should be skipped"; exit 1; }

3. Read it, then merge

Your AI shows you the report and the diff. When you are happy, one call merges it into your folder; Swarm never pushes on its own.

Not right? Send a correction to the same job (swarm_message_job); it continues on the same branch. Want every job checked first? Add a reviewer workflow.

What it can and cannot touch

• It runs as Swarm's own user, in a branch of your folder. Your files change only when you merge.
• By default its commands run on the machine without a sandbox and without permission prompts. install.sh sandbox on runs each project's jobs in gVisor; an environment gives a folder its own container with its toolchain.
• It never sees your API keys: secrets reach agents only inside an environment, as stand-ins that Swarm swaps for the real value on the way out.

Open source, on your own plan

Swarm is Apache 2.0 (source on GitHub). Your coding agent can run on your ChatGPT plan, your Claude plan through Claude Code, or an API key from OpenAI, Anthropic, Google, OpenRouter or Fireworks, and every job reports what it cost.