Organizing a Claude Army

Aug 12, 2026 • AI, agents, tooling, Proxmox

Skip the details — take me to the bottom line ↓

I had pushed up my productivity using a single agent, but I was still bottlenecked. I knew I could get more done if I could bring more than one agent to bear on my research, but I couldn’t figure out how to keep many agents marching in the same direction.

I had gone through the progression everybody goes through — chat window, then the IDE plugin, then the command line, then the command line with a git repo underneath it, which is the step where an agent stops being a clever autocomplete and starts being something you can hand a project to.

Each step was a real improvement. But they all landed in the same place: one conversation, one task, and me sitting there while it thought. I had four or five things I wanted done and exactly one worker.

What I was actually trying to run

Some context, because the shape of the work drove everything that follows.

I run a homelab of about ten Proxmox VMs and containers with high-availability migration between nodes. Alongside it is a timelab — more than half a dozen embedded Linux boxes, mostly Raspberry Pi class, doing precision timing work. At any given moment that lab usually has three or four different data-collection experiments running at once.

I needed agents for Python coding, for code reviews, for coordinating access to shared lab resources, for research, for design, for graphical presentation of experimental results, and for monitoring/restarting experiments while I was away from the lab or sleeping.

That is the load. It is not one project that needs an assistant. It is a small institution that needs staff.

The framework I couldn’t drive

Early in 2026 I tried Gas Town, a multi-agent workspace manager. It has a whole vocabulary — a Mayor who coordinates, a Town that holds your projects, worker agents with persistent identity, work tracked in a git-backed ledger. Conceptually it was exactly what I was after.

And when I told the Mayor to write code, I loved the result. That part was genuinely good.

The trouble started when the Mayor delegated. Work handed off to another agent came back incorrect, or did not come back at all, and I could not see enough of what was happening to work out why. In retrospect I suspect I was meant to be working directly with those agents rather than through the Mayor — but I never figured out how to structure my project so that I could.

So I did the thing you do when a system is too complicated to drive: I stopped driving it. I went back to giving the Mayor the work directly and waiting for it, which is precisely the bottleneck I had set out to escape, now with more moving parts.

The three habits I took with me

I did not leave empty-handed. Three things came out of that experiment and all three turned out to be load-bearing.

tmux, and the episodic check-in

Not as a terminal multiplexer — as a way to hold several agent sessions and switch between them in a keystroke.

The reason that matters is that my prompts are not quick. I got curious enough to measure it: I pulled the timestamps out of every session transcript across the whole fleet and timed each prompt to the moment the agent went idle.

A three-minute median sounds like something you could sit and watch. The tail says otherwise, and the tail is where the interesting work is.

It gets better, because a prompt returning quickly often does not mean the work is done. Half the time the agent has just started an experiment in the timelab, and what I actually want is to come back later, look at the data collected so far, and decide whether to let it run or change the parameters.

And you cannot predict it from the prompt either

I assumed a long prompt meant a long wait. It seemed obvious — more asked for, more work done. So I measured that too, and it is not true. Across all 1,071 prompts the rank correlation between how many words I typed and how long the agent then ran is 0.12, which is another way of writing “none”. Bucket the prompts by length and the median duration barely moves: about three minutes for a five-word prompt and about three minutes for a three-hundred-word one.

Which lands somewhere more useful than where I started. I cannot look at what I just typed and estimate when to come back. The information simply is not in the prompt.

So the unit of interaction is not “ask, wait, read.” It is check in, correct, leave again — and tmux is what makes that cost nothing. The same sessions I have at my office desk are on an iPad Pro with a keyboard on a park bench, or on my iPhone with a folding keyboard I have carried on the bike to a picnic table. I get a status update and make a mid-course correction whenever I have a moment, from wherever I happen to be.

--dangerously-skip-permissions

The flag does what it says. Every approval prompt goes away and the agent just acts.

