Introduction

Flock

Self-evolving agent coordination runtime — the harness is the flock.

Rust MIT CI verified

Install

curl -fsSL https://raw.githubusercontent.com/Alphabetsoup16/Flock/main/install.sh | bash

Quickstart · Daily driver · Agent guide · Socket API · MCP tools

Flock is a Rust coordination runtime where agents wake from a decaying pressure field, verify work through typed harness recursion (RAH), and improve topology from episode logs.

What makes Flock different

Flock is not a meta-harness wrapper or workflow DSL. Default flock run uses deterministic plugins (gridworld, shell) — wire your LLM via MCP, ACP, or remote panes. See What Flock is / is not.

Episode flywheel

flowchart LR
    RUN[flock run] --> LOG[.flock/episodes]
    LOG --> EVOLVE[flock evolve]
    EVOLVE --> GATE[flock drift-check]
    GATE --> RUN

    class RUN runtime
    class LOG runtime
    class EVOLVE evolve
    class GATE gate

1. Run — scheduler-led goal loop (flock run) or RLM verify/act (flock run --rlm)
2. Log — reproducible episode JSON with optional pane topology
3. Evolve — topology mutations from episode corpus
4. Gate — flock drift-check manifest guardrails

First success in one command after install:

flock run --goal "reach target" --plugin gridworld

Episode JSON lands in .flock/episodes/. Full walkthrough: Quickstart.

Quick paths

Build this book locally

cargo install mdbook mdbook-mermaid
mdbook-mermaid install book
mdbook build book
mdbook serve book   # http://localhost:3000

Or run ./scripts/smoke-docs.sh (included in ./scripts/verify.sh).

Live site: flock-docs.pages.dev — deploy via .github/workflows/docs.yml.

For LLM agents: llms.txt.

Quickstart

Get from clone to a gridworld episode in under two minutes.

Install

From a clone (recommended for development):

git clone https://github.com/Alphabetsoup16/Flock.git flock && cd flock
./install.sh
export PATH="$PWD/target/release:$PATH"

One-liner (release binary):

curl -fsSL https://raw.githubusercontent.com/Alphabetsoup16/Flock/main/install.sh | bash

Or with Cargo directly:

cargo install --path crates/flock-cli

Requires stable Rust from rustup.rs; toolchain pinned in rust-toolchain.toml.

First success

flock run --goal "reach target" --plugin gridworld

Structured JSON appears on stdout; an episode file lands under .flock/episodes/.

Common commands

flock --help
flock run --goal "reach target" --plugin gridworld
flock run --goal "reach target" --plugin gridworld --rlm
flock evolve --episodes 16 --workspace .flock/episodes
flock replay --episode .flock/episodes/<goal-id>.json
flock replay --episode .flock/episodes/<goal-id>.json --continue-run
flock multiplexer ensure
flock dashboard          # ratatui control tower (daily driver)
flock herd status
flock drift-check
flock plugin list
flock mcp

MCP server

flock mcp

Wire your MCP client to the stdio JSON-RPC surface. Tool catalog: MCP tools.

Remote multiplexer

flock remote --goal "reach target" --plugin gridworld
flock remote --ssh user@host --goal "reach target" --plugin gridworld
flock remote --stub --goal "reach target"

Default socket: ~/.config/flock/flock.sock (override with FLOCK_SOCKET).

Verify before you PR

./scripts/verify.sh

Daily driver loop

The recommended local workflow for developing and operating Flock.

Loop

flock multiplexer ensure  →  flock dashboard  →  flock run  →  flock evolve  →  ./scripts/verify.sh

1. Multiplexer — flock multiplexer ensure starts the in-tree PTY server (~/.config/flock/flock.sock).
2. Dashboard — flock dashboard opens the ratatui control tower (agents, pressure, pane tree). Writes ~/.config/flock/statusline.json for MCP observability.
3. Run — flock run --goal "…" --plugin gridworld (scheduler) or --rlm (verify/act loop with mux pane topology).
4. Evolve — flock evolve --episodes 16 --workspace .flock/episodes mutates topology from episode corpus.
5. Verify — ./scripts/verify.sh before every PR (fmt, clippy, hack, tests, smoke benches, dashboard + socket e2e).

