Legion

Context monitoring hooks for Claude Code plus Codex Legion skills

Legion installs Claude Code hooks, agents, and slash commands into ~/.claude/ by default. Install matching Codex skills into ${CODEX_HOME:-~/.codex}/skills/ with --codex (Codex-only) or --claude --codex (both targets). The Claude side provides context monitoring and multi-agent orchestration; the Codex side exposes the matching Legion roles and helper workflows as explicit skills.

Features

• 5 hooks — statusline progress bar, context usage monitor, teammate idle/completed state, MCP advisor
• 3 agents — context, architect, executor
• 4 slash commands — /legion:auto, /legion:codebase, /legion:uninstall, /legion:update
• 3 Codex skills — $legion-context, $legion-architect, $legion-executor
• Zero dependencies — only Node.js built-ins

Requirements

• Node.js >= 18
• Claude Code with agent teams enabled for hooks and slash commands
• Codex for Legion skills (optional, installed with --codex)

Installation

via npm (recommended)

npm install -g legion-cc
# or
npx legion-cc

This installs:

• Claude assets into ~/.claude/
• Codex skills into ${CODEX_HOME:-~/.codex}/skills/ (when --codex is passed)

Manual

git clone https://github.com/vladyslavblackmoore/legion.git
cd legion
node bin/install.js

Options

node bin/install.js --force     # overwrite without content check
node bin/install.js --dry-run   # preview changes without writing
node bin/install.js --codex     # install only Codex skills
node bin/install.js --claude --codex # install Claude assets + Codex skills
node bin/install.js --uninstall # remove Legion Claude files (default target)
node bin/install.js --uninstall --codex # remove only Codex Legion skills
node bin/install.js --uninstall --claude --codex # remove Claude files + Codex skills
node bin/install.js --codex-home /tmp/codex # custom Codex home for skills
node bin/install.js --help      # show help with full file list

--uninstall --codex removes only Legion-owned subdirectories under ${CODEX_HOME:-~/.codex}/skills/. It does not delete the shared skills root.

Usage

Slash Commands

| Command | Pipeline | When to use | |---------|----------|-------------| | /legion:auto | Auto-select | Scores complexity (1-10) and picks simple or full pipeline | | /legion:codebase | Codebase analysis | Analyze and document the project structure | | /legion:uninstall | — | Remove all Legion files and hooks | | /legion:update | — | Update Legion to the latest version |

Examples:

/legion:auto Fix the authentication bug in login flow
/legion:auto Add OAuth2 support to the API
/legion:codebase

Codex Skills

Use the installed Legion skills explicitly in Codex when you install with --codex:

$legion-context Collect and format project context.
$legion-architect Analyze architecture and design solutions.
$legion-executor Execute the approved plan.

Architecture

Hooks

Installed into ~/.claude/hooks/. All hooks are standalone Node.js scripts that read JSON from stdin and always exit 0.

| Hook | Event | Function | |------|-------|----------| | legion-statusline.js | statusLine | Progress bar with GSD-scaling | | legion-context-monitor.js | PostToolUse | Context usage warnings at 30%/20%/10% | | legion-teammate-idle.js | TeammateIdle | Tracks agent idle state | | legion-task-completed.js | TaskCompleted | Tracks completed tasks | | legion-mcp-advisor.js | SessionStart | MCP server awareness injection |

Agents

| Agent | Model | Role | |-------|-------|------| | context | sonnet | Project context collection and formatting | | architect | opus | Architectural analysis, design, and planning | | executor | opus | Code writing, file modification, parallel execution |

Codex Skills

Installed into ${CODEX_HOME:-~/.codex}/skills/ when --codex is selected. Each skill maps to a Legion role or helper workflow and is configured with allow_implicit_invocation: false, so invoke them explicitly via $legion-*.

Pipelines

Simple (score 1-4, 2 teammates): context → executor

Full (score 5-10, 3 teammates): context → architect → executor (parallel execution waves)

Codebase: parallel teammates analyze the project and write structured documentation. Generates architecture.md, conventions.md, files.md, dependencies.md, api.md to .legion/codebase/.

MCP Enforcement

Optional per-project config at .legion/config.json:

{
  "mcp": {
    "enforce": true,
    "servers": ["terraform", "aws", "git"]
  },
  "subagents": {
    "enforce": true,
    "minCount": 5,
    "types": ["Explore", "Plan", "general-purpose", "context", "architect", "executor"]
  }
}

License

MIT — Vladyslav Blackmoore