Legion Legion
Menu

Install on Windows PowerShell

git clone https://github.com/dnh33/legion.git; cd legion; .\setup.cmd

Hand it to an AI agent paste this

Install Legion on this computer. Fetch https://getlegion.xyz/install.md and follow it exactly. Check the requirements first and tell me what you are about to run, and ask me before anything it does not list. When it is installed, check that it starts and tell me what you saw.

For a coding agent that can run commands on your machine. It reads install.md (also as llms.txt), checks your setup, and is told to ask you before it installs.

Instructions GitHub

Windows 10 and 11 are the main target. The installer is unsigned, so SmartScreen may warn. macOS and Linux work from a dev install. Needs Node.js 20.10+, git and a Claude Code login.

Your own legion of Claude agents, on your own machine.

A desktop app that runs several Claude agents side by side, with approval cards, rooms and a shared memory. MIT licensed, and young: version 0.2.0.

The Relic, Legion's mascot: a cracked war helm with a glowing green visor, a ring of code around it and data cables trailing down to an open book on a candlelit altar.

What it is

A desk for several Claude agents, not another chat box

Legion is a desktop app for running several Claude agents from one place. Each agent has its own persona, model policy, approval mode and working directory, and can start a cloud Ubuntu VM on boat.dev when a task calls for one. Claude Code and Cowork can drive it too, over MCP.

Meet the thirteenSee it runningRead the status

On your machine
A small Node service on 127.0.0.1 does the work. An Electron window sits on top.
Your Claude, no new login
Agents run through the official Claude Agent SDK on the Claude Code account you are already signed in to.
Thirteen bots to start
Premade, each with a face, twelve visible until BSV mode is on. Edit them, delete all but Zealot, or add your own.
Open source
MIT licensed. It installs from source.
  1. Youthe Legion window, Electron, dark and light
  2. Legion coreNode, on 127.0.0.1: agents, approvals, rooms, the Library
  3. Claudethrough your Claude Code login
  • Claude Code and Coworkdrive Legion over MCP
  • The Librarya knowledge graph, kept as plain files on your disk
  • A VM per agentoptional, through your own boat.dev account
How it fits together. The window, the core, the Library and the MCP clients run on your machine. The model calls, and the optional VM, do not.

One task, start to finish

  1. The top of the agent rail, dark theme: Zealot, Builder, Scout, Inquisitor, Scribe and Archivist, each with an animated bust. The top of the agent rail, light theme: Zealot, Builder, Scout, Inquisitor, Scribe and Archivist, each with an animated bust.

    Step 1

    Pick a bot

    Twelve wait in the rail, thirteen once BSV mode is on. Each has its own persona, model policy and approval mode.

  2. A task thread, dark theme: the user's request, two tool rows (a file read and a search), and Inquisitor's reply with a table of three findings. A task thread, light theme: the user's request, two tool rows (a file read and a search), and Inquisitor's reply with a table of three findings.

    Step 2

    Give it a task

    Tool calls stream into the thread as they happen. Several bots can work at once, and Zealot can hand work to the others.

  3. A room-request card, dark theme: Needs your OK, Room request, the members and lead, a warning that there is no spend limit, Allow (A) and Deny (D) buttons, and a note that it auto-denies after 10 minutes. A room-request card, light theme: Needs your OK, Room request, the members and lead, a warning that there is no spend limit, Allow (A) and Deny (D) buttons, and a note that it auto-denies after 10 minutes.

    Step 3

    Approve what is risky

    Per bot, choose ask, auto-edits or full. In the first two a risky call stops at a card you answer with A or D; full never asks, and Builder ships as full.

  4. A pending note in the Library Inbox, dark theme, tagged Pending, Untrusted and Tainted run, with Accept, Edit then accept and Reject. A pending note in the Library Inbox, light theme, tagged Pending, Untrusted and Tainted run, with Accept, Edit then accept and Reject.

    Step 4

    Keep what is worth keeping

    Notes a bot writes after touching the web, a shell or an outside tool wait in your Inbox until you accept them.

The muster

Thirteen premade bots, ready before you write your own