Headless CI parity

CI runs the same smoke surface without a TTY:

cargo test -p flock-dashboard --test integration
cargo test -p flock-multiplexer --test socket_integration
flock run --goal "reach target" --plugin gridworld --rlm

Remote / SSH

flock remote --goal "reach target" --plugin gridworld
flock herd attach --session my-work

See Dashboard and Verify.

Dashboard

flock dashboard is the ratatui control tower over the in-tree multiplexer — the daily-driver view of agents, pressure, pane topology, and evolution archive.

Launch

flock multiplexer ensure
flock dashboard

Defaults:

• Socket: ~/.config/flock/flock.sock (override with --socket)
• Episodes: .flock/episodes
• Archive: .flock/archive

Keybindings

Headless observability

The dashboard writes ~/.config/flock/statusline.json on each refresh. MCP tool flock_read_statusline (see MCP tools) reads this snapshot for external monitors.

CI smoke

Dashboard client code is tested against a mock Unix socket:

cargo test -p flock-dashboard --test integration

Included in ./scripts/verify.sh.

What Flock is / is not

Flock is

• A coordination runtime — pressure-field scheduler, typed blackboard, episode logs
• A plugin harness boundary — FlockPlugin::verify_goal drives the default flock run loop
• An in-tree multiplexer — HerdR-shaped NDJSON socket API + PTY panes
• A topology evolution loop — flock evolve mutates wake maps from episodes
• Governance-aware — flock.toml hooks, tool pipeline, drift-check manifest

Default flock run uses deterministic plugins (gridworld, shell). The scheduler wakes agents from substrate signals — not a manager LLM.

Flock is not

• An OpenCode / Claude Code clone — no drop-in coding agent with 75 providers on the hot path
• A meta-harness wrapper — Flock does not wrap external harnesses; it is the runtime
• A workflow DSL — coordination is the pressure field, not hand-drawn graphs
• A chat router — agent-to-agent NL handoffs are intentionally forbidden

Honest adoption path

Flock deliberately does not chase OpenCode/Claude Code feature parity — coordination runtime and honest scope are the product.

Verify

The single verification entry point is ./scripts/verify.sh:

• cargo fmt --check
• cargo clippy --workspace --all-targets -- -D warnings
• cargo hack check --workspace --each-feature --no-dev-deps
• cargo test --workspace
• Release build + CLI smoke tests (run, json, rah-demo, acp, swarm-demo)
• Benchmarks: stigmergy ablation, govcraft acceptance, topology ablation
• Documentation smoke: ./scripts/smoke-docs.sh

./scripts/verify.sh
flock drift-check

CI runs the same script on every PR (.github/workflows/ci.yml).

Coordination model

Flock agents coordinate through the environment, not dialogue. Work flows via typed blackboard slots, decaying pheromone zones, and scheduler wake pressure — never through conversation loops, router LLMs, or handoff chains that re-encode state in natural language.

The substrate is the coordination protocol. Agents read signals, deposit completion, and wake when dependency pressure crosses a threshold.

Substrate primitives

Blackboard (typed slots)

Shared JSON slots keyed by name. Plugins declare expected slots in their manifest; the runtime writes last_observation after each dispatch. Plugins access slots through PluginContext::blackboard_set / blackboard_get.

Pheromone zones

Zone-keyed signal maps with exponential decay (PheromoneField). Each zone holds named signals (completion, activity, coordination, …). Strength accumulates on deposit and decays each scheduler tick.

Perception radius

CoordinationContext::perception_radius bounds how far an agent “sees” field signals. Today this gates boids-style coordination deposits; future plugins can filter reads by radius.

Pressure field and wake

PressureScheduler holds a pending task queue. Each task has:

• zone — where it runs and where completion is deposited
• dependencies — (zone, signal) pairs that must read above zero
• base_pressure — intrinsic urgency (capped by dependency pressure)

