Mobs

A mob is a team of agents that work together. Each agent has a role (profile) and agents communicate over signed channels (wiring). How they coordinate is up to you — autonomous agents can self-organize through peer messaging alone, you can define declarative flows (DAGs) for structured multi-step work, or combine both. For many use cases, wiring and skills are enough and preferable, as it gives agents more robust problem-solving through natural collaboration rather than rigid orchestration.

Core concepts

Profiles

A profile is a template for an agent. It defines the model, tools, skills, and communication settings. When you spawn a member, you pick a profile and give it a unique ID.

"lead": {
  "model": "claude-opus-4-6",
  "peer_description": "Coordinates the team, assigns tasks",
  "tools": { "builtins": true, "comms": true, "mob": true, "mob_tasks": true },
  "skills": ["triage-workflow"],
  "runtime_mode": "autonomous_host"
}

Field	Description
`model`	LLM model name
`tools`	Tool categories: `builtins`, `shell`, `comms`, `memory`, `mob`, `mob_tasks`, `mcp` (server names)
`skills`	Skill references to inject
`peer_description`	Visible to peers during communication
`runtime_mode`	`"autonomous_host"` (default) or `"turn_driven"`
`output_schema`	JSON Schema for structured output extraction
`external_addressable`	Whether this member is visible for cross-mob comms

Wiring

Wiring creates a trusted communication channel between two members. An agent can only send messages to peers it’s wired to. Wiring is bidirectional — if A is wired to B, both can send to each other.

"wiring": {
  "auto_wire_orchestrator": true,
  "role_wiring": [
    { "a": "analyst", "b": "analyst" }
  ]
}

auto_wire_orchestrator: automatically wire every spawned member to the orchestrator
role_wiring: rules applied at spawn time — every member of role a gets wired to every member of role b

Runtime modes

Mode	Behavior	Use case
`autonomous_host` (default)	Continuous loop: wake on inbox message → process → respond → sleep	Long-lived agents that react to peer messages and events
`turn_driven`	Only runs when explicitly given a turn	Controlled execution, deterministic ordering, flow steps

Flows

A flow is a DAG of steps. Each step targets a role, sends a message, and can depend on other steps. The flow engine dispatches steps in topological order, respecting dependencies and conditions.

"flows": {
  "triage": {
    "steps": {
      "scan": {
        "role": "lead",
        "message": "Scan the issue tracker and prioritize the top 5 issues"
      },
      "investigate": {
        "role": "analyst",
        "message": "Investigate your assigned issue in depth",
        "depends_on": ["scan"],
        "dispatch_mode": "fan_out"
      },
      "summarize": {
        "role": "lead",
        "message": "Synthesize all findings into an executive summary",
        "depends_on": ["investigate"],
        "depends_on_mode": "all"
      }
    }
  }
}

Step fields

Field	Description
`role`	Profile name — the step runs on a member with this role
`message`	Prompt sent to the member
`depends_on`	Step IDs that must complete before this step starts
`depends_on_mode`	`"all"` (default) — wait for every dependency. `"any"` — start when any one completes
`dispatch_mode`	`"fan_out"` (default) — send to all members of the role. `"one_to_one"` — single member. `"fan_in"` — aggregate
`condition`	Guard expression (`eq`, `in`, `gt`, `lt`, `and`, `or`, `not`) — step is skipped if false
`branch`	Label for conditional routing
`timeout_ms`	Per-step timeout
`allowed_tools` / `blocked_tools`	Per-step tool overlay

Mob definition

A mob definition is a JSON or TOML document that declares everything: profiles, wiring, flows, limits.

{
  "id": "release-triage",
  "profiles": {
    "lead": {
      "model": "claude-opus-4-6",
      "peer_description": "Coordinates triage",
      "tools": { "builtins": true, "comms": true, "mob": true, "mob_tasks": true },
      "skills": ["triage-workflow"]
    },
    "analyst": {
      "model": "claude-sonnet-4-5",
      "peer_description": "Investigates issues",
      "tools": { "builtins": true, "shell": true, "comms": true },
      "runtime_mode": "autonomous_host"
    }
  },
  "wiring": {
    "auto_wire_orchestrator": false,
    "role_wiring": [{ "a": "lead", "b": "analyst" }]
  },
  "flows": {
    "triage": {
      "steps": {
        "scan": { "role": "lead", "message": "Prioritize issues" },
        "investigate": { "role": "analyst", "message": "Investigate", "depends_on": ["scan"], "dispatch_mode": "fan_out" },
        "summarize": { "role": "lead", "message": "Summarize findings", "depends_on": ["investigate"] }
      }
    }
  },
  "limits": {
    "max_flow_duration_ms": 300000,
    "max_step_retries": 2,
    "max_orphaned_turns": 10
  }
}

Prefabs and mobpacks

Prefabs are built-in definition templates for common patterns:

Prefab	Pattern	Profiles
`coding_swarm`	Lead + workers for coding tasks	lead, worker
`code_review`	Multi-reviewer code audits	lead, worker
`research_team`	Diverge/converge research	lead, worker
`pipeline`	Sequential stage handoffs	lead, worker

Prefabs are starting points — create from a prefab, then customize. Mobpacks are portable archives (.mobpack) that bundle a mob definition with its skills, config, and optional Ed25519 signatures into a single deployable artifact. Mobpacks can be deployed to any surface or compiled into a browser-runnable WASM bundle. See the Mobpack guide for packaging, signing, trust policies, and web deployment.

Lifecycle

A mob goes through these phases:

Create — register the definition, allocate storage
Spawn — instantiate members from profiles (each member is a real agent session)
Wire — establish communication channels between members
Operate — members communicate, execute turns, run flows
Complete/Destroy — mark as done or tear down

