■how it works · colonies · settlers · ants
a colony for every task.
colonizer takes an issue from your backlog and lands a colony on it: a microvm of its own, a fresh git worktree, and settlers to do the work. when they are done, the work comes home as a pull request and the microvm is gone.
01 / the words
six words, used lightly.
the product borrows a little from a colony of ants, and only where it helps. whenever clarity is at stake, plain words win.
the full list, with the technical name behind each word, is on the glossary page.
mothership
your machine
the colonizer app on your computer. it holds the credentials and git, runs the mesh, and publishes the work.
frontier
your backlog
the issues and repositories waiting to be settled.
colony
one task
a microvm, a git worktree and settlers, landed on one task. disposable.
settler
an agent
an agent working in a colony: claude code today, and the settlers it sends out, each with a role.
mesh
the link home
the private network between every colony and the mothership, apart from any network you already use.
return
the pull request
bringing a colony’s work home as a pull request.
02 / a colony
a colony is disposable. the mothership is not.
everything a colony needs to work lives inside it, and everything worth keeping lives at home. this is one colony’s life, from launch to pull request.
queued
launched past the parallel limit, a colony waits in line. nothing is claimed yet, and it starts on its own when a slot frees up.
land
the mothership fetches the issue, makes a git worktree on the colony’s own
colonizer/issue-<n>-<id>branch, and boots a kvm microvm for it.connect
the colony joins the private mesh, and its daemon hands the task to the first settler. without the mesh binaries it is reached on a loopback port instead.
work
settlers read, build and test, sending out more settlers when a part of the task needs one. you watch the chat and the terminal, and questions arrive as cards with concrete choices.
return
when the work is done, the microvm is removed first. then the mothership commits, pushes the colony’s branch and opens the pull request: on its own with autopilot, or when you press create pr.
resume
if a microvm stops on its own, the worktree stays. resume boots a fresh microvm on the same branch, and the settler carries on from what is there.
03 / settlers
one settler lands. it sends out more.
every colony starts with one settler: the agent module, claude code today. for parts of the task it sends out settlers of its own, and each is named for its role. settlers sent out together work as a crew: one card each in the chat, their ants on one trail.
the role comes from the claude code agent type a settler was sent out as. the types below are claude code’s own and the ones colonies commonly start; a second settler of the same role is numbered.
Scout Settler
reads and searches the code, and changes nothing
Explore
Builder Settler
does the work; the default settler
general-purpose, or no type
Surveyor Settler
plans the approach before anyone builds
Plan
Inspector Settler
reviews what changed
code-reviewer, reviewer
Warden Settler
reviews for security
security-reviewer
Tester Settler
runs the tests
test-runner, tester
Tracker Settler
tracks a bug down
debugger
Scribe Settler
writes the docs
docs-writer, doc-updater
Mender Settler
fixes a broken build
build-error-resolver
Mason Settler
refactors and tidies
refactor-cleaner
Cartographer Settler
maps out the design
architect
Pioneer Settler
everyone else, named after its type
claude, or any other type
the ant shows what its settler is doing.
one glance at a crew tells you who is working, who is thinking and who is done. a settler whose step fails stumbles over a pebble, then carries on.
working
a tool is running; it carries what the tool is
thinking
between steps, waiting on its model
writing
its report is coming in
done
the report is in
stopped
the colony stopped before it finished
04 / why ants
an ant colony is the right shape for this.
an ant colony gets large, messy work done without any single ant being large, clever or irreplaceable. coding agents are good enough now to work on their own for a long time; what they need is that shape around them.
-
IN AN ANT COLONY
many small workers
an ant colony’s work is done by a great many workers at once. none of them is big, and none is irreplaceable.
IN COLONIZER
many colonies at once
colonies run in parallel, each small and disposable: a microvm, a worktree and its settlers. up to 32 at a time, and a queue past that.
-
IN AN ANT COLONY
division of labour
workers specialise. some forage, some tend the brood, some guard the nest.
IN COLONIZER
settlers take roles
a scout reads, a builder changes, an inspector reviews, a tester runs the suite. each has its own card in the chat, and its own ant.
-
IN AN ANT COLONY
scouts go first
a scout searches alone. when it finds food, it lays a scent trail home that brings others after it.
IN COLONIZER
read before you change
a settler can send a scout to read the code before anything changes, and the settlers after it work from the scout’s report.
-
IN AN ANT COLONY
the trail is the message
ants coordinate through the trails they leave, not through a boss watching every ant.
IN COLONIZER
the event log is the trail
every step a settler takes lands in the colony’s event log. the mothership follows that trail, replays it after a reconnect, and shows it to you in plain words.
-
IN AN ANT COLONY
foragers bring it home
what a forager finds is carried back to the nest and shared there.
IN COLONIZER
the work comes home
a colony’s work returns as a pull request. the colony never publishes: the mothership commits, pushes and opens the pull request after the microvm is gone.
-
IN AN ANT COLONY
the nest is guarded
the queen and the stores stay deep inside. a forager lost outside costs the colony almost nothing.
IN COLONIZER
credentials stay home
tokens and keys stay on the mothership, and a colony only ever holds placeholders. a colony that goes rogue wrecks its own worktree, and that is all.
where the metaphor stops.
- ants never ask. settlers do: when a decision is yours, the colony stops and asks with concrete choices, and an “other…” answer.
- no ant reviews the harvest. a colony’s pull request is untrusted until the mothership has sanitized it and a person has read it.
05 / your first colony
land one on your own backlog.
linux x86_64 with kvm, or an apple silicon mac, with git and gh.
Open this page on your computer to install Colonizer.
https://colonizer.dev/colonies
curl -fsSL https://colonizer.dev/install.sh | sh
Installs on an Apple silicon Mac or a Linux x86_64 computer (not on a phone or tablet).
the words come from the vision, a colony’s life from the architecture, and the roles from the colony chat itself.