Wake pressure = min(base_pressure, min(dep signals)), boosted by multiplexer deposits. Tasks dispatch when pressure ≥ wake_threshold.

Completion and dependency signals

When a plugin returns NextAction::Complete or Halt, the scheduler deposits completion into the task’s zone. Retries and delegates deposit completion on the source zone, then enqueue dependents that wait on that signal.

Allowed vs forbidden patterns

Typed handoffs use TaskDescriptor payloads and blackboard slots — not prose.

Coordination flow

flowchart TB
    subgraph encode["Encode"]
        G[Goal] --> P[Plugin.encode_task]
        P --> T[TaskDescriptor]
    end

    subgraph scheduler["PressureScheduler"]
        T --> Q[Pending queue]
        Q --> RP[refresh_pressure]
        RP --> DEP{deps satisfied?}
        DEP -->|no| DEFER[deferred]
        DEP -->|yes| DISPATCH[dispatch_ready]
        DISPATCH --> HOST[RunHost.spawn]
    end

    subgraph substrate["Substrate"]
        HOST --> OBS[observation]
        OBS --> BB[Blackboard.set]
        OBS --> DEPOSIT[pheromone deposits]
        DEPOSIT --> FIELD[PheromoneField]
        OBS --> COORD[boids coordinate]
        COORD --> FIELD
    end

    subgraph verify["Verify"]
        OBS --> V[Plugin.verify_goal]
        V --> R[AgentReport]
        R -->|Complete| COMP[deposit completion]
        COMP --> FIELD
        R -->|Retry/Delegate| ENQ[enqueue dependent]
        ENQ --> Q
    end

    FIELD --> RP

    class G,P,T,Q,RP,DISPATCH,HOST runtime
    class OBS,BB,DEPOSIT,FIELD,COORD substrate
    class V,R,COMP,ENQ gate

Scheduler-primary run

FlockEngine::run_goal drives the loop:

1. Encode initial task from plugin manifest primary zone
2. Tick field decay → refresh pressure → dispatch ready batch (parallel, budget-limited)
3. Read host output → apply pheromone deposits → coordinate (boids) in plugin zone
4. Verify via plugin → deposit completion → enqueue retries/delegates
5. Snapshot field, topology, wake stats into episode JSON

Evolve and multiplexer deposits

flock evolve reads episode logs (pheromone_snapshot, wake_stats, environment_fingerprint) to mutate topology — coordination quality becomes fitness pressure on harness shape.

Remote observations may include pane deposits:

{"pheromone_deposits": [{"zone": "herdr", "signal": "activity", "amount": 0.5}]}

These feed herdr_wake_boost, waking stalled tasks when panes report activity.

Reading order

• Memory architecture — hot/warm/cold layers
• Organism model — genome, circulation, immune gate
• Quickstart — first episode

Memory architecture

Flock memory is the coordination substrate plus durable episode artifacts — not a vector store or chat transcript archive.

Layers

Today (Phase 0)

flock run --goal "reach target" --plugin gridworld   # → .flock/episodes/<id>.json
flock replay --episode .flock/episodes/<id>.json
flock replay --continue-run --episode .flock/episodes/<id>.json

Working state: flock_read_blackboard, flock_deposit_signal during live episodes (MCP tools).

Planned

Phase 1 adds flock-memory, MCP flock_recall / flock_remember / flock_query_field_history, and optional SQLite backend with JSON mirror.

What never goes in the database

• Live pheromone ticks (stay in-process)
• Conversation transcripts for coordination
• Vector embeddings (deferred)

See Coordination model for the coordination protocol.

Organism model

Flock treats the harness as a living organism: genomes express coordination parameters, circulation vitals track field health, and an immune gate rejects harmful topology mutations.

Status: Phases 1–4 complete (circulation, DNA lineage, immune gate, per-zone expression).

Architecture

flock-core/organism.rs     DNA types + circulation vitals + zone expression
flock-substrate/pheromone  per-zone decay (fallback to global lambda)
flock-runtime/circulation  vitals + immune_fever tracking
flock-runtime/engine.rs    vitals + genome_id + fever + decay wire-through
flock-evolve/genome.rs     lineage + crossover + archive reconstruction
flock-evolve/immune.rs     corpus threat detection + auto_reject
flock-evolve/mutator.rs    crossover + cold-zone decay adjustment
flock-cli/organism_cmd.rs  flock vitals | flock genome list|lineage

