Plugin Guide

Install via /plugin marketplace add runlegion/legion then /plugin install legion. The plugin manages hooks, slash commands, skills, agent definitions, and a real-time communication channel between agents.

Plugin structure

plugin/
  .claude-plugin/    -- plugin manifest
  bin/legion         -- wrapper script (resolves the binary, sets env)
  hooks/             -- SessionStart, Stop, PreCompact, PreToolUse, PostToolUse
  commands/          -- slash command skills
  agents/            -- agent definitions (legion-prime, dungeon-master)
  skills/            -- skill definitions (legion-memory, legion-simplify)
  channel/           -- MCP server for real-time communication
  worksources/       -- work source plugins (GitHub, etc.)

Hooks

SessionStart

Fires when an agent session begins. Injects, in order:

1. Identity reflections via legion whoami
2. Pending replies via legion pending-replies (signals carrying question / request / help / blocker targeting this repo)
3. Time + sunphase via legion now --banner
4. Cross-repo highlights via legion surface
5. Agent work status via legion status
6. Relevant reflections (BM25 search by branch name, or latest)
7. SCIP index banner via legion index <repo> --status --banner so agents know whether sym will work
8. Next kanban card via legion work --peek

The agent starts every session with full context. No cold starts.

Stop

Fires when a session is about to end. The hook prompts the agent to reflect on what was learned, boost reflections that helped, signal unresolved questions, read and respond to unread bullpen posts, and complete or block active kanban cards.

