Understanding how to run a fleet of agents
Once the number of artifacts grew, a flat folder stopped being usable. I introduced hierarchical organization — grouping by topic, with a top-level index.md pointing to per-topic index.md files, each of which holds a short summary and links to individual artifacts. Nesting depth is unbounded; you add a level whenever a topic earns one.
The next realization was that tasks belong in a queue, not to the terminal. I moved to markdown files with todo and done sections. At that point, almost no terminal interaction was left — just /clear after each task and a prompt like "take the next task."
The obvious next step was to automate that loop: a shell loop calling claude -p "take next task", with context cleared automatically at the end of each session. This works fine for a single worker.
Scaling beyond one agent needs a few extra pieces: - A proper queue. This is what beads provides — dependency-aware, atomic claims via bd ready and bd update --claim, so two workers don't grab the same task. - A channel back to the human. Also handled by beads: bd update <id> --status blocked --notes "QUESTION: <one-line question>" parks the task and surfaces the question without halting the rest of the fleet. - Session memory. Because each claude -p invocation starts with a fresh context, the agent has to write down what it has done, what it plans to do, and any related notes — either into beads itself (status, notes, dependencies on the issue) or to disk — so the next session can pick up cleanly after a restart.
With these components in place, we can spawn many claude workers pulling from tasks from beads db, asking questions, adding tasks to db, storing progress and final artifacts to disk. AMD describe this pattern in their amazing issues description https://github.com/anthropics/claude-code/issues/42796. It took me some time to figure out how this suppose to work.