Organism loop

flowchart LR
    RUN[flock run] --> VITALS[circulation vitals]
    VITALS --> EP[episode JSON]
    EP --> EV[flock evolve]
    EV --> IMM[immune_report]
    IMM -->|accept| ARCH[genome archive]
    IMM -->|reject| QUAR[quarantine]

    class RUN,VITALS,EP runtime
    class EV,ARCH evolve
    class IMM,QUAR gate

1. FlockGenome expresses coordination + decay params at episode end
2. PheromoneField circulation → CirculationVitals in episode
3. flock evolve mutates or crossover (Pareto ≥ 2) → immune_report() gates accept
4. Quarantined genomes excluded from archive.nearest() seed
5. Per-zone decay tuned from proposer cold-zone heatmap

CLI

flock run --goal "reach target" --plugin gridworld
flock vitals
flock evolve --episodes 10
flock genome list
flock genome lineage <genome_id>

Phase completion

flux-grid (optional)

• Feature: flock-substrate/flux-grid (vendored 64×64 Stigmergy grid)
• Not enabled in default builds — zone-keyed PheromoneField remains default substrate
• Enable for experiments: cargo build -p flock-substrate --features flux-grid

Known deferred

• flux-grid in swarm-demo default path
• Full parent_ids lineage CLI (crossover sets parent_ids; CLI shows primary parent_genome_id only)
• RAH_MAX_DEPTH in flock-core (cycle avoidance with flock-evolve ↔ flock-rah)

See also

• Coordination model — substrate and scheduler
• Quickstart — first episode
• Episode flywheel on Introduction

CLI reference

Generated from flock --help (snapshot-tested in crates/flock-cli/tests/cli_help_snapshot.rs).

Top-level commands

flock run

flock run --goal <GOAL> [--plugin gridworld] [--rlm] [--max-steps 8]
          [--audit <PATH>] [--json] [--mcp] [--model <URL_OR_NAME>]
          [--genome <ID>] [--seed-archive] [--archive .flock/topology_archive.json]

--genome or --seed-archive seeds topology/coordination from the evolve archive before the run. Episode logs include a genome_seed event.

--model mock uses the deterministic stub. HTTP URLs and named providers require building with --features llm-http. The model is used only on the plugin verify path or RLM loop — never in PressureScheduler wake decisions.

flock remote

flock remote --goal <GOAL> [--plugin gridworld] [--socket <PATH>]
             [--ssh user@host] [--stub] [--audit <PATH>]

Governance pipeline (with_governance) applies on the remote hot path. Audit JSONL optional via --audit.

flock telemetry

flock telemetry [--limit 20] [--db <PATH>]
flock dashboard --history [--limit 20]

Headless query of dashboard telemetry (sessions, agent transitions, vitals snapshots). No TTY required.

flock evolve

flock evolve [--episodes 10] [--workspace .flock/episodes] [--hook rust|seed-only]

Output includes gen0_fitness, final_fitness, and fitness_delta. See repository docs/demo/evolve-proof.md.

flock mcp

flock mcp

Stdio JSON-RPC: initialize, tools/list, tools/call. See MCP tools.

flock plugin install

flock plugin install --from <DIR>
flock plugin install --git <URL> [--name <NAME>]

Installed plugins register automatically via plugins.toml and build.rs — no registry.rs edit.

Help snapshots

UPDATE_SNAPSHOTS=1 cargo test -p flock-cli --test cli_help_snapshot

MCP tools

Flock exposes a progressive-disclosure MCP surface: meta-tools for discovery, compact listings in tools/list, and full schemas on demand via flock_describe_tool.

Registry: crates/flock-runtime/src/mcp/registry.rs
Stdio server: flock mcp
Live episodes: flock run --mcp → FlockEngine::call_mcp_tool

Discovery flow

