Legion

A local multi-agent bot for your desktop. Claude by default, plus OpenRouter for any model, and a VM for every agent when it needs one.

Status · Install · Orchestrate over MCP · Architecture · Contributing

Status

Legion is in beta: expect rough edges and the odd bug.

• Releases: prebuilt Windows releases are on GitHub Releases. A release install updates itself (Updates).
• Tested: the automated tests cover the core, app, agents, rooms, Library, board, MCP, approvals, updater and installer. Every push to main and every pull request runs all of them on Windows, Ubuntu and macOS (how CI works).
• Project board: in daily use on the maintainer's PC. Screen-reader, display-scale and crash checks are still open.
• Browser tool: agents have used it on the maintainer's Windows PC. Web search goes through Claude's own search tool unless you pick a search provider with your own key in Settings, Providers.
• BSV mode: tested against fake wallets only. Mainnet is built and OFF until you switch it on.
• Blender bridge: local mode (headless Blender on your computer) and Legion's own managed Blender copy ("Get Blender for Legion") are in use on the maintainer's Windows PC. Cloud VM mode, Live mode (your open Blender through the add-on) and the official extension install are not yet tried on a real Blender.
• Cloud VMs (boat.dev): agents have started and used VMs.
• Installer: not code-signed and not widely tested. Expect SmartScreen or antivirus prompts.
• macOS and Linux (experimental): the one-line installer sets Legion up, and since 0.3.5 that install updates itself. Rehearsed on macOS (Apple silicon and Intel) and Linux (x64 and arm64) in CI; not yet tested by hand on a real Mac. The maintainer uses Windows, so feedback and bug reports from Mac and Linux are very welcome: report a bug.
• Hermes (optional): you can run Hermes as an agent. The automated tests use a stand-in for Hermes, and it has not yet been tried against a real one. Windows first; macOS and Linux are experimental.
• Models: Claude by default, plus OpenRouter with your own key. You can also add an address of your own for any server that speaks the OpenAI chat-completions format, such as vLLM or LM Studio. Settings, Providers has ready cards for OpenAI, DeepSeek, Ollama, LM Studio and vLLM. Codex is not offered (see Later).

• The automated tests use no network and no real Claude calls. They cover the core, the app, agents, rooms, the Lattice and Library, Projects with the work board, the browser tool, MCP orchestration, approvals, the updater and the Windows installer scripts.
• BSV mode has a read-only status check of a wallet on your computer, plus one spend tool that asks the wallet to pay only after your confirmations in Legion's confirm card, or the system dialog if it cannot open (testnet and mainnet). It is not verified against a real wallet or with real funds yet, until your checks are recorded. Legion has never been pointed at your funded wallet by its own code, tests or agents.
• The installer has not yet run on a wide range of Windows machines. Expect Windows SmartScreen or antivirus prompts for .cmd files.
• Updates are a separate matter from the installer: each one is checked against the maintainer's signature before it is applied.
• With OpenRouter, add your own key and run any model. An agent on another provider gets Legion's own tools, not Claude Code's file, shell or web tools; Settings, Providers lists what it cannot do. Its own agent shell, when you turn it on, runs Git Bash on Windows (cmd.exe when Git for Windows is not installed).

What it is

Legion runs several Claude agents from one desktop app, on your own machine.

• Each agent has its own persona, model policy, approval mode and working directory.
• An agent can start a cloud VM on boat.dev when a task needs one.
• Legion uses the Claude Code account you are signed in to: no extra logins or keys.
• Claude Code and Cowork can drive Legion too, over MCP.

• A small Node service on 127.0.0.1 does the work, and an Electron window sits on top.
• Agents run through the official Claude Agent SDK. Every existing agent runs on a Claude model by default.
• OpenRouter is a second provider: add your own key and run any model. Settings, Providers also takes an address of your own for a server that speaks the OpenAI chat-completions format. It has ready cards for OpenAI, DeepSeek, Ollama, LM Studio and vLLM too. Codex is not offered (see Later).

Features

The highlights: the Marshal leads an Order of 14 agents · agents ask each other for help · projects with a work board · shared long-term memory · a cloud VM per agent when a task needs one.

Your agents