Each ships with its own persona and an animated bust. They are ordinary agents: edit their prompts, models and approval modes like any other, or delete the ones you do not want (all but Zealot). The Assayer stays hidden until BSV mode is on, so you see twelve until then.

  • Zealot, the lead bot, as it appears in the app: the Relic, a cracked war helm with a glowing green visor, a gold laurel and a red plume, ringed by a halo of code, with red wax seals and data cables trailing down.

    Lead

    Zealot

    Lead agent of the Legion.

    Its bust is the Relic, the mascot. It leans in while you type, thinks, hacks, waits for your approval, celebrates, winces at errors and sleeps when nothing happens.

  • Builder: a grey armoured figure in a teal cloak holding a spike, in front of a stone arch and scaffolding.

    Coding

    Builder

    Coding and building. Prefers its VM for risky work.

  • Scout: a figure in a blue-grey cloak and olive tunic holding a map, a pennant and a moon behind.

    Research

    Scout

    Research and reading.

  • Inquisitor: a figure in a dark violet hood and robe with a silver ring at the chest, between lattice windows and stacks of files.

    Review

    Inquisitor

    Hostile review and security audit.

  • Scribe: a figure in an indigo robe holding an open book and a quill, in front of shelves of pigeonholes.

    Docs

    Scribe

    Documentation.

  • Archivist: a figure whose walnut body is a card-catalogue of small drawers, inside a dim archive.

    Memory

    Archivist

    Notes and memory hygiene. Flags and proposes; it cannot delete Library notes.

  • Sentinel: a figure in a slate cloak with a spiked halo, a blue-flame torch and a banner pole, on a rainy rampart.

    Watch

    Sentinel

    Watch duty and alerts.

  • Forgemaster: a broad figure in a copper-coloured apron with heavy pauldrons, an anvil and a glowing forge behind.

    Infra

    Forgemaster

    Infrastructure, CI and deploys.

  • Exorcist: a figure under a bell-shaped black hood, a lettered hem and a ring on the floor, in a barred archway.

    Debugging

    Exorcist

    Debugging.

  • Preceptor: a figure in a long white linen coat under a protractor-shaped halo, in front of a pegboard of tools.

    Craft

    Preceptor

    Craft and mentoring.

  • Herald: a figure in a mauve tabard holding a tall banner, in front of arched windows and pennants.

    Drafts

    Herald

    Message drafts. Briefed to draft only, never to send.

  • Assayer: a steel-blue figure under a pair of scales hung from a chain halo, with apothecary shelves and a furnace behind.

    BSV

    Assayer

    BSV development. Hidden until BSV mode is on.

  • Sculptor: a figure in a sand-coloured cloak with a hammer and chisel, in front of scaffolding and a half-carved statue.

    3D

    Sculptor

    Blender work through the Blender bridge.

Why it differs

Local-first, Claude-only, with approvals you can read

Local-first

The core binds to 127.0.0.1 and wants a bearer token on every request except a health check. State lives as files in your own data folder. Legion is a personal tool: it is not built to be exposed to a network or shared between users.

Claude only

Every agent runs on a Claude model through the Claude Agent SDK. Legion's own code never reads, copies or stores your Claude credentials. Auto routing picks Sonnet or Opus per task, and retries once on Opus after most Sonnet failures or turn-limit hits. Other providers are not supported.

Approvals and a taint model

Per agent, choose ask, auto-edits or full. In ask and auto-edits modes, risky calls show up as Allow or Deny cards in the thread; full never asks. A run that touched outside content (the web, a shell, an outside tool) counts as tainted, and what it writes to the Library waits in your Inbox until you accept it. A bot that reads config.json cannot approve its own request: the admin secret exists only in memory.

Limits are written down: a program running as your own user can still attack Legion. Read the threat model.

Rooms

A room is a group chat of two to six bots plus you. A message wakes bots by one of four strategies (mention, manager, round-robin, all). Guards for hops, budget, cycles and @everyone stop loops, and you can freeze and resume a room. Bots can propose a room, but creating one waits for an Allow card only you can answer.

The Library and the Lattice

