clodfarm

Quick start · How it works · Multi-seat · Docs · FAQ

Your Claude Code agents keep working while you sleep, and stop before they eat your week.

clodfarm (say it out loud) is a farm of Claude Code agents running around the clock in a container. A clod
is a lump of soil, and this is where your agents grow.

• You steer it from the Claude app on your phone.
• Agents split big jobs into parallel sub-agents.
• A budget governor paces everything on your account's real 5-hour and weekly usage.

Add more boxes, or your teammates' own accounts, and they share one queue while each account keeps its own budget.

_{One farm, two seats. Gil's seat is near its 5-hour ceiling and paused; the work flows to Matan's seat. (Illustrative output.)}

01 · Install One line on any box with Docker, or one command on AWS with no open ports.

02 · Log in from anywhere clodfarm login prints a URL. Approve it on your phone and paste the code.

03 · Give it a mission clodfarm mission "...", queue tasks, or just talk to it in the Claude app.

04 · It keeps going It plans, splits, tests and merges, and paces itself on your real limits.

Why clodfarm

A while true; claude -p loop gets you an agent that forgets what it did, can't split work, can't be reached from
your phone, and runs until it hits the wall and locks you out of your own Claude. clodfarm is the missing
operations layer:

🌙 Always on	Workers restart, leases expire, crashed runs are retried, and timed-out runs continue in their own session.
📱 Steer it from your phone	claude remote-control stays up, so the farm is a session in the Claude app and at claude.ai/code.
🌱 Sub-agents that merge	clodfarm task add --parent $FARM_TASK_ID fans out. Each child works in its own git worktree, and the parent is resumed in its own session to merge the results.
🌕 Paced on real usage	Every run reports the account's actual 5-hour and weekly utilization (rate_limit_event). The governor paces the week, leaves you 20% by default, sleeps through rejections, and never touches paid overage.
👥 Many boxes, many seats	Point containers on several accounts at one table: one queue, one repo, a separate budget per account.
✅ Nothing lands untested	FARM_VERIFY_CMD runs your tests on the rebased branch, and a failing check sends the agent back to fix it.
🧭 Never runs dry	When the queue empties, a planner reads MISSION.md and the work so far, then queues the next concrete tasks.
🔔 Tells you when it matters	Notifications to ntfy, Slack or Discord for failures, a tripped circuit breaker, usage limits, and "nothing left to do".

| 🕹️ A farm you can watch | Open http://localhost:8080: every agent is a pixel Claude walking the farm, tending its task at a terminal or napping when the budget says so. Read the quest log, post quests, set the mission, and hatch new agents (each one its own Claude login) from the browser. |

The farm UI, the Claude app, the CLI and the logs all drive the same queue: use whichever is at hand.

Quick start

One container, no config, no database to run:

curl -fsSL https://raw.githubusercontent.com/matank001/clodfarm/main/scripts/install.sh | sh

It pulls the image, starts clodfarm (restarting on reboot), and opens the login: a URL you approve on any
device, then paste the code back. Then give it something to do:

docker exec clodfarm clodfarm mission "Build csv2md: a CLI that converts CSV to Markdown tables, with tests."
docker exec clodfarm clodfarm status

Or open Claude app → Code → clodfarm and just talk to it, or open the farm UI at http://localhost:8080
(see docs/ui.md): the password is printed once in docker logs clodfarm, or set FARM_UI_PASSWORD.
From the UI you can also log the farm in: tap the egg, open the Claude login link and paste the code back.

Prefer plain Docker, or Compose?

docker run -d --name clodfarm --restart unless-stopped \
  -v clodfarm_claude-home:/home/farm/.claude -v clodfarm_workspace:/workspace \
  ghcr.io/matank001/clodfarm
docker exec -it clodfarm clodfarm login

Or clone the repo and run docker compose up -d. A .env is optional: copy .env.example to change any setting.
Either way the farm's state lives in a SQLite file inside the workspace volume, so there's nothing else to run.