I understand why that alarms people, so let me say plainly how I think about it. The prompts were not making me safe. I was approving them the way everyone approves them — reflexively, in batches, without really reading. What they were doing was serializing the work: the agent stops, I context-switch back, I click, it resumes. That is the bottleneck again, wearing a safety control’s uniform.

So I moved the safety somewhere it could actually do some good.

Use git worktrees when agents share a repo

The third habit. When several agents are working on one project, give each its own git worktree — separate directories, separate checkouts, one shared history. They can work on different aspects of the same problem without tripping over each other’s files, and everything still converges through git.

At this point in the story that was just tidiness. It turned out to decide far more than I realised, for reasons I would not understand for months.

Where they live, and what I assume about them

The whole fleet runs inside a single unprivileged LXC container on the Proxmox cluster. Inside that container the agents are ordinary users — no passwordless sudo, nothing special. What they do have is real authority outward: passwordless sudo on the timelab machines they run experiments on, and whatever other credentials I have handed them, scoped to specific jobs.

My default security posture assumes that malicious intent will show up eventually, even on a nominally trusted network. I do not get to assume my own LANs stay friendly forever. So I treat the container running my agents as a potentially malicious actor and ask two questions about it: what could go wrong if code in there went rogue, and how would I recover? This posture explains why it’s an unprivileged container.

Those questions have good answers here. The container itself I can snapshot, roll back, or throw away, on a cluster that can move it between nodes. The lab machines it can reach are experiment boxes I can reimage in an afternoon. That is the trade — the agents are fast and trusted within a blast radius I have actually drawn, instead of being interrupted forty times a day by prompts that were never a boundary at all.

It is worth being honest that this is a homelab posture. My blast radius is my own equipment and my own time. If the same fleet were touching production systems belonging to somebody else, the arithmetic would be different and I would not be writing this paragraph so cheerfully.

The day plan

With tmux, worktrees and no approval prompts, I got to four sessions running in parallel. And immediately hit the next problem, which is the interesting one: four agents working on related things have no way to talk to each other.

They cannot see each other’s conversations. They cannot ask each other questions. Two of them will happily solve the same problem twice, or worse, solve it two incompatible ways.

What I built for this is embarrassingly simple. It is a file. I call it the day plan, and it is an append-only log every agent can write to and read back. An agent can propose an item and get an ID, ack somebody else’s, discuss under one in a thread, set a status, or render the whole current state as markdown. Current state is computed by replaying the log, so several agents can write at once without stepping on each other. No database, no server — a JSONL file and a script.

The rhythm that grew around it is my favourite part of all this. I would wake up having slept on the previous day’s work with new tasks in mind — usually with some dependency between them that we would refine as the day went on. The day plan is where I put those, and where the agents put their results, their requests of each other, and their proposed follow-ups.

It reads like a stand-up that happens in writing, all day, without anybody standing up. The four sessions on my main project have names — Main, Bravo, Charlie and Delta — and they address each other by them, which sounds twee until you are reading a threaded argument between two of them about whose number is right.

Those four are the first of three different ways I ended up organizing agents, and it is the one that shares the most: one repo, one pool of retained knowledge, one day plan. A hive mind — everything shared. I did not choose it so much as fall into it, and it would be months before I understood why it worked.

The first sign that I did not understand my own setup

One day Charlie started talking about itself in the third person.

It took me a moment to work out what I was reading, and then it clicked: Charlie had taken on Bravo’s persona. I now had two Bravos and no Charlie at all. Getting one of them to pick up as Charlie again was easy enough — I told it who it was and it carried on. At the time I did not give it much thought beyond laughing and imagining a B-grade movie: Invasion of the Context Snatchers.

It was the first sign that I did not really understand what my agents shared and what they kept separate. I filed it as a curiosity. It was actually a symptom, and it would be months before I knew of what.

Retained knowledge, and how I stumbled into it

Here is the part I got to backwards.