flowchart LR
    A[Agent starts] --> B{flock_discover_tools<br/>or flock_search_tools}
    B --> C[flock_describe_tool]
    C --> D[Invoke operational tool]
    D --> E[Governance + trace]

    class A runtime
    class B runtime
    class C substrate
    class D substrate
    class E gate

1. Discover — flock_discover_tools returns domain-indexed tool cards (no full schemas).
2. Search — flock_search_tools with query (and optional domain) narrows by intent.
3. Describe — flock_describe_tool with name returns full schema, preconditions, side effects, examples.
4. Invoke — tools/call or live mcp_tools observation payload.

Meta-tools are always listed with full schemas. Operational tools in tools/list use compact cards (call flock_describe_tool for parameters).

Meta tools

Operational tools

All operational tools are in LIVE_TOOL_NAMES for flock run --mcp.

Start the server

flock mcp

Wire your MCP client to stdin/stdout JSON-RPC. Cursor config example in Cursor setup.

Example: discovery sequence

{"name": "flock_search_tools", "arguments": {"query": "deposit", "domain": "substrate"}}

{"name": "flock_describe_tool", "arguments": {"name": "flock_deposit_signal"}}

{"name": "flock_deposit_signal", "arguments": {"zone": "grid", "signal": "coordination", "amount": 2.0}}

Example: live episode

Observation payload for flock run --goal "..." --plugin gridworld --mcp:

{
  "mcp_tools": [
    {
      "tool": "flock_deposit_signal",
      "args": { "zone": "grid", "signal": "coordination", "amount": 2.0 }
    }
  ]
}

Trace JSONL emits mcp_discovery for meta-tools and mcp_tool for operational calls. Governance pre/post hooks apply on the hot path.

Design principles

Adding a tool

1. Add ToolSpec in registry.rs and register in all_tool_specs().
2. Add handler in handlers.rs and route in call_tool_with_registry.
3. Add name to LIVE_TOOL_NAMES if live episodes should expose it.
4. Update this page and run cargo test -p flock-runtime.

See also MCP overview and Agent guide.

Socket API

Flock exposes a newline-delimited JSON (NDJSON) API over a Unix domain socket. The in-tree flock-multiplexer server implements HerdR-compatible automation methods; flock-herdr is the NDJSON client.

Source: crates/flock-multiplexer/src/api.rs · HerdR-compatible NDJSON automation (external herdr binary not required)

Connect

Ensure the server is running:

flock multiplexer ensure
# or
flock herd server

Example request:

{"id": 1, "method": "ping", "params": {}}

Example response:

{"id": 1, "result": {"type": "pong", "version": "...", "protocol": "..."}}

Errors use {"id": ..., "error": {"code": "...", "message": "..."}}.

Method catalog

Methods marked Stream return an initial result then additional NDJSON event lines on the same connection.

CLI mapping

Agent detection

Screen heuristics detect Claude, Codex, and Cursor agent states (idle / working / blocked). Hooks via pane.report_agent provide authoritative state when integrations are installed.

Live handoff

server.live_handoff writes ~/.config/flock/sessions/handoff.json, spawns a replacement daemon, and releases the socket. PTY processes are not preserved across handoff — layout and visible text restore only.

Testing

cargo test -p flock-multiplexer
cargo test -p flock-herdr
flock multiplexer ensure
flock herd status

See Daily driver loop for the operator workflow.

Agent guide

Onboarding for AI agents operating Flock panes — Claude Code, Codex, Cursor, and Pi. Paste this page (or llms.txt) into your agent context before driving Flock.

What you are operating

Flock is a coordination runtime, not a chat router. Agents coordinate through:

• Blackboard — typed JSON slots
• Pheromone field — decaying zone signals that wake the scheduler
• Multiplexer panes — PTY sessions with NDJSON socket control

Do not coordinate via agent-to-agent natural language. Use substrate tools and pane deposits.

Install (operator machine)

curl -fsSL https://raw.githubusercontent.com/Alphabetsoup16/Flock/main/install.sh | bash
export PATH="$HOME/.cargo/bin:$PATH"   # if install.sh used cargo install

