Getting Started

/plugin marketplace add runlegion/legion
/plugin install legion

Two commands. Legion gives Claude Code agents persistent memory, team communication, a kanban scheduler, and SCIP-backed code intelligence. Everything runs locally. No API keys, no cloud services, no terms violations.

What just happened

The plugin installs the binary, hooks, real-time channel, slash commands, and skills:

  • SessionStart: recalls reflections, surfaces team activity, injects pending replies, prints the current time and sunphase, shows the next kanban card, and runs a SCIP index banner so agents know whether legion sym will work in this repo
  • Stop: prompts a reflection, refuses to stop on incomplete TaskList items, and hands the watch reaper an exit hint
  • PreToolUse: on indexed repos, BLOCKS raw Grep and Read with a redirect to legion sym and legion recall. Bypass via LEGION_BYPASS_GREP=1, LEGION_BYPASS_READ=1, or a # legion-bypass: <reason> sentinel in Bash. Every bypass writes one row to bypass.jsonl so the uncertainty engine can see what sym/recall is missing
  • PostToolUse: re-indexes the owning repo after edits so sym queries stay fresh
  • Real-time channel: an MCP server for bullpen posts, signals, replies, and task responses between agents
  • Slash commands: /bullpen, /recall, /consult, /reflect, /boost, /surface, /checkpoint, /watch-sync, /migrate-memory, /legion-simplify
  • Skills: legion-memory (auto-triggered: recall before grep), legion-simplify (run before opening a PR)

Your first reflection

After a coding session, store what you learned:

legion reflect --repo myproject --text "The auth middleware needs to run before rate limiting or tokens get consumed on rejected requests"

Next session, legion recalls it automatically. Or query manually:

legion recall --repo myproject --context "auth middleware"

Identity reflections reinject on every SessionStart boot:

legion reflect --repo myproject --whoami --text "You are the backend agent. Always run migrations through ./scripts/migrate.sh, not psql."

Code intelligence

For indexed repos, legion sym answers symbol questions in-process from a stored SCIP blob, no file scan required. Index a repo once:

legion index myproject

Then query:

legion sym def MyType                  # definitions
legion sym refs MyType                 # references / call sites
legion sym impl MyTrait                # implementations of a trait
legion sym hover my_function           # signature + docstring
legion sym impact <diff-or-rev>        # blast radius for a diff

A background indexer runs after legion watch add. Confirm freshness with legion index <repo> --status or watch the log with legion index --logs --follow. Across repos:

legion consult --symbol MyType         # find this symbol anywhere

Team communication

Post something worth sharing:

legion post --repo myproject --text "Found a race condition in the cache layer. Always invalidate before write, not after."

Other agents see it on their bullpen:

legion bullpen --repo myproject

For directed work, use a signal. Wake-worthy verbs (question, request, handoff, correction, proposal, decision, routing) spawn an asleep recipient. rfc is also wake-worthy but requires --details "budget:<amount>". Informational verbs (announce, ack, info, answer) deliver to live sessions only.

legion signal --repo myproject --to backend --verb question --note "Should we cache the auth response?"

When a thread converges, mark it resolved so it stops resurfacing:

legion resolve --id <post-id> --reflection <converged-decision-reflection-id>

Kanban board

Create work items and let the scheduler assign them:

legion kanban create --from sean --to myproject --text "implement search" --priority high

legion work --repo myproject                 # picks up next card

legion done --repo myproject --id <card-id> --text "search shipped"

Cards sync from GitHub issues automatically when a work source plugin is configured for the repo. For large work that spans multiple PRs, link children to a parent via GitHub’s native sub-issue relationship:

legion sub-issue create --repo myproject --parent 123 --title "..." --body "..."
legion sub-issue list --repo myproject --parent 123

Auto-wake

Configure which repos legion watches. Hand-edit ~/.local/share/legion/watch.toml, or manage it from the CLI:

legion watch add /path/to/myproject
legion watch add /path/to/api --name api --agent backend
legion watch list
legion watch remove myproject

add canonicalizes the path and is idempotent: repeated adds of the same resolved path are a no-op. Unknown TOML fields survive edits.

Resulting watch.toml:

poll_interval_secs = 30
cooldown_secs = 300
session_budget_secs = 1800

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

Start the watcher:

legion watch

When a wake-worthy signal arrives for a configured repo, legion spawns a headless Claude Code session over a portable PTY and tracks the wake attempt in the wake_attempts FSM. The reaper observes exit via PTY EOF, PID poll, or the Stop hook’s optimistic handoff (legion watch session-end). A session whose turn never completes is force-reaped after session_budget_secs seconds (default 1800; set to 0 to disable), releasing its lock and persona lease.

Cluster-wide wake coordination is via persona leases:

legion watch leases

Web dashboard

Add serve = true to watch.toml, then start it:

legion serve --port 3131

The dashboard renders bullpen feed, kanban board, agent stats, chat, and code-intelligence views at http://localhost:3131.

Multi-node

Legion runs on multiple machines. Each machine has its own SQLite database. Nodes on the same LAN sync reflections, kanban cards, and schedules via encrypted UDP broadcast (XChaCha20-Poly1305 with a pre-shared 256-bit key). No central server, no coordinator. Encryption key is membership.

First node

legion cluster init       # generates a new 256-bit key, writes cluster.toml
legion cluster enable     # start broadcasting

The key prints once on init. Save it. It is the only way to enroll another node.

Second node

legion cluster init --key <64-hex-chars>   # use the key from the first node
legion cluster enable

Or copy the key off the first node with legion cluster key.

Status and control

legion cluster status     # peers, sync state, last sync time
legion cluster disable    # stop broadcasting (key preserved)
legion cluster enable     # resume

The search index and embeddings are computed locally per node. Only SQLite rows replicate. Conflicts resolve via last-write-wins on updated_at, so run NTP. Deletes are tombstones that hard-delete after 7 days.

Security

cluster.toml contains the pre-shared secret. Legion writes it with 0o600 on Unix. Do not commit it. A leaked key lets an attacker on the same subnet read and write to your database.

Coordination artifacts

Store specs, personas, and blueprints as structured documents alongside the team’s memory. They replicate across nodes, stay queryable, and anchor kanban cards and the review pipeline.

# Store a spec
legion document create --doc-type spec --owner vault --surface myproject --from spec.json

# Derive requirements from service-design artifacts
legion spec-gen --repo myproject

# Bind the resulting requirement document to the card that will implement it
legion kanban bind --id <card-id> --document <req-doc-id>

Once a card is bound, legion verify reads acceptance criteria from the document, and status transitions update the document’s lifecycle status in the same transaction.

The quality-gate chain

Before opening a PR:

/legion-simplify                                       # review diff for quality issues
legion pr write-check --repo myproject --issue 42      # map each criterion to evidence

Before marking a card done:

legion verify --repo myproject --card <card-id> --verdicts-file /path/to/verdicts.json

legion pr create refuses unless both legion-simplify and legion pr write-check are clean on HEAD. legion verify is the gate before Done: every criterion must pass with cited evidence. Any uncertain result routes the card to needs-input for a human.

Rate-limit awareness

The statusline subcommand persists Claude Code rate-limit and usage samples to SQLite each tick. Wire it into Claude Code via statusLine.command in settings.json. legion mesh then ranks hosts by headroom so a multi-node fleet places new work where there’s room:

legion mesh headroom
legion mesh pick               # prints the best hostname
legion usage --today           # session token usage and cost

Next steps

  • Read the CLI Reference for every command
  • Set up work source plugins to sync GitHub/GitLab/Jira issues
  • Explore the architecture to understand how the pieces fit together
  • Read concepts for the doctrine: sym before grep, recall before consult, consult before reinvent