agent-orchestrator/examples/snakepit/README.md

🐍 Snake pit

the "snake pit" agent orchestrator. each agent is a snake. you toss food (tasks) into the pit. agents can devour tasks, gradually digest them, regurgitate them whole or in broken / digested parts, excrete waste (chat logs, debug traces, &c), &c. obviously some specialist agents are on cleanup duty

— @ponder.ooo, 2026-05-28

An agent-orchestrator example built on that idea. Where the sibling builder-adversary example is a phase machine (an ordered plan, two roles handing off), the snake pit is a worker pool over a shared queue: identical workers pull tasks from a pit, plus specialist species for planning and cleanup. Same harness, completely different topology — that's the point of having both.

The core metaphor mapping

(From Claude running with the idea — the image in the thread.)

bio	compute
snake species	agent specialization / system prompt
hunger	priority / availability
smell	task routing (tag match or embedding sim)
fighting	contention resolution
swallowing	task intake + context loading
digestion	LLM calls / tool use
regurgitate whole	re-queue (rejection / timeout)
regurgitate partial	subtask decomposition
excrete	artifact emission (logs, traces, results)
waste heap	artifact store
coprophagy	meta-agents consuming others' artifacts (log summariser, memory builder)
scavengers	housekeeping agents on the waste heap
snake death	crash / OOM / timeout → reap

The key insight: regurgitation IS task decomposition — a planner snake swallows a big task and regurgitates it as smaller food the worker snakes can each digest.

How it maps onto agent-orchestrator

• The pit = a filesystem queue (pit/). Snakes coordinate ONLY through it and claim work by atomic mv, so two snakes never devour the same food. Full layout + protocol: pit/README.md.
• Snake species = agents with different prompts (the "agent specialization" row):
  • keeper (zookeeper, persistent) — tosses food in, keeps the pit healthy, reports.
  • planner (persistent) — regurgitation = decomposition: eats big food, regurgitates smaller food for the workers (prompts/planner.md).
  • snake-1..3 (persistent worker pool) — devour → digest → regurgitate → excrete (prompts/snake.md). Scale the pool by copying a block.
  • cleanup (persistent) — the scavenger on the waste heap; also does light coprophagy (composts logs into a digest) and reaps food abandoned by a snake that died (prompts/cleanup.md).
• hunger / smell / fighting — emergent from the loop: an idle snake naps (low hunger), picks the food it can do (smell), and the atomic-mv claim resolves contention (fighting).
• snake death = crash / timeout → reap — the watchdog heals a dead snake (watch = "heal"); the cleanup snake reclaims whatever food it died holding.

Run it

Needs claude on PATH. From this directory:

python3 ../../agents.py status --config agents.toml      # read-only: what would run
python3 ../../agents.py up     --config agents.toml      # keeper + planner + 3 snakes + cleanup + watchdog
python3 ../../agents.py logs   snake-1 --config agents.toml
python3 ../../agents.py down   --config agents.toml

A sample piece of food (pit/food/food-0001-reverse-string.md) is already in the pit, so the snakes have something to eat on first up. Toss more by writing pit/food/food-<id>-<slug>.md (schema in pit/README.md) — or ask the keeper to.

To watch the mechanics without an agent CLI, set defaults.backend = "demo" in agents.toml (the demo backend just idles) and run up / status / down.

Extending it

• More workers → copy a snake-N block in agents.toml.
• A new species → add an [[agent]] with its own prompts/<species>.md (e.g. a coprophagy meta-agent that builds long-term memory from the waste heap, distinct from the scavenger).
• Smarter routing ("smell") → give food tags: and have snakes prefer matching tags.
• Real coordination across hosts → back the pit with a git repo instead of a local dir and use the watchdog's handoff inbox pings (see the builder-adversary example).

This example carries no project-orchestrator/fleet metadata — like any project it can be run by hand and has no idea a fleet exists.