[!TIP]
Point it at a real repo with FARM_REPO_URL (plus a deploy key), set FARM_VERIFY_CMD="pytest -q", and write a
MISSION.md. The farm clones the repo, keeps the agents busy, and pushes main only when your tests pass.

Deploy

	What you get
Single deployment	One box, one Claude account. Everything in one container.
Multiple deployments, one farm	Several boxes on your account or teammates' own accounts: one queue and one repo, each account paced on its own budget.

You can start single and add boxes later. A new box simply joins the first one's table.

Single deployment

Any Docker host: run the one-line installer on the server (ssh myserver, then the curl … | sh above). Or
start it there and log in from your laptop with ssh -t myserver docker exec -it clodfarm clodfarm login.

AWS (about 10 minutes, one box, no inbound ports):

deploy/aws/deploy.sh up       # CloudFormation: VPC, EC2 t4g.medium, DynamoDB table, IAM role limited to that table
deploy/aws/deploy.sh login    # over SSM Session Manager: URL + code, same as above
deploy/aws/deploy.sh status   # also: logs · shell · down

You need the AWS CLI v2 and the
Session Manager plugin.
Remote Control, the Claude API and SSM all use outbound HTTPS only. See docs/deploy-aws.md.

Multiple deployments, one farm

A single box keeps its farm in a local SQLite file. To spread one farm over several boxes, the boxes share a
DynamoDB table instead (FARM_STORE=dynamodb; the AWS deploy sets it for you).

• Shared: every box pointed at that table shares one queue and one git repo.
• Per account: each box is paced on the budget of the Claude account it's logged in to (its seat). When one
  seat hits a limit, only its boxes pause.

You need:

• real DynamoDB (the AWS deploy creates it);
• a shared git repo every box can push to (--workspace-repo / FARM_REPO_URL); task branches travel through it.

# box 1 creates the farm (table "clodfarm")
deploy/aws/deploy.sh up --workspace-repo [email protected]:you/repo.git && deploy/aws/deploy.sh login

# more boxes on your account: more room to run, never extra usage
STACK=farm-2 deploy/aws/deploy.sh up --table clodfarm --workspace-repo [email protected]:you/repo.git
STACK=farm-2 deploy/aws/deploy.sh login

# a teammate's box, logged in to THEIR account: a second seat, with its own budget
STACK=farm-gil deploy/aws/deploy.sh up --table clodfarm --workspace-repo [email protected]:you/repo.git
STACK=farm-gil deploy/aws/deploy.sh login

clodfarm budget   # every seat: usage bars, its boxes, what it may run right now

• A sub-task can run on Gil's box and be merged by its parent on yours.
• A resumed parent waits a few minutes for the box that holds its conversation.

Join from any Docker host, or add work from your laptop

A Docker host joining an existing farm:

1. In .env, set FARM_STORE=dynamodb, FARM_TABLE=<table>, AWS_REGION=<region> and
   FARM_REPO_URL=<shared repo>.
2. Give the box AWS credentials for the table.
3. Run docker compose up -d && docker exec -it clodfarm clodfarm login.

Queue work from your laptop without running a worker:

pip install git+https://github.com/matank001/clodfarm
export FARM_STORE=dynamodb FARM_TABLE=clodfarm AWS_REGION=<region>   # plus AWS credentials for the table
clodfarm task add "Refactor the parser" --prompt "..." && clodfarm status

Full guide: docs/multi-seat.md.

How it works

flowchart LR
  subgraph you[You]
    app[Claude app<br/>claude.ai/code]
    cli[clodfarm CLI]
  end
  subgraph box[Each box: clodfarm run]
    rc[Remote Control keeper]
    w[Workers<br/>claude -p, one worktree each]
    plan[Planner<br/>reads MISSION.md]
    gate[Verify gate<br/>FARM_VERIFY_CMD]
  end
  subgraph ddb[The farm store: SQLite on one box, DynamoDB across boxes]
    q[(Shared queue<br/>parents, children, leases)]
    b[(Budget per seat<br/>5h + 7d utilization)]
    s[(Slots per seat)]
  end
  origin[(git origin)]
  claude[(Claude)]

  app <--> rc
  cli --> q
  w -- claim / finish --> q
  plan -- queue next tasks --> q
  w -- "task add --parent" --> q
  w -- rate_limit_event --> b
  b -- governor --> s
  w -- take a slot --> s
  w --> gate --> origin
  rc & w <--> claude