Verify:

flock run --goal "reach target" --plugin gridworld
ls .flock/episodes/

Daily-driver loop

flock multiplexer ensure          # start socket server
flock dashboard                   # ratatui control tower (optional)
flock herd status                 # agent states across panes
flock run --goal "..." --plugin shell --mcp

Episode flywheel: flock run → .flock/episodes/*.json → flock evolve → flock drift-check.

Agent-specific pane setup

Spawn via socket API:

{"id": 1, "method": "agent.start", "params": {"name": "claude", "focus": true}}

Or CLI: flock herd attach --pane <id> after flock herd status.

MCP workflow (Cursor and headless agents)

1. Operator wires flock mcp in MCP settings (Cursor setup).
2. Agent calls flock_search_tools → flock_describe_tool → invoke.
3. For live substrate during episodes, operator runs flock run --mcp.

Key tools: flock_deposit_signal, flock_read_blackboard, flock_topology_snapshot, flock_multiplexer_status.

Full catalog: MCP tools.

Socket automation (HerdR-shaped)

Connect to ~/.config/flock/flock.sock. One JSON request per line.

{"id": 1, "method": "ping", "params": {}}
{"id": 2, "method": "agent.list", "params": {}}
{"id": 3, "method": "pane.read", "params": {"pane_id": "w1:p1", "lines": 40}}
{"id": 4, "method": "events.wait", "params": {"match_event": {"agent_status": "idle"}, "timeout_ms": 60000}}

Full method table: Socket API.

Diagnosis recipes

Flags agents should know

Do not invent flags — verify with flock --help or CLI reference.

Skills

Flock scans .flock/skills/ and ~/.cursor/skills/ on flock run. Author skills as SKILL.md with frontmatter; install via Cursor skills UI or copy into project.

Honest limits

• Flock is not OpenCode/Claude Code — no built-in 75-provider coding agent on the hot path.
• Default flock run uses deterministic plugins; wire your LLM via MCP or panes.
• Agent-to-agent chat coordination is forbidden by design.

See What Flock is / is not.

Cursor setup

Use Flock in Cursor via MCP (flock mcp). ACP is available for experiments but MCP is the primary editor path.

Install

git clone https://github.com/Alphabetsoup16/Flock.git && cd Flock
./install.sh
export PATH="$PWD/target/release:$PATH"

Wire MCP in Cursor

Add a server entry to Cursor MCP config (Settings → MCP, or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "flock": {
      "command": "/path/to/Flock/target/release/flock",
      "args": ["mcp"]
    }
  }
}

Set command to your built target/release/flock path. Restart Cursor.

Discovery flow: flock_search_tools → flock_describe_tool → invoke. Full catalog: MCP tools.

First smoke

flock run --goal "reach target" --plugin gridworld
flock run --goal "reach target" --plugin gridworld --json
flock mcp

MCP vs ACP

Skills and memory

Skills: .flock/skills/ and ~/.cursor/skills/ are both scanned on flock run.

Memory is the substrate (blackboard, field, episodes) — see Memory architecture. Vector RAG is deferred; hybrid SQLite/Turso plan is documented in-repo under docs/MEMORY_ARCHITECTURE.md (not yet migrated to this book).

Agent onboarding

For paste-into-agent context: Agent guide.

MCP overview

Flock exposes stigmergy and harness tools via flock mcp (stdio CLI) and live episodes (flock run --mcp).

Start the server

flock mcp

Wire your MCP client to stdin/stdout JSON-RPC (same surface as cargo run -p flock-mcp).

Quick tool list

Full catalog with live-column and governance notes: MCP tools.

Live episode example

{
  "mcp_tools": [
    {
      "tool": "flock_deposit_signal",
      "args": { "zone": "grid", "signal": "coordination", "amount": 2.0 }
    }
  ]
}

Governance pre/post hooks apply on the MCP hot path when --mcp is set.

Editor integration

• Cursor setup — wire MCP in Cursor settings
• Agent guide — onboarding for Claude/Codex/Cursor/Pi