// SUBSTRATE · v0.2 · alpha
swarm-lib
Filesystem-as-orchestrator for agentic workflows.
Three primitives — atomic-rename queueing, status.json checkpointing, a generic worker loop — that turn long, multi-step agentic work into a queue of atomic tasks immune to compaction, crashes, rate limits, and process restarts. No broker. No daemon. No database. Just POSIX and JSON.
Context starvation
A long agentic conversation accumulates context, hits compaction, mid-flight work dies. Chat history is being used as program state.
Sync tool-call blocking
An expensive planner holds its context window open while a subprocess churns for minutes. Tokens burn at idle.
Chat-history-as-state
When the conversation dies, the work dies. There's no durable source of truth for "where am I."
How you'd use it day to day
Five concrete shapes of work where swarm-lib saves real time, tokens, or sanity. Each one is the same substrate, just decomposed differently.
PATTERN 1 · the killer app
Long-running async
Ask an agent to audit 16 repositories for a standard. The planner decomposes into 16 tasks + 1 synthesize task with depends_on set to all 16, then exits. A worker chews through each one in a fresh context window. You come back later, run swarm-cli ls, see 14 done + 2 failed, read artifacts, decide what to retry. A multi-day marathon becomes a 12-hour worker run you didn't have to babysit.
PATTERN 2 · zero-friction adoption
Compaction insurance for any multi-step task
Even for a single multi-step task you're doing interactively, write status.json as you go. Compaction happens; the next session reads the file, sees next_step and next_task_id, picks up exactly where you left off. The chat surface looks the same; the substrate just won't lose state under it.
PATTERN 3 · resilient automations
Scheduled work that survives restarts
Daily multi-step pipelines: research → draft → edit → publish. Cron enqueues the first task; each handler enqueues the next with depends_on; artifacts land in artifacts/. When step 3 fails, it's quarantined in failed/ and tomorrow's run is unaffected. Retry + state + storage for free, no plumbing.
PATTERN 4 · human-in-the-loop without the framework
"I am the worker"
Sometimes the right worker for a task is you. swarm-cli claim outputs the task + the suggested next step + the artifact path. Do the work in your live session, swarm-cli complete when done. Bots claim draft tasks; humans claim review tasks; bots claim finalize. Humans are just workers with a filter.
PATTERN 5 · the substrate everyone shares
Cross-tool federation
n8n triggers and webhooks. Shell scripts for deploys. Claude or Codex for reasoning-heavy steps. ollama for cheap local inference. With swarm-lib, all of them read and write the same ~/.swarm/ substrate. Each tool stays in its lane; the filesystem is the contract. New tools join the federation without you writing integration code — if it can read and write files, it's a participant.
Each pattern gets a full walkthrough on the standalone site at swarm.mabus.ai/patterns.
"Three primitives, two commits' worth of substrate code, one filesystem. The discipline UNIX had in 1995, applied to the agentic work people are shipping now. Chat history is volatile; the file is the contract."