1. A worker asks the governor how many agents its seat may run right now, takes one of that seat's slots,
   claims the highest-priority task (an atomic conditional write, with a lease it keeps renewing), and starts
   claude -p --output-format stream-json in the task's own git worktree.
2. While it runs, every rate_limit_event updates that seat's budget, so all its boxes react within seconds.
3. When it ends:
   • Waiting on children: the parent stays open and is resumed in the same session when they finish.
   • A sub-task: its branch waits for the parent to merge it.
   • A top-level task: it's rebased onto main, FARM_VERIFY_CMD runs, and it fast-forwards main only if
     the check passes. Otherwise the agent is resumed with the failure output.
4. When the queue is empty and there's budget, one planner run turns MISSION.md into the next tasks, and backs
   off when there's nothing useful to do.

The budget governor, in detail

Utilization comes from Claude Code itself and covers the whole account, including your own chats, so the farm
backs off when you use Claude. Per seat:

• Weekly window: agents stop at FARM_WEEKLY_TARGET (80%). Before that, a pace line
  (target × fraction of the week elapsed + 5%) spreads the week out. Ahead of the line the governor slows down or
  stops until the line catches up; behind it, it runs at full concurrency.
• 5-hour window: never past FARM_FIVE_HOUR_CEILING (85%). The pace is loose, so bursts are fine.
• Rejected or paid overage: that seat stops until the reset time Claude reported.
• API key: no windows apply. It stops for the day at FARM_DAILY_BUDGET_USD.

It's a pure, unit-tested function: clodfarm/governor.py ·
docs/budget.md.

More: architecture · what agents are told · login options ·
security · how it's tested.

How it compares

	while loop	Single-loop runners (e.g. ralph, continuous-claude)	clodfarm
Runs unattended, survives crashes	❌	✅	✅
Parallel agents	❌	via separate instances	✅ shared queue
Sub-agent tree, parent resumes in its own session	❌	❌	✅
Paces on the real 5-hour and weekly utilization	❌	waits out limits	✅ per seat
Several boxes and accounts in one farm	❌	❌	✅
Merge only when tests pass	❌	✅ (continuous-claude)	✅
Steer it from the Claude app	❌	❌	✅ Remote Control
Cloud deploy with no open ports	❌	❌	✅

Both runners are great at what they do, and we learned from them. See related projects.

Logging in

Your login stays in the container's claude-home volume. clodfarm never reads or prints it.

	How	Good for
A. Remote login	clodfarm login: a URL on any device, then paste the code back	servers (the default)
B. Token	claude setup-token on your laptop, then CLAUDE_CODE_OAUTH_TOKEN=... in .env	headless workers, CI
C. Existing profile	mount a Linux ~/.claude (macOS keeps it in the Keychain: use A or B)	moving a box
D. API key	ANTHROPIC_API_KEY + FARM_DAILY_BUDGET_USD	teams, services, pay per token

Details and caveats: docs/auth.md.

Commands

Command
clodfarm status	seats, queue, workers, running tasks, the Remote Control link
clodfarm budget [--refresh]	every seat's usage and what the governor allows it now
clodfarm task add TITLE --prompt ... [--parent ID] [--priority 0-9]	queue work (agents use the same command)
clodfarm task list / show / cancel / retry	inspect and manage tasks
clodfarm mission [TEXT]	show or set MISSION.md, which the planner keeps the agents busy with
clodfarm events [-f]	the event log: claims, merges, checks, pauses, limits
clodfarm pause [reason] / resume	stop and restart new work on every box
clodfarm login / whoami / doctor	login and a setup check

