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

Agent	Start in pane	Hook install
Claude Code	`claude` in pane	`flock integration install claude`
Codex	`codex` in pane	`flock integration install codex`
Cursor	Cursor terminal or `cursor` CLI	MCP via `flock mcp` (see below)
Pi	`pi` in pane	Use Pi programmatic/RPC mode in pane

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)

Operator wires flock mcp in MCP settings (Cursor setup).
Agent calls flock_search_tools → flock_describe_tool → invoke.
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

Symptom	Check	Fix
No socket	`flock herd status` fails	`flock multiplexer ensure`
Agent stuck “working”	`flock herd agent explain --pane <id>`	Wait or `pane.report_agent` hook
MCP tools missing	Cursor MCP panel	Restart Cursor; verify `flock mcp` path
Episode not written	`flock run` exit code	Run with `--json`; check plugin goal
Drift rejected	`flock drift-check` output	Review `flock.toml` governance section

Flags agents should know

Command	When
`flock run --json`	Headless NDJSON contract (episode_start … episode_end)
`flock run --mcp`	Live MCP tools on running engine
`flock run --rlm`	RLM verify/act loop
`flock remote --ssh user@host`	Remote pane farm
`flock evolve --episodes N`	Topology mutation from corpus

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.

Keyboard shortcuts

Flock