Welcome to Mandible

Most multi-agent frameworks coordinate agents through direct messaging. This reimplements distributed systems problems - service discovery, routing, consensus, backpressure - but for LLMs. We built Mandible to sidestep all of that.

Mandible is a universal stigmergy framework for autonomous agent coordination. Instead of wiring agents together with message passing, Mandible agents coordinate by depositing and sensing signals in a shared environment - the same way ant colonies self-organize through pheromone trails. No orchestrator. No message routing. Complex behavior emerges from simple rules.

Why stigmergy over message passing?

The environment carries the state. Agents are stateless reactive workers. You never need to answer "who should I tell about this?" - you just modify the environment, and whoever cares will notice.

What you get:

• Observability for free - the environment is the log. ls the signals directory and see the full system state.
• Fault tolerance - an agent dies, the signal remains, another agent picks it up. No lost messages.
• Zero coupling - add or remove colony types without touching any existing colony's configuration.
• Natural load balancing - spin up more instances of any colony type. They self-organize around available work.
• Provenance built in - every signal is signed by the colony that produced it. Bridges attest transfers. Trust is verifiable.

Core concepts

Every concept in Mandible maps to a biological analogy:

The stigmergy loop

Every colony runtime executes the same loop:

sense → match rules → claim → execute action → deposit → (others sense)

1. Sense - poll or watch the environment for signals matching the colony's sensor queries.
2. Match - evaluate rules against sensed signals, ordered by priority.
3. Claim - attempt to claim the signal (prevents duplicate work across concurrent agents).
4. Act - execute the matched rule's action (LLM call, shell command, custom function).
5. Deposit - leave new signed signals in the environment as output.

Other colonies sense those deposited signals and the cycle continues. Complex workflows emerge from simple local rules.

Quick start

Install Mandible and define your first colonies:

npm install mandible

import { colony, createRuntime, FilesystemEnvironment, withClaudeCode } from 'mandible';

const env = new FilesystemEnvironment({ root: './.mandible/signals' });

const shaper = colony('shaper')
  .in(env)
  .sense('task:ready', { unclaimed: true })
  .do(withClaudeCode({
    systemPrompt: 'You are a code shaper. Given a task, write the implementation.',
    allowedTools: ['Read', 'Write', 'Bash'],
  }))
  .concurrency(2)
  .claim('lease', 30_000)
  .build();

const critic = colony('critic')
  .in(env)
  .sense('task:shaped', { unclaimed: true })
  .do(withClaudeCode({
    systemPrompt: 'You are a code critic. Review the implementation for correctness and style.',
    allowedTools: ['Read'],
  }))
  .claim('exclusive')
  .build();

const shaperRuntime = createRuntime(shaper);
const criticRuntime = createRuntime(critic);
await shaperRuntime.start();
await criticRuntime.start();

No colony references any other colony. They coordinate entirely through signals in the environment.

The colony DSL

Mandible provides a fluent builder for defining colonies:

colony('name')
  .in(env)                                        // which environment
  .sense('type:pattern', { unclaimed: true })     // what to watch for
  .when(signal => signal.payload.priority > 0)    // optional guard
  .do(withClaudeCode({ allowedTools: ['Read', 'Write'] }))  // action provider
  .concurrency(3)                                 // max parallel agents
  .claim('lease', 30_000)                         // claim strategy
  .poll(2000)                                     // sensor poll interval (ms)
  .heartbeat(10_000)                              // periodic alive signals
  .autoWithdraw()                                 // auto-remove processed signals
  .timeout(60_000)                                // action timeout
  .retry(3, 1000)                                 // retry with backoff
  .build();

Claim strategies control how agents coordinate over shared work:

Action providers

Action providers wrap external capabilities into a standard interface for colony rules:

withClaudeCode is fully wired to the Claude Code SDK - colonies spawn real agent sessions that read files, write code, and run commands.

Environment adapters

Any shared substrate that supports observe/deposit/withdraw/claim/watch can be a Mandible environment. We ship with four:

Filesystem - signals are JSON files. Claims use atomic file operations. The simplest way to get started locally.

GitHub - issues, pull requests, comments, and labels mapped as signals. Colonies can sense repository activity and deposit responses.

Remote - WebSocket-based environment for distributed deployments. Multiple machines share a single signal namespace over the network.

Dolt - a SQL database with Git-like versioning. Signals become rows, branching enables parallel work, and dolt_history provides queryable time travel for the full signal history.

Trust and attestation

Mandible provides cryptographic provenance for signals using Ed25519:

• Colony signing - each colony generates a keypair and signs every signal it deposits.
• Bridge attestation - when a signal crosses environments via a bridge, the bridge appends a signed attestation, creating a linked chain of custody.
• Sentinel colonies - monitor an environment for signals that fail provenance verification and deposit report signals that other colonies can react to.

The live dashboard

The fastest way to see colonies in action is the CLI:

mandible dev mandible.config.ts

This starts all colonies and opens the live dashboard at localhost:4040 with real-time signal flow visualization, colony status cards, and WebSocket streaming.

What's next

We're building Mandible in the open. Here's what's on the roadmap:

• create-mandible starter template
• Dolt full implementation
• CloudEvents bridge adapter
• Colony scaler
• Trust enforcement policies
• Hosted observability platform

Check out the GitHub repository to get started, or explore Mandible Cloud for managed colony deployment.