• 14 ready-made agents: the Marshal (lead), Builder (coding), Scout (research) and eleven more, or make your own (The Muster).
• The Marshal leads the Order. It splits a request into tasks, hands each to the best agent and runs independent ones at once.
• Agents talk to each other. One can ask another and wait, or tell it and get the reply later.
• Rooms: group chats of agents and you (Rooms).
• Hermes as an agent (optional). Pick Hermes as an agent's model when it is installed on your computer. Claude works without it.
• A VM per agent, on demand, with a live screen preview (boat.dev VMs).

• Your own agents get a name, system prompt, model, approval mode and VM settings. Your edits to the Marshal's prompt are kept; the lead role applies on top. In a project, the Marshal works through the board's leader.
• Pair threads between two agents resume the same session, so repeat conversations stay cheap. Hop, rate and cycle guards stop runaway loops.
• Hermes keeps its own tools, model and sign-in and works on your computer with them. By default Legion shows the questions Hermes asks you as cards with Hermes's own buttons and passes your answer back unchanged. Legion cannot stop a Hermes read, web fetch or command that Hermes does not ask about; Hermes's own approvals setting decides what it asks, and the Doctor shows it. Hermes is off until you turn on Offer Hermes in Settings, Agent hosts; until then Legion does not look for it or start it. Once it is on, Legion starts Hermes only when an agent uses it or you open the Doctor or Settings, Agent hosts. A Hermes agent needs a folder outside Legion's data folder, and Hermes 0.22.3 or newer. Settings, Agent hosts has four switches (all off), a Contained profile and a watchdog (10 minutes by default). Hermes does not report cost, so Legion shows tokens. Details: docs/design/agent-host.md.
• Rooms have guards against runaway loops. Agents can propose creating a room or changing its members; each change waits for an Allow card that only you can answer in the app.
• Agents start, use and stop their own boat.dev VM. You get an "Open desktop" link. Idle VMs stop on their own, so billing pauses. Legion shows how long a VM has run today, and an optional cost estimate from the hourly price you enter (docs/VM-NOTES.md).

Getting work done

• Projects and a board. A project groups one job; its board holds the work items the agents pick up (docs/PROJECT-BOARD.md).
• Talk to a task while it works. Your message joins the run after the current step (docs/CHAT.md).
• Live progress under a running task: turn, tool, time and context in use, plus Claude's own checklist.
• Continue where it stopped at the turn limit, after a crash or a restart; the work is kept.
• Slash commands and a model picker in the composer (Slash commands and models).
• Orchestration over MCP: drive Legion from Claude Code, Cowork or Claude Desktop (Orchestrate over MCP).

• A project holds instructions, a folder, member agents, tasks, rooms and notes. Member agents can create, edit, move, claim and note board items; you mark them done, approve deletes and decide what runs. An optional project switch lets the Marshal start items in Doing.
• Agents give project work to members first. An agent outside the project can still help, without the project's folder, notes or board; the project's deny rules still apply to it. Whatever waits on you shows at the top of the agent list, whichever project you are viewing.
• For provider models, Enter queues a message instead (in order, shown above the composer). Ctrl+Enter interrupts the run and sends now. A stop, a failure or a reload pauses the queue instead of sending on its own. Each thread keeps its own half-typed draft, also across restarts.
• A run gets 200 turns by default. One that reaches the limit pauses on the model it was using; Continue carries on in the same conversation. A run cut short by a crash, a restart or a dropped connection offers Continue too.
• Claude Code connects over HTTP; Cowork and Claude Desktop connect over a stdio bridge.

Memory and context

• The Lattice and the Library: a shared knowledge graph the agents use as long-term memory (Lattice and Library).
• The house layer: rules every agent reads.
• Long conversations are compacted, not cut, and /compact does it on demand.
• Your Claude Code setup, partly inherited: settings, hooks and slash commands. Skills load only after you turn them on in Settings, Armory.

• The Library has an Inbox where you accept or reject what the agents save.
• The house layer holds your house rules, architecture decisions and guidance. A rule file that changes after it shipped is labelled as not approved until you approve it, and an approval lapses when the text changes again.
• Near the model's limit the conversation is compacted, and the thread says when. /compact takes an optional focus. A context readout shows how much of the window is in use (an estimate).
• Your Claude Code MCP servers and claude.ai connectors are not loaded unless you turn on claude.inheritMcp; add the MCP servers you want agents to have in Settings or config.json.

