Agent guide

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

What you are operating

Castellan 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/Castellan/main/install.sh | bash
export PATH="$HOME/.cargo/bin:$PATH"   # if install.sh used cargo install

Verify:

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

Daily-driver loop

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

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

Agent-specific pane setup

Agent	Start in pane	Hook install
Claude Code	`claude` in pane	`castellan integration install claude`
Codex	`codex` in pane	`castellan integration install codex`
Cursor	Cursor terminal or `cursor` CLI	MCP via `castellan 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: castellan herd attach --pane <id> after castellan herd status.

MCP workflow (Cursor and headless agents)

Operator wires castellan mcp in MCP settings (Cursor setup).
Agent calls castellan_search_tools → castellan_describe_tool → invoke.
For live substrate during episodes, operator runs castellan run --mcp.

Key tools: castellan_deposit_signal, castellan_read_blackboard, castellan_topology_snapshot, castellan_multiplexer_status.

Full catalog: MCP tools.

Socket automation (HerdR-shaped)

Connect to ~/.config/castellan/castellan.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	`castellan herd status` fails	`castellan multiplexer ensure`
Agent stuck “working”	`castellan herd agent explain --pane <id>`	Wait or `pane.report_agent` hook
MCP tools missing	Cursor MCP panel	Restart Cursor; verify `castellan mcp` path
Episode not written	`castellan run` exit code	Run with `--json`; check plugin goal
Drift rejected	`castellan drift-check` output	Review `castellan.toml` governance section

Flags agents should know

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

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

Skills

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

Honest limits

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

See What Castellan is / is not.

Keyboard shortcuts

Castellan