Archimedes

Pi, with the good stuff.

An extra pair of eyes on your code. Agents working in parallel. A terminal that keeps you in the loop—and looks good doing it.

Archimedes brings subagents, shared task lists, MCP tools, and a polished interface to Pi. Install them together, use what you like, and make the setup yours.

Setup • Commands • Settings • Components • Development

Setup

You already use Pi

One command:

pi install npm:pi-archimedes

Your ~/.pi/agent/ stays as it is — Archimedes only adds its namespaces under settings.json. Pi's own auth.json, keybindings.json, agents, and sessions are untouched (and /mcp setup only writes the project's .mcp.json, when you run it).

Then run /reload in your session (or start a new one) to pick it up — that reloads the extensions and your keybindings, so any shortcuts you've customized in ~/.pi/agent/keybindings.json keep working.

New to Pi

1. Node.js ≥ 22.19.0 — the requirement Pi itself declares.
2. Install Pi (shell):

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

1. Install Archimedes (shell):

pi install npm:pi-archimedes

1. Launch the terminal in the project you want to work on (shell):

cd /path/to/your/project
   pi

1. Authenticate and pick a model (inside the Pi session):

/login
   /model

1. Make image-paste own the paste keys — Pi's built-in app.clipboard.pasteImage owns Ctrl+V (Linux/macOS) / Alt+V (Windows), and image-paste (on by default in the suite) binds the same keys — clear the built-in in ~/.pi/agent/keybindings.json so image-paste takes them cleanly (otherwise both handlers fire on the shared key and the built-in throws warning banners; format in Pi's keybindings docs). If the file doesn't exist yet, create it with:

{
     "app.clipboard.pasteImage": []
   }

If it already exists, just add/set "app.clipboard.pasteImage": [] in there and run /reload.

/login signs you into a supported provider (subscription or API key) and /model selects a model from it. Model access comes through the providers you configure in Pi — Pi's provider docs list the supported ones, and Archimedes doesn't ship a model of its own. For the broader first run, Pi's quickstart is worth a read.

Give your agent some backup.

Have one subagent explore the codebase while another reviews your changes. Subagents run with your choice of models and tools, stream their progress live into your terminal, and their tasks show up side by side on the shared todo board.

Their token usage and costs feed into the same status bar. More work happening at once, without losing sight of it.

See the subagent guide for dispatching, agent definitions, and the /agents editor.

Keep the decisions. Delegate the work.

When a subagent needs your input, it can ask directly in your session — ask presents the question right in your terminal. Pick an option, add a note, or write your own answer. It gets your decision and carries on.

You don't have to copy messages between terminals to stay involved.

Bring the tools you already use.

Connect MCP servers, browse their tools, and handle authentication inside Pi. Import server definitions from Cursor, Claude Code, Claude Desktop, or VS Code rather than rebuilding your setup.

Start with /mcp setup. Manage it with /mcp.

See what changed. Not just that something changed.

Syntax-highlighted diffs, side by side when there's room and unified when there isn't. Word-level highlights draw your eye to the changes inside each line.

The details are easier to catch when they're easier to read.

A terminal worth spending your day in.

Paste screenshots with inline previews. Keep your branch, model, context usage, and costs in view. Give sessions useful names automatically so they're easier to find later.

A framed editor, animated working indicators, and configurable colours finish the picture. Small touches that make the whole setup feel considered.

Practical notes: the paste markers appear as you paste; image previews appear when you submit the message. Image rendering and desktop alerts both depend on your terminal's support — the image-paste and notify docs cover what each needs. Naming is a separate (potentially billed) model call, not included in the footer's totals.

A little more care with root access.

For tasks that need sudo, sudo shows you the exact command and its reason before you enter your password in a masked prompt—not the chat. Credentials are cached in memory with an expiry, and /sudo forget clears them.

Step away without losing track.

Notify alerts you when the agent finishes or a prompt needs your attention. Alerts wait before firing, and typing cancels anything pending.

You can leave the terminal to do its thing.

The whole suite. Or just your favourite parts.

One install brings everything together. Switch optional extensions on or off with /plugins, then /reload to apply. Use /archimedes to adjust the available settings.

Only want the diffs, footer, or MCP tools? Each component is available separately — see Components.

Commands