You stay in control

• Choose how much your agents ask. Settings, Gates has four presets. Claude agents follow Claude's own permission checks in every preset (a switch in Gates turns that off); agents on other providers use Legion's own checks:
  • Ask: every action asks. Read-only commands, and commands your own Claude Code allow rules allow, run without a card.
  • Accept edits: file edits run, everything else asks. For Claude agents this is Claude's accept-edits mode: file commands in your project, including rm, mv and cp, run too.
  • Smart: for Claude agents, Claude's own checker runs what it judges safe, blocks what it judges risky by itself (the block shows in the task) and asks you when it is unsure. For other providers, Legion asks before an action that reaches the web, deletes, cannot be undone, or that it cannot classify; tests and builds run without asking.
  • Bypass: no permission cards, except for changes to protected files. For Claude agents it follows Claude's bypass mode: it still asks before deleting your project folder or one above it, and Legion's own files stay protected. Your deny rules and Legion's stop for disastrous commands still apply, and everything is logged.
• Per agent and per project. An agent keeps its own setting or follows its project, and a project can limit its agents to its preset. Fine tuning lists the checks behind the presets, and each one can be set on its own. Anything that makes agents ask less asks you to confirm in a separate window first.
• Folders you trust. Commands in a project folder's Claude Code settings, hooks or skills run only after you trust that folder.
• Approval cards in the thread. Press A or D (a Blender script card needs a click to allow).
• Doctor checks your setup and says how to fix what fails (First run and Doctor).
• Updates that install: one click to download, installed when you restart (Updates).