What I wanted, without yet having the words for it, was retained knowledge: every new session for a given agent should start with a distillation of the previous work, so I never have to re-explain the project. And — just as important — I did not want every agent to know everything, because knowing everything is just a way of wasting context.

Those first four agents were each in a separate worktree of one shared repo, working on different aspects of the same project. They shared everything except their transcripts. Entirely by accident, I had stumbled into exactly the retained knowledge configuration you want for that shape of work: a hive mind — common facts pooled, conversations separate.

Then I started spinning up agents for completely unrelated purposes — Proxmox, UniFi, DNS, Homebridge, Checkmk, the UPS fleet, this blog, and others. And the accident stopped being lucky. I did not want to clutter my Proxmox agent’s context with conversations about writing blog posts.

Those turned out to need the other two organizations. The ops agents each tend a different system, so they want private heads — but they all need the same facts about which host is which, so they are independent, with one shared database. And a handful of agents have nothing whatever to do with each other and should never bleed together: fully independent, nothing shared.

Three organizations, sorted by how much each group shares. But I only got there after finding out how sharing worked at all.

That is what finally drove me to understand how retained knowledge is shared between agents, and how it is not.

The hiring analogy

The way I think about it is hiring.

Say you run a ten-person company and everyone is working at 90% capacity. On paper you have one person’s worth of slack you could use to start a new project if you distributed it across the team. But you probably should not. Handing a new direction to ten busy people costs each of them a context switch, and what you get back is worse than one focused person’s work. Hire the eleventh.

That is exactly the trade with agents, except the eleventh employee starts immediately and costs a great deal less. Not nothing — every agent burns tokens, and more of them means more output to review, which is the scarce resource in the end. But the argument was never about cost. It is about context switching, and that is the thing the eleventh employee actually saves you.

What the meta agent found

So I pointed an agent at the fleet itself — a meta agent whose whole job is how the other agents are set up. The meta agent explained how three things are keyed independently:

Which yields one rule that does most of the work:

Launch each agent from its own directory and it gets a separate transcript, separate instructions, and separate retained knowledge for free. No access control needed. The isolation is a side effect of where you started.

And it explained my accident. Main, Bravo, Charlie and Delta shared a repo, so they shared one memory store — which is why they had felt so well coordinated. Two directories that share a git repo share their retained knowledge no matter how separate they look.

It also explained why the day plan worked as well as it did. A shared log of proposals and acks is only useful between agents who already have the same picture of the project; four strangers passing notes would have spent every message re-establishing context. The day plan was an extra layer of coordination on top of shared retained knowledge, and it was only possible because that layer was there. I had built the visible half and inherited the invisible half by accident.

It also explains what an agent is. Identity comes from the launch directory — which means Charlie was never a thing that could be corrupted, only a directory I could start something in. I never did find out exactly what happened that day, when Charlie seemed to snatch Bravo’s identity, and I no longer have the evidence to check. But I am certain that agent identities can be mixed up if you are not careful, and that I should have chased down the confusion at the time.

The scaffolding now includes a tmux startup script per agent that launches it from the correct directory, every time. It is a nine-line shell script guarding the single decision that determines who an agent is, and writing it down was the cheapest fix in this entire story.

Then the meta agent found the thing I would never have found myself: a vestigial ~/.git left over from that earlier experiment with Gas Town. My home directory had quietly become a git repository, so every agent underneath it that was not inside another nested git repo — Proxmox, DNS, the blog, all of them — was pooling its memories into one store and reading everybody else’s retained knowledge. I had been carefully separating agents into their own directories and inadvertently running a global hive mind the whole time.

Archiving that stray .git fixed it, and we then walked through the rest deliberately: isolate retained knowledge where isolation is what you want, and share it where sharing is what you want.

The three organizations, on one page

Which is where the three ways of organizing agents stop being scattered observations and become a shape. The meta agent drew the whole fleet as a single map, and it is the clearest picture of this I have.