| Command | Scope | Notes | |---------|-------|-------| | /plugins | Suite | Toggle the ten optional extensions (core is always on and not toggleable). Toggles persist immediately; /reload (or a fresh session) applies them. | | /archimedes | Suite | Interactive settings panel — up/down moves, left/right changes values, Enter edits supported fields, s saves, Esc discards the current edits. Settings captured at startup need /reload. Not every setting has a panel control. | | /agents | Suite, subagent enabled | Browse, create, and edit custom subagent definitions in .pi/agents/*.md. | | /todos | Todo component | Refreshes the todo widget and reports its status. /todos clear clears the list. (The board's visibility is not a /todos toggle — see the todo docs.) | | /mcp, /mcp setup | MCP component | Manage servers and run logins; the setup wizard scaffolds .mcp.json or imports configs from Cursor, Claude Code, Claude Desktop, or VS Code. | | /sudo, /sudo forget | Sudo component | Inspect cached credential state; forget clears it. | | /reload | Pi | Applies plugin changes and settings read at startup. |

Settings

Every component keeps its own namespace under ~/.pi/agent/settings.json, which Pi parses as strict JSON (no comments — unlike MCP server configs, which accept JSONC). Each component's README documents its namespace, fields, and defaults — including core (chrome, spinner, thinking), footer, diff, notify, mcp, and sudo (also strict JSON). The /archimedes panel covers the settings that have a control; not everything does.

Components

| Component | npm package | What it adds | |-----------|-------------|--------------| | Core | @pi-archimedes/core | Shared event bus, splash screen, framed editor, working spinner, thinking blocks | | Subagent | @pi-archimedes/subagent | Live subagent dispatch, custom agent definitions; /agents editor with the suite | | Todo | @pi-archimedes/todo | Multi-column todo board with subagent columns and auto-clear | | Ask | @pi-archimedes/ask | Structured questions — including subagent questions relayed into your terminal | | MCP | @pi-archimedes/mcp | /mcp management, setup wizard, OAuth, config imports | | Sudo | @pi-archimedes/sudo | sudo_exec with masked password prompt and interactive-sudo guard | | Diff | @pi-archimedes/diff | Syntax-highlighted side-by-side and unified diffs with word-level highlights | | Footer | @pi-archimedes/footer | Branch, model, context usage, and token/cost status bar | | Image Paste | @pi-archimedes/image-paste | Clipboard image paste with inline previews | | Notify | @pi-archimedes/notify | Delayed desktop notifications with input cancellation | | Session Name | @pi-archimedes/session-name | Automatic session titles |

The full suite is the supported connected setup — the integrations above (subagent costs in the footer, subagent columns on the todo board, subagent questions in the terminal) light up when the relevant components are loaded together.

To install just the components you want:

pi install npm:@pi-archimedes/core
pi install npm:@pi-archimedes/subagent
pi install npm:@pi-archimedes/todo
pi install npm:@pi-archimedes/ask
pi install npm:@pi-archimedes/mcp
pi install npm:@pi-archimedes/sudo
pi install npm:@pi-archimedes/diff
pi install npm:@pi-archimedes/footer
pi install npm:@pi-archimedes/image-paste
pi install npm:@pi-archimedes/notify
pi install npm:@pi-archimedes/session-name

Development

pi-archimedes is a pnpm monorepo with no build step — Pi loads the .ts sources at runtime, so verification is a type-check per package, not a build.

.
├── packages/
│   ├── core/          # event bus, chrome, text/color utils, editor, thinking
│   ├── footer/        # status bar
│   ├── diff/          # Shiki-powered diff rendering
│   ├── subagent/      # subagent dispatch (live streaming, cost tracking)
│   ├── todo/          # todo list tool + widget
│   ├── ask/           # structured question tool
│   ├── mcp/           # MCP client adapter, /mcp commands
│   ├── sudo/          # sudo_exec tool + guards
│   ├── image-paste/   # clipboard image paste
│   ├── notify/        # delayed desktop notifications
│   └── session-name/  # auto session naming
└── meta/              # the pi-archimedes orchestrator (depends on all eleven)

git clone https://github.com/danielcherubini/pi-archimedes.git
cd pi-archimedes
pnpm install            # requires pnpm ≥ 10
Verification: type-check each package, independently —
tsc --noEmit in every component directory and in meta (wait for each)
(cd packages/core && npx tsc --noEmit)
Then the full test suite (1300+ tests):
pnpm test

Local testing with Pi

The monorepo root is itself the Pi package — but create the extensions directory first:

mkdir -p ~/.pi/agent/extensions
ln -s "$(pwd)" ~/.pi/agent/extensions/pi-archimedes

Pi's extension loader picks up meta/src/index.ts through the root package.json.

[!WARNING]

Don't run the local symlink and an npm copy of the suite at the same time (pi install npm:pi-archimedes) — you'd double-register the components. Remove one before loading the other: pi remove npm:pi-archimedes, or delete the symlink.

For conventions, architecture decisions, and the release workflow, see AGENTS.md.