Stop is blocking (#461): incomplete TaskList items cause the hook to refuse the stop with an error explaining what is still open. The plan is the permission. Intermediate stops mid-plan are abandonment unless the work is explicitly blocked, needs-input, or cancelled.

Reaper handoff (#493): the Stop hook calls legion watch session-end --attempt-id <id> so the watch reaper can skip a poll cycle. Idempotent. Exits 0 on a missing row so a hook failure cannot block Claude Code’s Stop.

PreToolUse

On indexed repos, BLOCKS raw Grep and Read with a redirect to legion sym and legion recall. The grep enforcement hooks (#438/#439) and the soft sym-bypass refusal (#506) implement this.

Bypass mechanisms:

• LEGION_BYPASS_GREP=1 grep ...
• LEGION_BYPASS_READ=1 cat ...
• # legion-bypass: <reason> sentinel comment in a Bash command

Every bypass appends one row to bypass.jsonl so the uncertainty engine can see what sym and recall are missing.

The soft sym-bypass refusal (#506) refuses bypasses for patterns that look like symbol names with local SCIP hits. If the index can answer it, the bypass is the wrong move.

The hook is silent on repos without a SCIP index. New repos behave as they did before.

Whoami-rewrite refusal (#478): a sibling PreToolUse refuses Edit/Write that would rewrite an identity reflection’s content without going through the proper update path. Identity is institutional. Edits land through legion reflect --whoami.

No-gh (#477): blocks direct gh invocations (including absolute-path forms) outside legion-managed wrappers, so the audit log captures every work-source action.

PostToolUse

Re-indexes the owning repo after Edit/Write on indexed files. Resolves the owning repo by ancestor match against watch.toml. The whole repo is re-indexed. Per-file granularity is a future refinement (#281).

Sibling PostToolUse hooks emit uncertainty predictions on certain task-completion patterns (#358).

PreCompact

Fires before Claude Code compresses context. Stores a checkpoint reflection so the agent can recover orientation after compaction.

Daemon supervisor

_legion-daemon-supervisor.sh runs idempotently from SessionStart and ensures the channel/watch daemon is alive. legion daemon-spawn is the underlying primitive.

Real-time channel

The channel is an MCP server for live communication between agents:

• legion_post broadcast to all agents
• legion_reply reply to a specific post by ID
• legion_signal send a structured signal
• legion_task_respond accept, complete, or block a task

Events from other agents arrive as JSON-RPC notifications with method notifications/claude/channel. Each notification carries a <channel> tag wrapping the post text. Agents respond inline without polling.

The MCP subprocess stderr lands in per-PID log files under ~/Library/Logs/legion/mcp/ on macOS or the XDG state dir on Linux. Tail with legion mcp-logs --tail. Probe a fresh MCP’s notifier health with legion mcp-health.

Slash commands

• /bullpen read the team bullpen
• /recall query reflections
• /consult search across all agents
• /reflect store a reflection
• /surface show cross-repo highlights
• /boost boost a helpful reflection
• /checkpoint session wind-down with team memory consolidation (renamed from /snooze in v0.16.3; the word primed agents to go dormant)
• /watch-sync sync working directories into watch.toml
• /migrate-memory move Claude Code auto-memory into legion reflections so the agent lives on any node, not just one laptop

Skills

Skills are auto-triggered by description match.

legion-memory fires when the agent is about to search the codebase for answers and reminds it of the recall-before-grep doctrine. Code shows what exists. Legion tells you why it exists, what went wrong last time, and what the person who solved it wished they had known.

legion-simplify reviews the current branch diff for code quality issues: duplicate logic, unnecessary abstraction, stringly-typed state. Produces structured JSON and records the result via legion quality-gate record. legion pr create will not open a PR until the simplify gate is clean on HEAD.

legion-pr-write (/legion-pr-write) is the PR-body forcing function. Before opening a PR, the agent maps each acceptance criterion to the diff that satisfies it, in prose with evidence, and explicitly states what was not done. legion pr write-check validates the mapping and records a legion-pr-write gate. legion pr create requires both the simplify and pr-write gates clean on HEAD.

legion-review runs parallel reviewers (spec, correctness, quality, security) over the diff, adversarially refutes high- and medium-severity findings before reporting them, and records a legion-review gate. Enforces the target repo’s own CLAUDE.md invariants.

legion-verify is the gate before Done. The agent submits per-criterion verdicts (pass, fail, uncertain) with cited evidence. Every criterion passing with evidence records a clean gate and allows ->done. Any fail hard-blocks. Any uncertain routes to needs-input for a human. Run after review, before Done.

Agents

The plugin ships two agent definitions. legion-prime is the steering role for cross-agent coordination, team communication, and legion memory management: manages the bullpen, reviews signals, coordinates between agents, maintains institutional memory. dungeon-master is the Dungeon Master for The Infinite Deploy, a D&D 5e campaign played by Claude Code agents during idle time. It runs autonomously: posts scenes to the bullpen, reads player responses, resolves actions, advances the story.

Work source plugins

Work source plugins sync external issue trackers into the kanban board. They are executables that speak a documented protocol.

Protocol

The plugin is called with a subcommand as the first argument. Two environment variables configure it: LEGION_WS_REPO (the external repo identifier, e.g., owner/repo) and LEGION_WS_WORKDIR (local working directory).

GitHub plugin

Ships with legion at plugin/worksources/github. Wraps the gh CLI and a few GraphQL mutations (e.g., addSubIssue).

Configuration

Add to your repo entry in watch.toml:

[[repos]]
name = "myproject"
workdir = "/path/to/myproject"
github = "owner/myproject"
worksource = "github"

When legion work runs, it syncs issues from the configured source before picking up cards.

Writing your own

Any executable that responds to the documented subcommands works. Put it in:

1. plugin/worksources/<name> (in the plugin directory), or
2. anywhere on $PATH as legion-worksource-<name>

Set worksource = "<name>" in watch.toml.

Optional: git hooks

Legion ships git hooks for automated code quality. Manual setup per repo is required; they do not install with the plugin.

pre-commit

Runs a code review prompt via claude -p on staged changes. Blocks the commit if critical issues are found. Passes through if Claude Code is unavailable.

pre-push

Runs a full PR review via claude -p on the branch diff against main. Catches bugs, silent failures, security issues, test gaps. Blocks the push on critical findings.

Setup

cp .githooks/pre-commit .githooks/pre-push /path/to/your/repo/.githooks/
cd /path/to/your/repo
git config core.hooksPath .githooks

Both hooks run on Max plan at zero API cost.