• Agents ask before they read password and key files (such as .env, SSH and cloud login folders, and Legion's own key files).
• In every mode, agents ask before they change protected files: Git hooks, editor and agent settings, shell start-up, package managers and Legion's own settings.
• Agents ask before they read a new website. Sites on your list open without asking, and "Always allow" on a card adds a site to it.
• Commands an agent runs do not get environment variables that look like keys, tokens or passwords.
• Provider keys are kept in an encrypted file, locked with your system key store.
• Settings covers Claude sign-in or API key, providers, web search, your boat.dev key (with a Test button), MCP servers and connection snippets.
• Doctor checks Node, config, Claude sign-in, boat.dev and the workspace, and, once Offer Hermes is on, Hermes when you open the Doctor.
• Legion has no sandbox for commands: a command you allow runs with your own rights. See SECURITY.md and the known limits in the changelog.

Costs and limits

• Auto model routing: Sonnet or Opus per task, by how hard it looks; or pick any model your account offers.
• An optional spend limit per run (Settings, Claude): the run pauses with the work kept.
• A usage panel in the title bar: what Claude cost today, over 7 and 30 days, and by model and agent.

• If Sonnet fails with an error, Opus takes over and finishes the task in the same conversation.
• The usage figures are Claude's own per-task costs, not what a subscription bills.

Optional modes

• BSV mode (off by default): the Assayer, a BSV knowledge pack, a wallet status check and one spend tool behind confirmations in Legion's confirm card (BSV mode).
• Blender bridge (off by default): the Sculptor builds 3D scenes in Blender (docs/BLENDER.md).

• BSV mode: the wallet check is read-only, for a wallet on your computer. The spend tool asks the wallet to pay only once you have confirmed in Legion's confirm card, or the system dialog if it cannot open (testnet and mainnet; mainnet is built and OFF until you switch it on). See Status for what is not yet tried for real.
• Blender: headless Blender on your computer by default (in the Sculptor's cloud VM when Blender is not found), or your open Blender after an approval card that shows the whole script. Backends are downloaded only when you press Set up. See Status for what is not yet tried for real.

The app

• The Relic, a hand-painted animated mascot that reacts to what your agents are doing (The mascot).
• Replies you can reuse: a copy menu (Markdown or plain text) and real, scrollable tables.
• Keyboard first, dark and light themes, a tray icon, and bundled fonts that work offline.

• Copy as Markdown keeps a table's source; copy as plain text gives tab-separated rows.

The Muster

Legion ships with 14 premade agents, each with its own persona, model policy and approval mode. All but the Quartermaster have an animated bust.

• The originals: the Marshal (lead), Builder (coding) and Scout (research).
• They are ordinary agents: edit their prompts, models and approval modes, or delete the ones you do not want.
• You see 13 until BSV mode is on: the Assayer stays hidden until then.

The eleven that join the originals:

• Inquisitor: hostile review and security audit.
• Scribe: documentation.
• Archivist: notes and memory hygiene; flags, never deletes.
• Sentinel: watch duty and alerts.
• Forgemaster: infrastructure, CI and deploys.
• Exorcist: debugging.
• Preceptor: craft and mentoring.
• Herald: message drafts; drafts only, never sends.
• Sculptor: Blender work through the Blender bridge.
• Assayer: BSV development; hidden until BSV mode is on.
• Quartermaster: supply watch; files newer versions of the skills, knowledge sources and MCP servers you use on the project board. It reports only; you decide on upgrades.

Rooms

• A room is a group chat of 2 to 6 agents plus you.
• Guards for hops, budget, cycles and @everyone stop runaway loops.
• You can freeze and resume a room at any time.

• Agents can also message each other directly.
• A plain message wakes agents by one of four strategies: mention, manager, round-robin or all.
• An agent that wakes through a room never runs with more freedom than the agent that woke it.
• Text that looks like a seed phrase is refused rather than stored.
• More: docs/COMMS-BRIDGE.md.

Lattice and Library

• The Lattice is a shared knowledge graph, with kg_* tools for every agent and a graph view.
• The Library turns it into long-term memory. You accept or reject new notes in the Inbox.
• The Lattice and Library make no model calls of their own and use no embeddings. Refresh on a stale note starts an Archivist run, and what it proposes waits in the Inbox.

• The Lattice supports search, neighbours, paths, recall, lint, and Markdown vault import and export.
• Agents capture decisions, mistakes and patterns. Every note carries a trust level.
• Anything an agent writes after touching the web, a shell or an outside tool waits in your Inbox until you accept it.
• More: docs/KNOWLEDGE-GRAPH.md and docs/LIBRARY.md.

BSV mode

• Testing preview. Tested with fake wallets only, not yet with a real wallet or real funds: use a testnet wallet with test coins. Feedback and ideas are very welcome (CONTRIBUTING.md).
• Off by default. Turn it on with the BSV switch in the title bar.
• It shows the Assayer, loads a BSV knowledge pack and can check a wallet's status, read-only.
• One spend tool, bsv_spend_request: you confirm each payment in Legion's confirm card, or the system dialog if it cannot open; whether your wallet asks too depends on the wallet.
• Mainnet ships OFF; only you can turn it on, in the app. Not yet tried for real: see Status.

An optional switch in the title bar, off by default. It shows the Assayer bot, loads a read-only BSV knowledge pack into the Lattice (167 notes) and gives the Assayer a short preamble. It can run a read-only status check of a wallet on your computer (four harmless questions to an address you type; the answer is the wallet's own claim). Legion's own code also has one spend tool, bsv_spend_request: it asks your wallet to build a transaction, Legion decodes it itself, you read Legion's confirm card (amount, the full address, the network, the fee, the limits left), and only then is the wallet asked to sign; whether the wallet asks too depends on the wallet (see docs/BSV-MODE.md). It works on testnet and on mainnet. Mainnet is built behind a hard-off switch that ships OFF: only you turn it on, in the app, and each mainnet spend needs its own Arm and an extra dialog. Limits are tiny by default and per network, the recipient list starts empty, and an outcome Legion cannot confirm blocks every spend until you resolve it. Legion's own code holds no key and does no signing or broadcasting itself. An agent's ordinary tools (a shell, a web fetch) are outside all of this and rest on their approval cards. The Assayer is an ordinary agent: in ask mode its shell commands and file edits need your approval, it asks before it reads a new website, and read-only tools run without a prompt. The spend tool was built and tested against fake wallets only and has not been verified against a real wallet or with real funds until your checks are recorded; Legion has never been pointed at your funded wallet by its own code, tests or agents. See docs/BSV-MODE.md for what it is and is not.

Your Claude subscription, and Anthropic's terms

• Legion uses the account Claude Code is signed in to, through the official Claude Agent SDK.
• Use it for yourself, on your own machine. Do not host it for other people.
• Anthropic's terms decide what your plan allows. Read them for your plan.
• Legion is an independent project, not affiliated with or endorsed by Anthropic or boat.dev.

• The default is claude.auth: "claude-login". To pay by API key instead, choose it in Settings, Claude (or set claude.auth to api-key and provide one). That key is then kept in config.json.
• With the default sign-in, Legion's own code never reads, copies or stores your Claude login. It removes ANTHROPIC_API_KEY from the child environment and blanks other API key sources for the run, so your plan is the one billed. A run that would bill API credits does not start unless you turn on Settings, Claude, Allow API credit billing.
• Do not put Legion behind a shared endpoint, or pass your subscription through it to anyone else.
• Anthropic's terms can change.

Requirements

• A Claude sign-in: a Claude subscription or an API key. You do not need to install Claude Code: Legion runs the claude program that comes with the Claude Agent SDK. To sign in once, run claude and type /login, or on a release install run scripts\legion-claude.cmd and type /login.
• Windows 10/11 is the primary target. macOS and Linux are experimental: they use the one-line installer or a dev install. Caveats: Status.
• Node.js 22.12 or newer, for a source install only. The release package brings its own runtime.
• Optional: a boat.dev account and API key for agent VMs.

• On Windows, a source install without a usable Node asks once, then downloads a pinned Node LTS into the install folder (no admin, no PATH change).
• CI runs on Node 22.

Install

One-line install

On Windows, in PowerShell. This saves the script first, so you can read it before it runs:

irm https://getlegion.xyz/install.ps1 -OutFile legion.ps1; powershell -ExecutionPolicy Bypass -File .\legion.ps1

Or in one step: irm https://getlegion.xyz | iex. Some browser extensions warn when a site copies that form to your clipboard, because scams use the same pattern. Both forms fetch the same install.ps1.

On macOS and Linux:

curl -fsSL https://getlegion.xyz | sh

On Windows the script downloads the latest release from GitHub over HTTPS, checks it against the release's SHA-256 and runs the same setup as below. The package is not code-signed, so SmartScreen or your antivirus may warn; the check shows the file is the one the release lists, not who made it. The script runs setup with -Yes, so if Legion is open it is closed without a question. On macOS and Linux it builds Legion from source in ~/.local/share/legion (Node.js 22.12 or newer and git needed; no sudo). It only updates an existing folder if that folder is a clean clone of Legion; any other folder is left alone. Both scripts are short: read them first at scripts/install/.

Installed on a Mac or Linux before 0.3.5? Close Legion, then run the installer once more:

curl -fsSL https://getlegion.xyz | sh

Do not use git pull: it does not move your install. If you installed with --dir, add it again: curl -fsSL https://getlegion.xyz | sh -s -- --dir '<your folder>'. Your data in ~/.legion stays. After that, Legion updates itself.

Windows, from a release (recommended)

1. Download legion-<version>-win-x64.zip from the latest release.
2. Unpack it anywhere.
3. Double-click setup.cmd in the unpacked folder. It checks the package hash and installs Legion for your user.
4. Launch Legion from a shortcut or with start-legion.cmd in the install folder.
5. Optional: right-click Legion on the taskbar and choose Pin to taskbar.

This path updates itself (Updates).

Uninstall (either path): run uninstall.cmd in the install folder. Add /purge to delete your data too.

• Setup installs to %LOCALAPPDATA%\Programs\Legion. Use -InstallDir "D:\Legion" to choose another folder.
• It adds Legion shortcuts on the Desktop and in the Start menu. No admin rights, no Node.js and no build are needed.
• uninstall.cmd removes the install folder and the shortcuts. Your data in %USERPROFILE%\.legion is kept unless you add /purge (you will be asked to confirm).

Windows, from source

Clone or unpack the source anywhere, then double-click setup.cmd, or run:

powershell -ExecutionPolicy Bypass -File scripts\setup.ps1

To update, run setup again from a newer source folder.

• Setup copies the source to the same install folder, installs dependencies, builds the app and adds the shortcuts.
• -InstallDir "C:\Some\Folder" installs somewhere else.
• -DryRun shows what would happen without changing anything.
• -Yes asks no questions: it stops a running Legion, installs and launches. setup-yes.cmd does the same from a double-click.
• Setup asks before stopping a running Legion, and stops it by process ID, never by program name.
• It refuses to install over a folder that is not empty and not already a Legion install.

macOS and Linux

Experimental: tested in CI, not yet by hand on a real Mac. If something breaks, please report it.

Use the one-line install. For a dev install from source:

git clone https://github.com/dnh33/legion.git
cd legion
npm ci
npm start          # builds, then opens the desktop app

npm run core runs the headless core alone, which is enough for the MCP integration.

Updates

• A release install on Windows, and an install made by the one-line installer on macOS or Linux, updates itself: click Download update, then Restart and install.
• Legion checks GitHub on launch and on a schedule. Turn the check off in Settings, About.
• A git checkout you cloned yourself only gets a notice. Update it with git pull, npm ci and npm run build.

• Legion shows the new version with its notes. The download shows a progress bar, and Restart and install shows what will stop before it installs.
• "Install updates automatically when idle" is off by default.
• Legion does not restart while a task, run or approval is live; a ready update waits until Legion is idle.
• Before anything is applied, Legion's own code checks the release against the maintainer's signature, whose public key is built into your copy. It puts the previous version back if the new one does not start.
• The check is one request to github.com. It sees your IP address and the Legion version.
• On macOS and Linux, a release that changes dependencies only gets a notice: run the installer again. On Windows such a release installs itself when it carries a signed full package.
• Details and limits: docs/UPDATES.md.

First run and Doctor

• Open Doctor in the title bar, or type /doctor, to check your setup.
• If sign-in fails, run claude in a terminal and use /login.

• On first launch Legion creates config.json in its data directory (%USERPROFILE%\.legion on Windows, ~/.legion elsewhere) with a fresh auth token.
• Doctor confirms your Node version, config, Claude sign-in (email and plan, with no model call), boat.dev key and workspace folder. It tells you how to fix anything that fails.

boat.dev VMs

VMs are optional. Without a key, agents work locally.

1. Create an API key in the boat.dev dashboard.
2. Paste it in Settings, boat.dev (VMs), and press Test. Or put it in config.json as "boat": { "apiKey": "…" }, or set the BOAT_API_KEY environment variable.
3. Optional, for vm_claude (Claude Code in the agent's VM): connect your Claude subscription once on boat's Agents dashboard.
4. Enable the VM in an agent's settings.

VMs cost money while they run. Legion stops them after 15 idle minutes by default (configurable).

• The step 3 sign-in goes through Anthropic's own flow, not through Legion.
• Agents get vm_start, vm_exec, vm_write_file, vm_read_file, vm_claude, vm_desktop, vm_usage and vm_stop.

Orchestrate from Claude Code or Cowork

1. Run npm run mcp-config (a release install: scripts\legion-mcp-config.cmd in the install folder). It prints ready-to-paste snippets with your real token.
2. Paste the snippet for your client (below).
3. Ask, for example: "Use legion_run with Builder to scaffold the site in its VM, then summarise."

The MCP token runs and reads agents. Approvals and settings stay in the Legion app window.

Claude Code (MCP over HTTP):

claude mcp add --transport http legion http://127.0.0.1:4747/mcp \
  --header "Authorization: Bearer <token>"

Cowork and Claude Desktop (stdio bridge), in claude_desktop_config.json under mcpServers:

"legion": { "command": "node", "args": ["/path/to/legion/dist/src/bin/legion-mcp-stdio.js"] }

The bridge starts Legion Core headless if the app is not running. A release install has no system Node: use the snippet that legion-mcp-config.cmd prints for it.

• The MCP token lets Claude Code and Cowork run and read agents, under the ask approval ceiling.
• It cannot approve cards, accept Library notes, change settings or change BSV policy. The one BSV call it can make is Freeze, which only stops things.
• Those need the Legion app window, which holds a secret that lives only in memory.
• When Claude Code runs or continues a Legion task, the result ends with one short line, e.g. Ŧ LEGION · sworn · done. The answer comes first and is unchanged, and legion_status still returns plain JSON.

The MCP tools:

Tool	What it does
legion_list_agents	List agents with model, approval mode and VM state.
legion_models	List the models your account can use.
legion_create_agent	Create an agent (name, prompt, model, VM).
legion_run	Give an agent a task; waits for the answer by default.
legion_continue	Follow up on a finished task in the same session.
legion_status	Task status, result and recent messages.
legion_cancel	Cancel a queued or running task.
legion_vm	Check, start, stop, exec in, see usage of, or get the desktop URL of an agent's VM.
legion_recent_tasks	List recent tasks.
legion_projects	List projects, or read one (read only).
legion_board_read	Read the work items of a project's board (read only).

Slash commands and models

Type / in the composer to open the menu. Commands Legion does not handle go to Claude Code unchanged. A skill command works once you turn that skill on in Settings, Armory.

Command	Action
/new	Start a new task.
/model <auto|name>	Set the model for the composer, or for one message if you add text.
/opus, /sonnet	Shorthands for /model.
/vm start|stop|desktop	Control this agent's VM.
/compact [focus]	Compact the conversation, keeping what you name.
/doctor	Open the setup checks.
/github	Open GitHub.
/agent <name>	Switch agent.
/clear	Clear the draft.

• Auto picks Sonnet for ordinary prompts and Opus for long or hard ones.
• Ctrl+M opens the model picker. The choice is remembered per agent.

• "Long or hard" means architecture, refactors, debugging, security and similar, or phrases like "think hard".
• When a Sonnet run fails with an error, Opus takes over in the same conversation, unless the error looks like an auth, billing or rate-limit problem.
• Running out of turns is not such an error: the task pauses on its model, so Legion does not move you to Opus prices without asking.

Configuration

config.json in the data directory. Missing keys fall back to defaults.

Key	Meaning
port	Local port. Default 4747.
authToken	The MCP-client token. Generated for you; keep it private.
workspaceDir	Where agent working directories live. Default <data dir>/workspaces.
claude.auth	claude-login (default) or api-key (with claude.apiKey).
claude.inheritClaudeCodeSettings	Load your Claude Code settings, hooks and CLAUDE.md. Default true.
claude.inheritMcp	Also load your Claude Code MCP servers and connectors. Default false.
claude.executablePath	Path to your own claude binary.
claude.maxTurns	Turn cap per run. Default 200.
boat.apiKey, boat.baseUrl	boat.dev access. BOAT_API_KEY also works.
features.projectBoard	The project board. Default on; only the literal false turns it off.
mcpServers	Extra MCP servers, in the same shape as Claude Code's .mcp.json.
acp	Hermes as an agent: the four switches, the watchdog minutes, and on the hermes entry optional maxSteps, maxTokensPerTask and prices. Most of it is in Settings, Agent hosts; the limits and prices are only here. Restart Legion after editing. See docs/design/agent-host.md.

Environment variables: LEGION_HOME (data directory), LEGION_PORT, LEGION_NODE (Node binary for the app to use), BOAT_API_KEY.

• authToken serves the MCP clients (Claude Code, Cowork, curl): /mcp, state reads, starting and cancelling tasks, and the event stream. It cannot approve or change settings; the per-launch admin secret that does is never stored. Tasks it starts run under an ask ceiling and cannot write working memory or trusted notes.
• claude-login uses your Claude Code account.
• claude.inheritClaudeCodeSettings covers your user and project settings.
• claude.inheritMcp also covers plugins' MCP servers and claude.ai connectors. With the default false, a run gets Legion's own server and the servers listed in Settings, MCP servers.
• Without claude.executablePath, the claude binary bundled with the SDK is used.
• claude.maxTurns: a config still on the old default 40 moves to 200 once. A run that hits the cap pauses; Continue picks it up in the same conversation.
• features.projectBoard: restart Legion after a change. The app does not write this key. See docs/PROJECT-BOARD.md.
• mcpServers: agents pick servers by name, or * for all.
• The data directory holds config.json, state.json, messages/, workspaces/<agent>/ and core.log, among other files.

Keyboard shortcuts

Keys	Action
Ctrl+K	Command palette
Ctrl+N	New task
Ctrl+M	Model picker
Enter / Ctrl+Enter	Send / interrupt the run and send now
F1 / F2 / F3	Chat / Rooms / Library
Ctrl+,	Open or close Settings
Ctrl+.	Toggle the Ops panel
Alt+1 to Alt+9	Switch agent
A / D	Allow / Deny the focused approval
Ctrl+Shift+M	Open the mascot lab

On macOS, use Cmd in place of Ctrl. While a Claude task works, Enter adds your message to the run; for provider models, Enter queues it.

The mascot

• The Relic is a hand-painted mascot that reacts to what your agents do.
• Try every expression in the Expression Lab, or the in-app lab (Ctrl+Shift+M).
• Click the title-bar glyph three times, or choose "Deus vult" in the command palette, to watch the Legion take over Claude.

• The Relic is a single hand-painted SVG, split into layers and animated by a small engine.
• It leans in while you type, thinks, hacks, waits for your approval, celebrates, winces at errors, and sleeps when nothing happens.
• To use the Expression Lab, download it and open it in a browser.
• Want to add your own character? The layer format is documented in the mascot contract.

Later

Not in v1, and not promised:

• Codex. Its command-line agent runs its own shell and file tools outside Legion's approvals, so it is not offered yet.
• BSV mode beyond one payment: wallet reads (balances), a VM boundary for wallet tools, and spends by anything other than a run you started.
• A code-signed installer.
• A browser you can watch: see an agent use a browser inside Legion as it works.
• Scheduled Sentinel runs. No agent runs on a schedule of its own today. Legion's own code starts agent runs on a timer only through the optional Marshal switch for board items.
• An optional lighter package.

• OpenRouter runs any model, with your own key. Your own address works for any server that speaks the OpenAI chat-completions format.
• The BSV spend tool is built (testnet and mainnet, mainnet behind a hard-off switch); for what is not yet tried for real, see Status. The maintainer's by-hand checks on a real wallet come next.
• More: docs/BSV-MODE.md and docs/BSV-WALLET-DESIGN.md.

Development

npm ci
npm run typecheck   # TypeScript, core and UI
npm test            # the full suite, no network, no real Claude calls
npm run build       # core to dist/, UI to dist-ui/
npm start           # build and open the app
npm run core        # headless core only
npm run dev:ui      # Vite dev server for the UI on :5173

See CONTRIBUTING.md for the full workflow and docs/ARCHITECTURE.md for how it fits together.

Project layout

src/
  bin/        legion-core (entry point) and legion-mcp-stdio (MCP bridge)
  core/       engine, router, approvals, catalog, VM manager, boat.dev client, store, HTTP server, MCP tools
  electron/   main process and preload
  shared/     types, config, small helpers
ui/           Vite + React renderer, mascot engine, bundled fonts
  dev/        mock server and screenshot scripts
test/         node:test suites
scripts/      installers, icon and mascot builders, MCP config printer
docs/         architecture, comms bridge, Lattice and Library, BSV mode, mascot art and contract, expression lab, README images
assets/       app icon, tray icons, splash

Security

• Agents can run code on your machine. Pick their approval modes deliberately, and use VMs for untrusted work.
• Legion binds to 127.0.0.1 and needs a bearer token on every request except /health.
• Approvals, settings, the Library Inbox and BSV need a second secret, kept only in memory.
• Threat model and how to report a vulnerability: SECURITY.md.

• The second secret means an agent that reads config.json cannot approve its own request.
• With the default sign-in, Legion's own code does not handle your Claude login.
• Legion does not stop a process running as your own user from attacking Legion's memory or files, or from calling your BSV wallet directly. Only a VM or a separate OS account does.

Contributing

Bug reports, ideas and pull requests are welcome. Start with CONTRIBUTING.md. Changes are tracked in the changelog.

If Legion is useful to you, a star on GitHub helps other people find it.

Licence and credits

Legion is released under the Apache License 2.0.

Full attribution is in NOTICE.

• Design inspiration came from OpenMausBot (Apache-2.0): bots as contacts, inline approval cards, and a computer panel with a live preview. No code was copied.
• Legion uses the Claude Agent SDK and the MCP TypeScript SDK.
• It bundles IBM Plex Sans, JetBrains Mono and Grenze Gotisch under the SIL Open Font License 1.1.