mfowler
e4453dcfdd
Based on @ponder.ooo's "snake pit agent orchestrator" idea (bsky 2026-05-28) and Claude's metaphor-mapping elaboration: agents are snakes, tasks are food tossed into a shared pit; snakes devour/digest/regurgitate/excrete. A worker-pool-over-a-shared-queue topology (contrast the builder-adversary phase machine): - pit/ is a filesystem queue; snakes claim by atomic mv (no two eat the same food) - species = specialized agents: keeper (zookeeper), planner (regurgitation IS task decomposition), snake-1..3 (worker pool), cleanup (scavenger + coprophagy) - no [loop] phase machine; persistent agents self-pace via /loop - README carries the full bio→compute mapping table from the thread image Verified: `agents.py status --config agents.toml` lists all 6 agents + service. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
85 lines
4.4 KiB
Markdown
85 lines
4.4 KiB
Markdown
# 🐍 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](https://bsky.app/profile/ponder.ooo/post/3mmwue5bot22u), 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:
|
|
|
|
```bash
|
|
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.
|