The Lattice is a shared knowledge graph the bots use as long-term memory: search, neighbours, paths, recall, lint, Markdown vault import and export. The Library adds trust levels and the Inbox. There are no model calls and no embeddings in any of it.

A VM per agent, when you want one

Optional, through your own boat.dev account. An agent can start, use and stop its own Ubuntu VM, and you get a live preview and an Open desktop link. Idle VMs stop after 15 minutes by default. Without a key, agents simply work locally.

Claude Code and Cowork can drive it over MCP

Claude Code connects over HTTP; Cowork and Claude Desktop use a stdio bridge. Nine tools cover listing agents and models, creating an agent, running and continuing tasks, checking status, cancelling, driving a VM and listing recent tasks. Agent runs started this way sit under an ask ceiling, and the MCP token cannot approve cards or change settings. The VM tool is the exception: it has no Legion card, so treat the token like a password.

Claude Code, MCP over HTTP
claude mcp add --transport http legion http://127.0.0.1:4747/mcp \
  --header "Authorization: Bearer <token>"

The app

The real thing, in eighteen screens

Real screenshots of Legion 0.2.0, not mock-ups: different bots, moods, cards and both themes. The tasks, notes and room are demo content, not a real workspace. Nothing is edited. Click any picture to open it full size.

Working together

The lead hands work to the others, and a room puts several bots in one conversation with you.

Zealot has asked Scout and Inquisitor for work. The Relic is Executing, and the label under it names the hand-off.
Inquisitor reviews a change and answers with a findings table, worst first. Light theme.
A room: four bots and you, a hop counter, a cost meter against its budget, and a Freeze button.

Every bot has a face, and a mood

Each bust reacts to what its bot is doing: celebrating a finished task, wincing at a failure, standing by.

Scribe, just finished: Victory.
Forgemaster, after a failed run (here an API overload error): Fault detected, with the error and a Retry.
Herald is briefed to draft only, and says so in its reply.
Archivist flags and proposes merges; it does not delete Library notes.

It asks first

In ask and auto-edits modes, risky calls stop at a card only you can answer. The bust turns amber and waits. Full mode never asks, and Builder ships as full.

Exorcist wants to run a shell loop. Nothing runs until you press Allow (A) or Deny (D).
Zealot asks to create a room. The card says plainly that there is no spend limit.

Memory you can audit

Bots keep long-term notes in a graph. What they write after touching outside content waits for you.

The Inbox: notes from bots, flagged Untrusted and Tainted run, wait to be accepted or rejected. Light theme.
The Lattice: the Library as a graph, with search, filters and a note list beside it.
Activity: recent bot and system writes, each with an Undo while it is still allowed. Light theme.

BSV mode, switched on

An optional switch, off by default and fixed to testnet. It reveals the Assayer and loads a read-only knowledge pack.

With BSV mode on there are thirteen bots. The title bar says TESTNET and 157 BSV nodes. The Assayer is clear that Legion has no spend tool in this version.
The BSV panel: wallet status, live funds (disarmed), the activity log and the limits. Legion has no spend tool in this version, so nothing here can move funds.
The pack in the Lattice: a note with its confidence and its sources.

Setup and controls

Hooking it up to Claude Code, picking a model, running commands from the composer.

Settings, Connections: the command that lets Claude Code drive Legion over MCP, and the snippet for Cowork and Claude Desktop.
The slash menu: Legion's commands next to your Claude Code commands.
The model picker, as the app lists it: Auto, or any model your account offers.

The amber "boat.dev key missing" card in the right-hand panel is what the Computer card says until you add a key. The model picker lists the models of the account the capture ran under. Both are shown as the app shows them. The capture ran on a different local port from the default 4747, so the port in a snippet may differ from the one on this page.

Status

Where it honestly stands: version 0.2.0

Legion is young. Here is what is done, what is built but not yet proven, and what it does not do.

Built and tested

The core is built and covered by automated tests: agents, approvals, rooms, the Library and Lattice, and the Windows setup script. The test suite makes no network calls and no real Claude calls, so it says nothing about how your own setup behaves.

