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 talk to your Claude from the Claude app on your phone. It does the work, or starts sub-agents for it.
• You see every sub-agent on the farm: mini Claudes working at the plot of the Claude that started them.
• Claudes work together: each one is a person's own account. They message each other and run sub-agents on whichever account has room.
• Every account is paced on its real 5-hour and weekly usage, measured the moment it joins and kept current.

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:

You talk to your Claude in the Claude app; the farm UI shows who is working on what; the Claudes and you use the same CLI.

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 open Claude app → Code → [clodfarm] clodfarm on your phone and just talk to it: "add CSV export to the report page", "have gil's Claude review it", "every morning at 9, triage new issues". Or from a shell:

docker exec clodfarm clodfarm spawn "Add CSV export" --prompt "Add CSV export to the report page, with tests."
docker exec clodfarm clodfarm status

The farm UI is 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.

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

[!TIP] Point it at a real repo with FARM_REPO_URL (plus a deploy key) and set FARM_VERIFY_CMD="pytest -q". The farm clones the repo, and every sub-agent's work lands on main only when your tests pass.

Deploy

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 is one farm (sub-agents, messages, schedules) with 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); sub-agent branches travel through it.

# box 1 creates the farm (table "clodfarm")
deploy/aws/deploy.sh up --workspace-repo git@github.com: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 git@github.com: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 git@github.com: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-agent 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.

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 spawn "Refactor the parser" --prompt "..." && clodfarm status

Full guide: docs/multi-seat.md.

How it works

The picture at the top, step by step:

1. You talk to your Claude in the Claude app (Remote Control). Every Claude on the farm is one person's account, kept reachable by its own clodfarm run.
2. It starts sub-agents with clodfarm spawn: a headless claude -p in its own git worktree, shown on the farm as a mini Claude next to it. Any Claude whose account has budget free runs it, unless --on <name> pins it. A sub-agent's own sub-agents are its children; it ends its run and is resumed in its own session with their results to merge them.
3. The budget governor decides, per account, how many sub-agents may run right now. Usage comes from Claude Code's own rate_limit_events during every run, from a one-word probe the moment a Claude logs in, and again whenever it has been idle for FARM_USAGE_REFRESH seconds.
4. Claudes talk to each other: clodfarm msg gil "..." shows up in Gil's next conversation turn (a Claude Code hook), and clodfarm agents shows how much of its usage each Claude has used, so one that is running high sends work elsewhere.
5. When a sub-agent finishes, its branch is rebased onto main, FARM_VERIFY_CMD runs, and main moves only if the check passes. Otherwise the sub-agent is resumed with the failure output.
6. Schedules start sub-agents on a cron line (in your time zone), every N minutes or once at a time. Every box checks; each firing is claimed atomically, so it runs once.

Everything lives in one store: a SQLite file on one box, or a DynamoDB table shared by several boxes and accounts.

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

How it compares

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.

Details and caveats: docs/auth.md.

Commands

Every command takes --json.

FAQ

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.