1 Hive mind — everything shared. Main, Bravo, Charlie and Delta. Four worktrees of one repo, so one memory store, one set of docs, one day plan. They know everything each other knows, which is what makes a threaded argument between two of them productive rather than a re-briefing.

2 Independent — one shared database. The seven ops agents. Each keeps private lessons in its own store, because how the Checkmk agent likes to work is no business of the DNS agent’s. But they all read and write one shared repository of host facts, because facts about the homelab belong to the homelab. The trick is that they reference that repo rather than launching from it — so it never becomes their memory keying.

3 Fully independent — nothing shared. The meta agent, this blog, and one more. Different domains that should never bleed into one another.

There is a second dimension on that map, drawn as a badge above each agent, and it is worth reading separately: reach. How far into the real world that agent can act. Those two axes are independent, and confusing them is the mistake the map exists to prevent — the ops group is the most isolated in knowledge and contains some of the widest authority, while the blog agent is isolated on both axes and still carries the fleet’s only real risk, because its output is public — this post, and everything in Topics In Timekeeping, came out of it. Sharing and power are different questions.

The scaffolding

The meta agent also worked out what actually goes where, and this is the part I would hand to somebody starting today.

CLAUDE.md auto-loads every session, so it holds the project’s identity, its conventions, its working rules, and pointers to everything else. It is the single biggest lever against re-explaining yourself.

glossary.md holds the lingo — human-facing, browsable, the place where the project’s jargon gets defined once. That one is my buddy Chris Treichel’s idea, and it has earned its keep several times over. A glossary keeps the language consistent across sessions and consistent with what is written in docs/, which matters more than it sounds like.

In my last talk I put it as sloppy language is sloppy thinking. A glossary keeps the thinking honest, and it cuts down the confusion between the language model and the meat-ware — which is very often not a disagreement about the subject at all, but two parties using one word for two things.

The memory store holds distilled agent-facing facts, one per file, indexed so a fresh session can find them.

And the rule that ties it together, which my main project now follows: every new file in docs/ gets summarised into CLAUDE.md with a link back to the file for the details. So every session begins with a summary of all the retained knowledge that exists, plus pointers to the depth. The agent reads a page and knows what it knows; it goes and reads the file only when it needs the detail.

That is what makes a brand-new session genuinely caught up rather than merely resumed — which matters more than it sounds like, because resuming an old session replays the entire transcript into context, and transcripts grow without bound.

What I’d tell someone starting

Steal the tmux habit first. It is free and it changes the economics of watching more than one thing. Check in episodically; do not sit and watch.

Give each agent its own directory, and know what that keys. Transcript and instructions follow the directory. Retained knowledge follows the repo. That difference is the whole ballgame and it is easy to get wrong by accident. Write the launcher script that starts each agent in the right place — the one decision you cannot afford to make by hand at eleven at night is which agent you are talking to.

Build the shared file before you think you need it, and make it append-only. The moment you have two agents on related work you have a coordination problem, and you will invent something worse under time pressure than what you would design calmly.

Partition by domain, not by capacity. The temptation is to give new work to whichever agent seems least busy. Resist it. Hire the eleventh.

And pick your boundary deliberately. Somewhere between “approve every file write” and “no limits at all” there is a line that fits what you are actually risking. Mine is the edge of a container I can roll back, chosen on the assumption that something hostile turns up eventually. Yours might be somewhere else entirely — but it should be a decision you made once, not a prompt you dismiss forty times a day.

Follow-ups: What a Claude Army Shares — the flip side of this map. Sorting the groups by how much they share raised the question of what kinds of thing get shared, and the answer turned out to be four separate rails with four different sets of rules. And A Window Per Agent Team — the cockpit rather than the structure: how you actually sit in front of all this.

← What a Claude Army Shares Sub-Nanosecond at Home, Take Four →