# 🐍 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.