MixCode Pi (mpi)

中文文档

A multi-tab, terminal-native AI coding agent fully compatible with the Pi extension ecosystem. Pi is an open, extensible terminal AI coding agent; MixCode runs its entire package ecosystem natively.

Why MixCode Pi? Standard AI coding agents lock your terminal to a single session; you cannot explore, review, or run parallel tasks while the model is thinking. MixCode adds native multi-tab concurrency, Agent Tab collaboration, and full Pi extension compatibility: run multiple agents side by side, send work between tabs, organize workspaces across restarts, and use the full Pi package catalog (npm:…, tools, widgets, and commands).

Highlights

• Native multi-tab concurrency. Run multiple agent sessions side by side with live status indicators.
• Agent Tab collaboration. Tabs send each other prompts, wait, and collect replies (mpi ctl).
• Pi extension compatibility. Runs the full Pi package catalog plus first-party mpi-* extensions.
• Zen & inline modes. Hide chrome for a distraction-free view, or move widgets into the chat stream.
• Mobile & touch optimized. Narrow terminals, split panes, and touch-friendly SSH clients (Termux, iOS Blink).
• Mouse & clickable surfaces. Click tab chips and metadata badges to open pickers, drag the chat scrollbar, and drag-select transcript or draft text to copy.
• Terminal-first workflow. Vim-style transcript navigation, command palette, $skill / @file / @tab autocomplete.
• Prompt history by scope. Recall prompts from the current session, workdir, or global log with /prompt-history and Ctrl+G.
• Declarative batch automation. Script multi-agent workflows in Lua or TypeScript, with dry-run validation.
• Run duration in the footer. See how long the current run has been working (⏱ 12s), and its total duration plus finish time once it settles (✔ done 12s at 2026-10-03 15:39:00), in MixCode and bare Pi.

---

Quick start

Requires Bun. Install via clone and build script:

git clone https://github.com/cyril0124/mixcode-pi.git
cd mixcode-pi
./install.sh
mpi

Or run bun run install:global inside the cloned directory if you prefer linking the development source. Ensure ~/.local/bin (or ~/.bun/bin for linked source) is on your PATH. Upgrade via git pull && ./install.sh.

Models and credentials use Pi's standard config: ~/.pi/agent/models.json (models & custom endpoints) and auth.json (API keys). For built-in providers just run /login inside mpi (or pi) and authenticate via subscription OAuth or an API key; no manual config needed. Credentials are shared with Pi, so an existing Pi setup is picked up as-is; see Model Management.

---

Key features

1. Multi-tab workspaces & session coordination

Run isolated agent sessions side by side. Switch with Tab / Shift+Tab or fuzzy jump via Ctrl+T; background tabs show live status indicators (● running, ✓ unread completion, x error). Each tab maintains an independent conversation tree, tool runtime, and working directory. Workspaces persist tab layouts across restarts, while atomic file locks (open_tabs.json.lock) coordinate tabs across multiple terminal windows or tmux panes.

2. Agent Tab collaboration

Tabs talk to each other, in the same TUI or another mpi, without stealing the keyboard. One tab delegates a review or verification to a peer, waits, and reads the reply. The built-in mpi-ctl skill exposes mpi status / mpi ctl to the agent's bash tool. CLI loop: Agent Tab Collaboration.

3. Full Pi ecosystem & built-in extensions

Install community extensions directly through Pi package declarations (settings.json packages, e.g. npm:pi-web-access), including custom tools, widgets, and themes, or use MixCode's first-party mpi-* tools:

• mpi-goal: Long-running goal tracking with dynamic progressive tool loading and execution budgets.
• mpi-diff-viewer: In-terminal visual diffs with line-level review comments and structured follow-up prompts (/diff).
• mpi-cron: Per-directory scheduled prompts with an editor dock widget and a fire-time claim (cron tool, /cron).
• mpi-loop: Recurring prompt scheduling with conflict handling (/loop 5m /review).
• mpi-optimize-prompt: Metaprompt-based prompt expansion.
• mpi-auto-rename: Context-derived session titles (/auto-rename).
• mpi-ctl-skill: Agent Tab cross-tab / multi-instance collaboration skill ($mpi-ctl, mpi status / mpi ctl).
• mpi-permission: Fine-grained tool execution permission rules (/permission).
• mpi-command-router: Routes selected external Bash command names to configured executables or scripts through per-call PATH wrappers.
• mpi-transcript: View effective LLM context, chatlog, thinking, and latest replies in nvim, vim, or the in-app viewer; configure with /transcript config.
• mpi-prompt-history: Prompt recall log and interactive browser (/prompt-history).
• mpi-tool-block: Selectively hide tools from model context (/tool-block).
• mpi-tool-display: Compact terminal transcript presentation for tools and thinking.
• mpi-model-attach: Add or remove skills and load extra extensions for the current model (/model-attach).
• mpi-skill-refs: $skill autocomplete and prompt expansion.
• mpi-batch-skill: Writes, validates, and launches batch scripts ($mpi-batch, /skill:mpi-batch).
• mpi-stuck-guard: Guards oversized recursive searches, repeated identical tool calls, stalled provider streams, and repeated parameter-validation failures. Configuration and statistics: /stuck-guard config, /stuck-guard stats.
• mpi-herdr-report: Real-time status reporting to Herdr agent panes (HERDR_ENV=1).
• mpi-bash: Default bash timeout plus a foreground window that detaches long commands to the background and reports their exit code when they finish; /bash-logs opens any background command's full log.
• mpi-working-timer: Footer entry with the elapsed time of the current run (⏱ 12s), switching to the settled total and local finish time (✔ done 12s at 2026-10-03 15:39:00) when it ends; also active under bare Pi.

4. Inline & docked extension widgets

Switch dynamically between docked editor widgets and inline chat-stream widgets using /toggle-inline-widgets. In inline mode, widgets follow transcript scrolling rather than taking up fixed vertical editor space.

5. Vim navigation

Treat the conversation transcript as a Vim buffer: scroll line-by-line (j/k), page with Ctrl+U / Ctrl+D, and jump between milestone user turns (Right / Shift+Right). Enter via /vim or empty-queue Ctrl+U then u. Leave with q.

6. Zen mode & ambient status

Hide the top tab bar for a distraction-free view (/toggle-zen-mode). Background agents with notable state changes (running, waiting for input, error, done) render as compact status dots (●) on the top border. The dots are display-only and not clickable.

7. In-prompt skill references & autocomplete

Type $ in the prompt editor to trigger fuzzy autocomplete for project, global, and installed package skills, automatically embedding skill instructions into the prompt payload.

8. Command palette

Press Ctrl+P to fuzzy search and execute slash commands, model switches, and extension actions for the current tab context.

9. Batch automation

Open a whole fleet of agent tabs from one Lua or TypeScript script. Each request carries its own workdir, model, thinking level, and prompt — or a prompts sequence of ordered rounds in one tab — and MixCode applies requests in parallel across distinct tabs. Run it in the live TUI with /batch script.ts -- <args>, or launch a new instance with mpi --batch script.ts -- <args>. Validate before anything changes: mpi --batch script.ts --batch-dry-run prints the plan and exits without a TUI, without bootstrapping runtime, and without state writes.

$ mpi --batch examples/batch/monorepo.ts --batch-dry-run -- packages/core packages/cli
Batch dry-run: 3 request(s)
1. name=core-lint thinking=low workdir=packages/core
   prompt: Run lint and typecheck for the `core` package. Fix all errors without changing behavior.
2. name=cli-lint thinking=low workdir=packages/cli
   prompt: Run lint and typecheck for the `cli` package. Fix all errors without changing behavior.
3. name=summary
   prompt: Summarize lint results across 2 package(s) in /repo.

Fourteen runnable scripts live in examples/batch/ — monorepo lint fan-out, model comparison, prompt sequences, argument passing, and rendering helpers. Reference: Batch Script Automation.

---

Keyboard shortcuts

Core keys only. Open Help or the Command Palette in-app for the full map:

Key	Scope	Action	Description
Tab / Shift+Tab	Global	Next / Previous Tab	Cycle tabs. No-op when autocomplete is open or Zen mode is on (use Ctrl+T).
Ctrl+P	Global	Command Palette	Fuzzy search and run slash commands.
Ctrl+T	Global	Tab Jump	Interactive modal to jump to any open tab.
Ctrl+G	Global	External Editor	Edit current draft in $VISUAL / $EDITOR.
Ctrl+Q	Global	Quit	Safely persists workspace state and exits.
Ctrl+U	Input / Queue	Dequeue / Choose / Vim	Pops the sole non-empty queue; when both contain messages, use Ctrl+U,S/F; when empty, arms Vim entry. See queue management.
Right	Empty Input	Side Panel	Toggle right-hand extension widget panel.
Escape	Global	Smart Escape	Close overlay → abort/retract prompt.
!	Editor	Bash Command	Single-line shell execution mode.
$	Editor	Skill Autocomplete	Trigger project, global, and installed package skill completion.
@	Editor	File / Tab Autocomplete	Complete workspace file paths and peer tab titles.

---

Installation

Recommended: standalone binary (via git clone)

git clone https://github.com/cyril0124/mixcode-pi.git
cd mixcode-pi
./install.sh                 # standalone binary → ~/.local/bin/mpi
./install.sh --prefix /opt/mixcode

Upgrade by running git pull && ./install.sh in the repository directory.

From a local checkout (development / linked)

bun run install:global       # global `mpi` linked from this repo

• ./install.sh compiles a single standalone binary (bun build --compile); no node_modules needed at runtime.
• bun run install:global runs from this repository via the linked Bun runtime.

For release builds, use the Bun version pinned in the release workflow. ./release.sh installs from the frozen lockfile, prefers cached packages, and downloads missing packages. Run ./release.sh --help for target and output options.

---

Usage

mpi                             # Start in current directory
mpi --workdir ~/project         # Start in specific directory
mpi --builtin-extensions-only   # Disable 3rd-party packages; load only mpi-*
mpi --batch script.ts           # Run batch automation script (.lua or .ts)
mpi --print "..."               # Delegate to upstream pi (needs pi on PATH); no TUI
mpi commands                    # List slash commands this workdir registers, no TUI
mpi --list-models               # List authenticated models and thinking levels, then exit
mpi status                      # Inspect running instances and tab states

Agent Tab Collaboration

An agent tab drives its own TUI, or any other mpi, with mpi status / mpi ctl. Send a prompt or slash command to a peer tab, wait for completion, read the result. Target another directory with --pid / --workdir.

Typical uses:

• Hand a review, a question, or a long job to another tab and read the reply.
• Split independent work across tabs and collect the results.
• Talk to a tab in another mpi instance (--pid / --workdir).

mpi status --json                        # List live instances, tabs, states
mpi ctl --tab Agent-01 send-prompt '/compact'
mpi ctl --workdir ~/other-proj --tab Reviewer send-prompt 'review the diff'
mpi ctl --tab Agent-01 wait && mpi ctl --tab Agent-01 last-message

This is how mpi develops mpi: one tab delegates review or verification tasks to tabs of other instances and collects their replies. Full command reference: pi-packages/mpi-ctl-skill/skills/mpi-ctl/SKILL.md. At runtime the skill is installed at <agentDir>/extensions/mpi-ctl-skill/skills/mpi-ctl/SKILL.md, ~/.pi/agent/… by default.

Inspired by Herdr, a terminal multiplexer for coding agents that exposes session control to the agents running inside it.

---

Documentation

Full architectural specifications, guides, and manuals are available in the docs/ directory:

• System Architecture
• TUI Components & Layout
• Narrow & Mobile Terminal Optimizations
• Mouse Support & Clickable Surfaces
• Keybindings & Shortcuts
• CLI & Flags
• Multi-Tab Workspaces
• Model Management
• Provider Errors
• Steering & Follow-up Queues
• Zen Mode
• Inline Widgets Mode
• Extension UI & Widgets
• Vim Mode & Navigation
• Batch Script Automation
• Built-in Extensions Overview
• Pi Extension Compatibility
• Slash Commands Reference
• MixCode Settings
• Environment Variables
• Instance Registry & Monitoring

---

About this project

This is an AI-developed project. My daily development now happens entirely in mpi, including developing mpi itself. The code quality may be poor, but please experience mpi for yourself.

Not interested in this project? Take a look at pi-packages/ instead, a set of high-quality Pi extensions that also work on plain Pi.

Licensed under the MIT License.

Acknowledgements

• Pi by Mario Zechner (earendil-works/pi). MixCode is built on Pi's agent core, extension system, and TUI toolkit (pi-coding-agent, pi-tui, pi-ai, pi-agent-core). Its clean SDK and open extension ecosystem are what make a project like this possible.