Built, not yet proven

  • Blender bridge. Built, off by default, not yet tried on a real Blender.
  • BSV mode. Read-only today, testnet, off by default. A testnet spend tool (mainnet later, off by default) is being finished and has not been verified with real funds.
  • The installer. Unsigned, and not yet run on a wide range of Windows machines.

Not here yet

Other model providers: Codex or ChatGPT may be added later, which is a possibility and not a feature. Signed installers and prebuilt releases: today you install from source.

Instructions

Install from source

You need

  • Node.js 20.10 or newer and git.
  • Claude Code, signed in. Run claude, then /login. A Claude subscription or an API key is required.
  • Windows 10 or 11 for the supported path. The installer is unsigned and has had no wide testing; expect SmartScreen or antivirus prompts for .cmd files.
  • Optional: a boat.dev account and API key, for agent VMs.

With an AI agent

If you use a coding agent that can run commands, give it the address of this site and ask it to install Legion. It will find install.md, a plain-Markdown procedure written for agents: check that Node, git and Claude Code are present and ask you to confirm you are signed in, clone the source, show what setup would do, ask you before installing, then check that Legion starts and report what it saw. It is told not to touch your credentials, not to use admin rights and to stop and ask when a step fails. The same text is at llms.txt and llms-full.txt.

Windows, by hand

Open PowerShell and run the command from the top of this page. It clones the source and starts setup:

git clone https://github.com/dnh33/legion.git; cd legion; .\setup.cmd

Setup installs Legion for your user in %LOCALAPPDATA%\Programs\Legion. No admin rights are needed. It copies the source there, installs dependencies, builds the app and adds Legion shortcuts to the Desktop and Start menu. If you already have the source, double-click setup.cmd or run:

powershell -ExecutionPolicy Bypass -File scripts\setup.ps1
  • -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.
  • Run setup again from a newer source folder to update in place.

Launch from the shortcuts, or start-legion.cmd in the install folder. uninstall.cmd in the install folder removes the install and the shortcuts and keeps your data in %USERPROFILE%\.legion; add /purge to delete that too.

macOS and Linux

These work from a dev install:

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.

First run

On first launch Legion creates config.json in its data folder with a fresh auth token. Open Doctor in the title bar, or type /doctor. It checks your Node version, config, Claude sign-in, boat.dev key and workspace folder, and tells you how to fix anything that fails. For agent VMs, create a boat.dev API key and put it in config.json as "boat": { "apiKey": "…" }, or set BOAT_API_KEY.

Full README on GitHub

FAQ

Plain answers

Do I need an API key?

Not for Legion itself, but you do need a Claude subscription or an API key. By default Legion uses whichever account Claude Code is signed in to on your machine. If you would rather pay by API key, switch the setting and provide one.

Can it use ChatGPT, Codex or another model?

No. Every agent runs on a Claude model through the Claude Agent SDK. Other providers are a possible later addition, not a feature.

What does it cost?

Legion itself is MIT licensed. Your Claude usage is billed under your own plan or API key, and Anthropic's terms say what your plan allows. VMs are optional, belong to boat.dev and cost money while they run; Legion stops idle ones after a set time.

Is it safe to give agents a shell?

It depends on the approval mode you pick. ask puts risky tool calls behind a card, full removes the prompts for that agent. Agents can run code on your machine, so use a VM for untrusted work. Legion's own checks do not stop a program that already runs as your user. The security policy lists the limits.

Does anything leave my computer?

Legion's state is files in your data folder. Your prompts go to Claude through the Agent SDK, as they would from Claude Code, and to boat.dev only if you turn on a VM for an agent. Tools you approve can reach further: a web fetch, or an MCP server you add, talks to whatever it is pointed at.

Can I host it for other people?

No. It is a personal tool for your own machine. Do not put it behind a shared endpoint or pass your subscription through it to someone else.

What is BSV mode?

An optional toggle, off by default and fixed to testnet. It shows the Assayer bot, loads a read-only BSV knowledge pack and can run a read-only status check of a wallet on your computer. Legion has no spend tool in this version.

Does it work on macOS or Linux?

From a dev install, yes. Windows 10 and 11 are the primary target and the only place the setup script runs.