Super Pi

Super Pi is a cross-platform web control plane and companion for Pi (@earendil-works/pi).

It provides a rich Web UI featuring multi-workspace management, interactive agent chats, file browser, subagent delegation, real-time tool inspection, and extensible themes.

Installation & Usage

Method 1: Install as a Pi Plugin (Recommended)

Super Pi is designed to work seamlessly as an official/community extension for Pi:

pi install npm:@evandu/super-pi

Once installed, simply launch your Pi terminal as usual, and type:

/super_pi

This will automatically start the background Super Pi server (port 3080) and open the Web UI in your default browser.

commands available inside pi:

• /super_pi — Open or launch Super Pi
• /super_pi stop — Stop the background Super Pi server
• /super_pi restart — Restart the Super Pi server

To update:

pi update @evandu/super-pi
# or update all Pi extensions:
pi update --extensions

Method 2: Run directly via npx / Node

You can also run Super Pi standalone without Pi:

npx @evandu/super-pi start

Or install globally:

npm install -g @evandu/super-pi
super-pi start   # Start server and open browser
super_pi start   # The underscore spelling is also supported
super-pi stop    # Stop the background server
super-pi restart # Restart the server

To start Super Pi automatically when the current user signs in, run:

super_pi autostart enable
super_pi autostart status
super_pi autostart disable

This registers a per-user startup entry on Windows, macOS, or Linux and does not require administrator access. The automatic process starts the local server without opening a browser. Use --port and --host with autostart enable when the server uses a non-default address.

Then visit http://127.0.0.1:3080 in your browser (or use the printed Network URL http://<lan-ip>:3080 for LAN access).

Super Pi listens on 0.0.0.0 by default. You can customize the host and port:

super-pi start --host 0.0.0.0 --port 3080
# Restrict to local loopback only:
super-pi start --host 127.0.0.1

Active memory

Super Pi includes Hermes-style active memory. It saves only durable information, and keeps the three kinds of information separate:

• User profile: long-term preferences shared across workspaces.
• Workspace facts: repository conventions and environment facts, visible only in that workspace.
• Skills: validated reusable procedures and pitfalls, stored as Markdown and loaded on demand.

Open Settings → 主动记忆 to inspect, edit, delete, or approve pending changes; the same panel controls the automatic review interval. Primary Agents can use memory, skill_manage, and session_search. Sub Agents can read relevant material but cannot write it.

Composer references

Messages may include @worktree:<name> to attach the matching Git worktree path from the current workspace, or @session:<id-or-title> to attach the recent transcript of another session in the same workspace. These references are expanded into explicit context before the turn is sent to Pi, so an agent repairing a harness can inspect the session where it behaved poorly without switching away from the current session.

After the configured number of completed user turns (10 by default), Super Pi starts a separate, restricted review run. It can only use the three memory tools: it cannot read or modify project files, execute shell commands, or dispatch agents. New facts may be saved automatically; changing or deleting existing facts is staged for approval. A new message or stop cancels that conversation's review.

The feature is on by default. Set SUPER_PI_MEMORY_ENABLED=0 to disable it, or set SUPER_PI_MEMORY_REVIEW_INTERVAL=0 to keep manual memory while disabling automatic review. See the design for storage limits, lifecycle, and security boundaries.

Remote latency diagnosis

For a remote browser, enable phase tracing on the server for one test turn:

SUPER_PI_TRACE_LATENCY=1 super-pi start

The server writes answer.begin, pi.spawned, prompt.sent, pi.first-record, and pi.settled with elapsed milliseconds. This separates process/configuration startup from model time. Streaming is coalesced to one WebSocket update per 16 ms and rendered once per browser frame; structural events such as tool calls and state snapshots flush pending text first.

Use the output to compare a direct SSH Pi run with Super Pi. A long answer.begin ? pi.spawned indicates process startup or local configuration work; a long pi.spawned ? prompt.sent identifies pre-prompt validation/configuration; a long prompt.sent ? pi.first-record belongs to Pi/model/provider. If these phases are fast but the browser remains slow, inspect the network path between the browser and the server.

Development

# Install dependencies
npm install

# Start development servers (frontend + backend hot-reload)
npm run dev

# Build for production
npm run build

# Run check suites
npm run check

License

MIT

Web tools and terminal

Add a sidebar tool

Open Tools → 工具设置 and use 复制工具开发 Prompt in the setup dialog. Ask the Super Pi agent to create the tool; its built-in tool_register submits the complete files and mounts the result globally, so the tool is available from every workspace without a separate server.

For a tool that needs local computation, include a Python script in the registration and declare its parameter schema. The script receives one JSON object on stdin and must print one JSON object on stdout. Load the built-in browser SDK from the mounted page:

<script src="./super-pi-tool.js"></script>
<script>
  async function calculate(params) {
    const run = await SuperPiTool.run(params);
    return await SuperPiTool.wait(run.id);
  }
</script>

SuperPiTool.run, get, wait, and cancel are relative, tool-scoped APIs. A page should not call /api/exec, guess a tool id, start an HTTP server, or send shell commands. The server enforces the declared schema, timeout, cancellation, and Python process isolation.

Legacy URL bookmarks remain available for opening external HTTP/HTTPS pages, but they are not the mechanism for registering or running a Super Pi tool.

Enable the terminal

The terminal is built in and starts with Super Pi. It is restricted to local and private-network connections.

PowerShell:

npm start

macOS/Linux:

npm start

Select a workspace, then open the Terminal tab. The shell starts in that workspace. Windows uses PowerShell by default; set SUPER_PI_TERMINAL_SHELL to choose another shell. Terminal connections are limited to localhost and private-network addresses, and the browser cannot choose an arbitrary working directory.

See docs/TERMINAL.md for security details and troubleshooting.