Members can be added (spawn) or removed (retire) at any time. Wiring can change dynamically (wire, unwire). Flows can be started, polled, and cancelled.

Spawn semantics

Spawning is deferred — create_session() registers the member without running an LLM turn. The first real work happens when the member receives input (a peer message, event injection, or flow dispatch). This keeps spawn latency bounded by session provisioning, not model latency.

State transitions

Operation	Effect
`stop`	Pause all members
`resume`	Restart paused members
`complete`	Mark mob as done (members stop)
`destroy`	Tear down all resources

Mob tools

When mob capability is enabled on a session, the agent gets these tools:

Tool	Parameters	Description
`spawn_meerkat`	`mob_id`, `specs[]`	Spawn members (batch)
`spawn_many_meerkats`	`mob_id`, `specs[]`	Spawn multiple members concurrently
`retire_meerkat`	`mob_id`, `meerkat_id`	Remove a member
`force_cancel_meerkat`	`mob_id`, `meerkat_id`	Force-cancel a member
`meerkat_status`	`mob_id`, `meerkat_id`	Get member status
`list_meerkats`	`mob_id`	List members and state
`wire_peers`	`mob_id`, `a`, `b`	Wire a comms channel between two members
`unwire_peers`	`mob_id`, `a`, `b`	Unwire a comms channel
`mob_run_flow`	`mob_id`, `flow_id`, `params?`	Execute a DAG flow
`mob_flow_status`	`mob_id`, `run_id`	Check flow run status
`mob_cancel_flow`	`mob_id`, `run_id`	Cancel a running flow
`mob_task_create`	`mob_id`, `title`, `body?`	Create a shared task
`mob_task_list`	`mob_id`	List shared tasks
`mob_task_update`	`mob_id`, `task_id`, `status`	Update a task’s status
`mob_task_get`	`mob_id`, `task_id`	Get task details

These tools are available on every surface — CLI, RPC, REST, MCP, Python SDK, TypeScript SDK. The agent orchestrates the mob by calling these tools in response to natural language instructions.

Direct control plane

In addition to tool-driven orchestration (where an agent calls mob tools), there is a direct control plane for programmatic access without going through an LLM:

JSON-RPC
REST
Python
TypeScript
Rust

// List prefabs
{"jsonrpc":"2.0","id":1,"method":"mob/prefabs","params":{}}

// Create a mob directly
{"jsonrpc":"2.0","id":2,"method":"mob/create","params":{
  "definition": {"id":"my-mob","profiles":{}}
}}

// Spawn and send work
{"jsonrpc":"2.0","id":3,"method":"mob/spawn","params":{
  "mob_id": "my-mob",
  "profile": "lead",
  "meerkat_id": "lead-1"
}}
{"jsonrpc":"2.0","id":4,"method":"mob/send","params":{
  "mob_id": "my-mob",
  "meerkat_id": "lead-1",
  "content": "Coordinate the release triage."
}}

# REST keeps mob lifecycle compact/generic
curl http://localhost:8080/mob/prefabs
curl http://localhost:8080/mob/tools
curl -X POST http://localhost:8080/mob/call \
  -H "Content-Type: application/json" \
  -d '{"name":"mob_create","arguments":{"definition":{"id":"my-mob","profiles":{}}}}'

mob = await client.create_mob(definition={"id": "my-mob", "profiles": {...}})
await mob.spawn(profile="lead", meerkat_id="lead-1")
lead = mob.member("lead-1")
await lead.send("Coordinate the release triage.")
events = await lead.events()

const mob = await client.createMob({ definition: { id: "my-mob", profiles: {...} } });
await mob.spawn({ profile: "lead", meerkatId: "lead-1" });
const lead = mob.member("lead-1");
await lead.send("Coordinate the release triage.");
const events = await mob.subscribeMemberEvents("lead-1");

let definition = MobDefinition::from_json(json)?;
let handle = MobBuilder::new(definition, MobStorage::in_memory())
    .with_session_service(service)
    .allow_ephemeral_sessions(true)
    .create()
    .await?;

handle.spawn("lead", "lead-1", None).await?;
handle.wire("lead-1", "worker-1").await?;
handle.run_flow("triage", json!({})).await?;

Topology

Topology rules govern which roles can communicate. Use topology for structural governance in sensitive deployments.

Mode	Behavior
`advisory` (default)	Log violations but allow communication
`strict`	Block disallowed edges

"topology": {
  "mode": "strict",
  "rules": [
    { "from_role": "analyst", "to_role": "lead", "allowed": true },
    { "from_role": "analyst", "to_role": "analyst", "allowed": false }
  ]
}

Wildcard "*" matches any role.

When to use mobs

Situation	Use
Single agent with tools	Plain session
Multiple agents that need to collaborate	Mob
Agents with different roles/capabilities	Mob with profiles
Coordinated multi-step workflows	Mob with flows
Structured communication policies	Mob with topology

Getting started

Core concepts

Guides

Examples

Core concepts

Profiles

Wiring

Runtime modes

Flows

Step fields

Mob definition

Prefabs and mobpacks

Lifecycle

Spawn semantics

State transitions

Mob tools

Direct control plane

Topology

When to use mobs

See also

Getting started

Core concepts

Guides

Examples

​Core concepts

​Profiles

​Wiring

​Runtime modes

​Flows

​Step fields

​Mob definition

​Prefabs and mobpacks

​Lifecycle

​Spawn semantics

​State transitions

​Mob tools

​Direct control plane

​Topology

​When to use mobs

​See also

Core concepts

Profiles

Wiring

Runtime modes

Flows

Step fields

Mob definition

Prefabs and mobpacks

Lifecycle

Spawn semantics

State transitions

Mob tools

Direct control plane

Topology

When to use mobs

See also