clodfarm (say it out loud): a farm of Claude Code agents. Plant a mission, they split it into sub-agents, open the work, and pace themselves on each account's real 5-hour and weekly usage. Steer it from the Claude app.. It is open-source on GitHub.

Is clodfarm free to use?

clodfarm is open-source under the MIT license, so it is free to use.

What category does clodfarm belong to?

clodfarm is listed under devops in the Claudeers registry of Claude-compatible tools.

clodfarm — DevOps & CI/CD for Claude

Platforms	cli, api, web
Operating systems	—
AI compatibility	claude
License	MIT
Pricing	open-source
Language	Python

The clodfarm UI: a pixel-art farm where every Claude Code agent is a little Claude character. Some work at terminals beside crop plots, mini Claudes help as sub-agents, finished quests bloom, and a few nap by the barn while the budget governor paces them

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.

Terminal output of clodfarm status: two Claude accounts with their own usage bars and governor decisions, Remote Control live, and the shared task queue
_{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:

In .env, set FARM_STORE=dynamodb, FARM_TABLE=<table>, AWS_REGION=<region> and FARM_REPO_URL=<shared repo>.
Give the box AWS credentials for the table.
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

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.
While it runs, every rate_limit_event updates that seat's budget, so all its boxes react within seconds.
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.
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.

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.

clodfarm

Install with your AI

// compatibility

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

Why clodfarm

Quick start

Deploy

Single deployment

Multiple deployments, one farm

How it works

How it compares

Logging in

Commands

FAQ

Contributing

License

// faq

// embed badge

// retro hit counter

// reviews

// guestbook

// related in DevOps & CI/CD

Install with your AI

// compatibility

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

Why clodfarm

Quick start

Deploy

Single deployment

Multiple deployments, one farm

How it works

How it compares

Logging in

Commands

FAQ

Related projects

Contributing

License

// faq

// embed badge

// retro hit counter

// reviews

// guestbook

// related in DevOps & CI/CD