Every command takes --json.

Configuration (all environment variables; .env.example documents every one)

Variable	Default
FARM_MAX_WORKERS	3	parallel agents per box (upper bound; the governor decides)
FARM_MODEL / FARM_EFFORT	opus / default	model and effort for every agent
FARM_WEEKLY_TARGET	0.80	agents stop at 80% of the weekly window
FARM_FIVE_HOUR_CEILING	0.85	max share of a 5-hour window
FARM_DAILY_BUDGET_USD	0	API-key mode: daily cap (0 = none)
FARM_REPO_URL	(empty)	repo to work in (required for more than one box)
FARM_VERIFY_CMD	(empty)	check that must pass before landing, e.g. pytest -q
FARM_NOTIFY_URL	(empty)	ntfy, Slack or Discord webhook
FARM_STALL_THRESHOLD	5	failed runs in a row that pause the farm
FARM_REMOTE_CONTROL	1	keep a Remote Control session up
FARM_PERMISSION_MODE	bypassPermissions	the container is the sandbox (security)
FARM_MISSION	(empty)	the mission, if you'd rather set it at start than with clodfarm mission
FARM_STORE	sqlite	dynamodb to share one farm across boxes and accounts (setting FARM_TABLE implies it)
FARM_TABLE / FARM_SEAT	clodfarm / from login	which DynamoDB farm to join / override the seat name

FAQ

Is this allowed?

clodfarm drives the official Claude Code CLI, headless mode and Remote Control as documented. On a subscription
it's meant for your own projects, on your own login. Anthropic's consumer terms say plan limits assume ordinary,
individual use, and they forbid reselling or intermediating Claude usage. So:

• don't run it as a service for others on a subscription;
• don't share logins;
• for people working together, use Team or Enterprise seats, each person on their own login;
• for commercial workloads, use an API key.

clodfarm never shares or rotates logins, and it paces every seat well under its limits. Read the current
Consumer Terms and Usage Policy
yourself; this isn't legal advice.

Will it lock me out of my own Claude?

That's what the governor is for. By default agents stop at 80% of your week and 85% of any 5-hour window, and the
numbers include your own usage, so the farm backs off when you're working.

What does it cost?

On a subscription, nothing beyond your plan. Locally or on your own server it's free: a single box needs no
database. The AWS box is roughly $25/month for a t4g.medium, plus cents of DynamoDB (an estimate; check AWS pricing).

Is it safe to give agents a shell?

They run as an unprivileged user inside the container. Mount only what they may change, give git a deploy key
for one repo, and consider FARM_PERMISSION_MODE=auto. A prompt is not a security boundary: read
docs/security.md.

Does it work with an API key, Bedrock or Vertex?

API keys: yes, with a daily dollar cap instead of subscription pacing. Bedrock and Vertex should work through Claude
Code's own environment variables but aren't tested yet. PRs welcome.

Related projects

• ralph-claude-code is a hardened single loop with a circuit
  breaker and exit detection. From its bug history we took three rules:
  • never trust the agent's text for limit detection;
  • a timeout is not a limit;
  • keep progress after a timeout.
• continuous-claude is a loop that opens a PR per iteration
  and merges only when CI passes. That's the idea behind FARM_VERIFY_CMD.
• sleepless-agent is a 24/7 daemon with a task queue and
  Slack control.
• Several small images keep claude remote-control running in a container.

clodfarm is the first open piece of Pluribus, an experiment in running a small company with a swarm of
Claude agents. This repo is the engine that keeps a swarm like that working.

Contributing

Issues and PRs welcome. Start with CONTRIBUTING.md. The whole loop is tested without a
subscription, using a fake claude that speaks the stream-json protocol:

python3 -m venv .venv && .venv/bin/pip install -e ".[test]" && .venv/bin/pytest

Security issues: see SECURITY.md.

License

MIT. clodfarm is an independent open-source project, not affiliated with or endorsed by Anthropic.
"Claude" and "Claude Code" are trademarks of Anthropic, PBC.