Pi Agent Studio

A feature-rich VS Code extension for the pi coding agent - native terminal TUI or webview chat panel, full editor bridge, and bundled pi extensions (todo, subagent...) out of the box, plus a sessions sidebar and a full settings panel for models, agents, and more 🔥

English | 简体中文

Features

• Native terminal TUI - Pi runs in a real VS Code integrated terminal (PTY). No shell layer, no quoting hacks - pi is spawned directly (default mode)
• Webview chat panel - Optional webview UI mode opens a streaming chat panel backed by a per-panel pi --mode rpc subprocess, with a rich contenteditable composer (@file mentions and /commands rendered as token chips), prompt queuing (Enter steer / Alt+Enter follow-up), input history, fork/revert, built-in commands, and retry
• Sidebar chat view — The same chat UI is also available as a WebviewView in its own Pi Chat activity bar container (Pi: Open in Sidebar): a lightweight starter screen shows until you start a session, and one background session per window survives view hide / re-resolve with full state re-hydration. A new sidebar value for pi-agent-studio.ui routes Pi: Open / Open Here and the Sessions view to it
• Mermaid & math rendering — The webview chat panel renders mermaid code fences as interactive diagrams and math expressions ($...$, $$...$$) with KaTeX; diagram theme is configurable via pi-agent-studio.chatMermaidTheme (default / neutral / dark / forest / base)
• Rewind code - Rewind a historical message in /tree and optionally restore the file changes too, via the bundled rewind-code extension (file-level snapshots, Accept / Revert controls; /fork rewind is message-only)
• MCP support - Talk to Model Context Protocol servers (stdio or HTTP) configured in user/project scope via pi's built-in MCP (requires pi ≥ 0.99; tools exposed as mcp__<server>__<tool>, OAuth sign-in, /mcp management); the chat toolbar drawer shows live server status and offers one-click reconnect
• Skills management - Visual panel to create, edit, and delete pi skills (SKILL.md with YAML frontmatter) in user and project scopes
• VS Code bridge — Bundles a pi extension and local HTTP bridge for live editor data
• Diagnostics tool — The agent can read VS Code diagnostics (LSP / lint / type errors) on demand via vscode_get_diagnostics
• AI-powered Git commit messages — Generate semantic commit messages from staged changes using pi, with support for 14 languages and custom prompt templates
• Full Settings panel — One unified webview editor for everything: Models (Providers / OAuth / API Keys), Agents, Prompt Templates, Skills, MCP Servers (built-in format: transport, enabled, exposure, tool exposure, description, timeout, OAuth JSON), Commit Message (model / language / custom prompt), and Settings (inline settings.json editor + System Prompt Append/Override) — all backed by direct ~/.pi/agent/*.json I/O. The Models tab exposes advanced provider/model compatibility options: per-model API protocol and base URL overrides, custom headers with env/command placeholders, OpenAI/Anthropic compatibility fields, cost tiers, and thinking levels
• Sidebar views — Sessions (new/restore/switch) and a compact Settings sidebar (env info, upgrade, jump to the full panel)
• Dangerous Command Approval — Built-in permission gate that blocks dangerous bash commands like rm -rf and sudo, requiring manual approval before execution; supports AskForApproval / FullAccess modes and custom danger modes

Requirements

• VS Code ≥ 1.100.0 (the extension engine requirement is ^1.100.0)

• pi CLI installed:

  npm install -g --ignore-scripts @earendil-works/pi-coding-agent
  # or
  bun add -g --ignore-scripts @earendil-works/pi-coding-agent
  # or
  pnpm add -g --ignore-scripts @earendil-works/pi-coding-agent
  # or
  yarn global add --ignore-scripts @earendil-works/pi-coding-agent

• An API key (or OAuth credential) configured for at least one provider — manage them from the Models tab of the Settings panel

• For MCP support, use pi ≥ 0.99 (built-in MCP) — Pi: Upgrade Pi runs pi update

Install

Available on the VS Code Marketplace and Open VSX:

# VS Code / Cursor
code --install-extension johnny-zhao.pi-agent-studio

# Open VSX (VSCodium, etc.)
ovsx get johnny-zhao/pi-agent-studio

Commands

Command	Keybinding	Description
Pi: Open	Alt+Shift+P	Open or focus the pi terminal beside the editor
Pi: Open in New Window	—	Open pi then move it to a new VS Code window
Pi: Open in Sidebar	—	Open the chat UI in the Pi Chat sidebar view (starter screen until a session is started)
Pi: Open Here	—	Open a pi terminal in the selected folder (via explorer context menu)
Pi: Upgrade Pi	—	Upgrade pi via pi update (falls back to the inferred package manager when offline)
Pi: Open settings.json	—	Open ~/.pi/agent/settings.json in the editor (creates an empty {} if missing)
Pi: Open models.json	—	Open ~/.pi/agent/models.json in the editor (creates an empty { providers: {} } if missing)
Pi: Open Settings	Alt+Shift+,	Open the full Settings panel (chat panel gear button and status bar item do the same)
Pi: Generate Commit Message	—	Generate an AI-powered Git commit message from staged changes using pi
Pi: Generate Commit Message - Stop	—	Abort an ongoing commit message generation

The Pi: Open command is also wired to the editor title bar for one-click access.

Sidebar

The Pi activity bar icon opens a sidebar with two webviews:

• Sessions - Per-workspace session list with live running/idle status icons; dropdown when multiple workspace folders exist
• Settings - Environment info, quick links, Upgrade Pi button, and a Full Settings jump button; when pi is missing it shows a first-run onboarding card with Node ≥ 22.19.0 / npm / pi checks, link-only install steps, and a restart hint (PATH changes apply on VS Code restart)
• Pi Chat - Activity bar icon hosts the chat UI as a sidebar webview (same UI as the webview chat panel). It shows a starter screen until you start a session via the button or Pi: Open in Sidebar, then keeps one background session per window that re-hydrates when the view is hidden and shown again.

Full Settings panel

The Settings sidebar's jump button (or the Pi: Open Settings command) opens a single-instance editor panel with eight tabs, each loading its data lazily:

• Models — three subtabs:
  • Providers — Add / rename / edit / delete custom providers in ~/.pi/agent/models.json; per-provider authHeader toggle and custom headers (env/command placeholders), per-model API protocol / base URL overrides, OpenAI / Anthropic compatibility fields, sampling parameters, cost tiers and thinking-level maps
  • OAuth — Sign in to providers that support OAuth, managed through the bundled AuthStorage
  • API Keys — Manage stored API keys in ~/.pi/agent/auth.json
• Agents - Manage user/project-level subagent definitions used by the bundled subagent tool
• Prompt Templates - Create / edit / delete / open pi prompt templates (markdown with YAML frontmatter) in user and project scopes
• Skills - Create / edit / delete pi skills (SKILL.md) in user and project scopes; external skills are shown read-only with an option to open the file
• MCP Servers - Add / edit / delete MCP server configs in user (~/.pi/agent/mcp.json) and project (.pi/mcp.json) scopes, merged into a single deduplicated list with source badges; an explicit transport selector (stdio / http) shows only the relevant fields — command/args/env/cwd for stdio, url/headers/oauth (raw JSON)/auth.provider for http — plus per-server enabled, exposure, toolExposure, description, and timeout. Written in pi's built-in MCP format
• Commit Message — Configure the AI-generated commit message feature: model (provider/model), output language, and a custom prompt template, written straight to VS Code settings
• System Prompt — Append → ~/.pi/agent/APPEND_SYSTEM.md (appended to pi's system prompt), Override → ~/.pi/agent/SYSTEM.md (replaces pi's system prompt entirely)
• Settings — Form editor over ~/.pi/agent/settings.json, grouped into Model & Thinking (thinking level, per-level token budgets, per-model thinking levels, cache warming), Tools (defaultTools, codemode mode and inline budget), UI & Display (TUI mode regular / fullscreen, fullscreen scrollbar, quiet startup, project trust, notifications), Terminal (OSC 9;4 progress, OSC 8 hyperlinks, inline-image protocol, true color — each auto / on / off), Network, Retry, Compaction, Branch Summary, Message Delivery, Sessions, Model Cycling, Markdown, Resources and Warnings; enum selects can carry non-string values and some fields accept either a number or text (e.g. "auto")

Bridge: tools, slash commands, and footer status

Each pi terminal launched by the extension loads a bundled pi extension that opens a local HTTP bridge to VS Code. The bridge powers three things:

1. Live footer status - Refreshed every ~1.5s in pi's TUI status area: active file, cursor / selection, language id, dirty marker, and diagnostic counts. Disable with pi-agent-studio.statusBar.
2. One LLM tool - The agent can autonomously read VS Code diagnostics. Other actions are intentionally not exposed to the model. Disable individual tools via pi-agent-studio.disabledTools.
3. Slash commands — User-triggered commands that pull live editor context and inject it into the conversation as a user message.

Design note. Earlier versions exposed 25 tools to the model. They were cut down to one: tool-spam pollutes context and tempts the model into making file edits behind the editor's back. The remaining live-editor surface is now driven by explicit slash commands so the human stays in control of when context flows in.

Bundled bridge extensions

Beyond the editor bridge, the extension bundles a few pi extensions that add agent-facing tools and commands (disable any via pi-agent-studio.disabledTools):

• todo - a todo LLM tool with a live list widget above the composer, plus /todos and /todo-clear commands
• questionnaire - lets the agent ask structured questions (rendered as a native web form in webview mode)
• subagent - delegate tasks to specialized agents (explore, general, plus your own); managed from the Agents tab of the Settings panel
• permission-gate - intercepts dangerous bash commands (matching pi-agent-studio.permission.dangerousPatterns, e.g. rm -rf, sudo) and requires approval before execution; switch per session via /permission
• rewind-code - file-level content snapshots that let you rewind a historical message via /tree and optionally restore its code changes (message-only on /fork); in the webview panel it drives a live changed-files widget with Accept / Revert
• btw - /btw asks a question without altering the main conversation context

LLM tool (1)

Tool	What it returns
vscode_get_diagnostics	VS Code diagnostics (LSP / lint / type errors) for a file or the whole workspace

Accepts an optional filePath (absolute or workspace-relative). With no argument it returns diagnostics for the whole workspace.

Slash commands (2)

Type these inside the pi terminal. Each command resolves arguments from the current VS Code state when omitted, calls the bridge, and injects the JSON result back into the conversation as a user message (so the model sees it and can react).

Command	Arguments	Behavior
/vscode-selection [intent?]	optional free-text intent	Returns the current editor selection (text, file path, coordinates). Trailing text is treated as the user's intent and prepended to the injected message.
/vscode-diagnostics [filePath?] [intent?]	optional file path, optional intent	Returns diagnostics for filePath, or for the active editor when omitted. Non-path tokens are treated as intent.

Example:

/vscode-selection explain this regex
/vscode-diagnostics src/extension.ts why is this failing?
/vscode-diagnostics                 # → diagnostics for the currently active editor

Notes

• Slash command arguments use a simple heuristic: a token containing /, \, or . is treated as a file path; everything else is treated as free-text intent.
• File paths can be absolute or workspace-relative.
• The bridge RPC layer (src/bridge/handlers.ts) still implements the full set of editor operations (selection, symbols, definitions, references, hover, code actions, formatting, workspace edits, save, notifications, …). They are reachable from the bundled bridge but not registered as LLM tools or slash commands today — reserved for future explicit commands.
• Oversized bridge results are capped; when a response exceeds the limit, the tool returns a valid JSON wrapper with truncated: true, original size metadata, and a resultJsonPrefix preview.
• Terminal mode (pi-agent-studio.ui: "terminal") creates its terminals without a static name, so the tab can track pi's own signals instead of being frozen on a fixed label: pi writes its live title via OSC 0 (π - <session name> - <cwd>) and reports working/idle state via OSC 9;4. VS Code renders neither unless you opt into the title templates — set "terminal.integrated.tabs.title": "${sequence}" (pi's live title). With VS Code's default template (${process}) the tab shows the process name plus the pi logo icon.

Configuration

Setting	Type	Default	Description
pi-agent-studio.path	string	""	Absolute path to the pi binary (auto-detected if empty)
pi-agent-studio.bridgeSocket	string	""	Bridge endpoint: empty = random port; number = fixed port; else socket path (Windows: named pipe), {windowId}
pi-agent-studio.language	string	"auto"	UI language: auto (follows the VS Code display language), en, or zh-cn
pi-agent-studio.env	object	{}	Environment variables merged into the pi terminal (bridge vars win on key collision)
pi-agent-studio.args	array	[]	Extra CLI args appended after --extension and before any caller-supplied extra args
pi-agent-studio.commitLanguage	string	"English"	Language for generated Git commit messages (14 languages supported)
pi-agent-studio.commitMessagePrompt	string	""	Custom system prompt for commit message generation
pi-agent-studio.commitModel	string	""	Model used for commit message generation, in provider/model format (e.g. Zai/glm-5.2)
pi-agent-studio.statusBar	boolean	true	Show live VS Code context (editor, selection, diagnostics) in the pi TUI footer
pi-agent-studio.ui	string	"terminal"	UI for Pi: Open: terminal (TUI), webview (chat panel), or sidebar (sidebar chat view)
pi-agent-studio.disabledTools	array	[]	Bundled LLM tools to disable: vscode_get_diagnostics, todo, questionnaire, subagent
pi-agent-studio.rpcTrace	boolean	false	Log RPC traffic and pi stderr to the "Pi Chat RPC" output channel
pi-agent-studio.permission.mode	string	"AskForApproval"	Gate dangerous bash commands: AskForApproval (prompt before execution) or FullAccess
pi-agent-studio.permission.dangerousPatterns	array	see "package.json"	Regexes matching dangerous bash commands that require approval (case-insensitive; replaces defaults entirely)
pi-agent-studio.chatFontSize	number	13	Font size of the webview chat panel (range 8–32)
pi-agent-studio.chatSendShortcut	string	"enter"	Send shortcut for the chat composer: enter (Enter sends, Shift+Enter newline) or ctrlEnter (Ctrl/Cmd+Enter sends, Enter newline)
pi-agent-studio.chatMermaidTheme	string	"default"	Mermaid diagram theme for the webview chat panel (default / neutral / dark / forest / base)
pi-agent-studio.chatBackgroundImage	string	""	Absolute path to a local image file (validated for type and ≤ 10 MB) used as the chat panel background
pi-agent-studio.chatBackgroundOpacity	number	1	Background image opacity (0–1); frosted-glass styling is applied to composer, widgets, and autocomplete
pi-agent-studio.mcp.enabled	boolean	false	Enable pi's built-in MCP support (reads ~/.pi/agent/mcp.json + .pi/mcp.json); when disabled, --no-mcp is passed to pi

Building from source

pnpm install
pnpm build         # rolldown bundle → dist/extension.cjs
pnpm package       # builds + vsce package --no-dependencies
pnpm install-local # package + install into local VS Code

Useful dev commands:

• pnpm dev — rolldown watch mode
• pnpm fmt — oxlint --fix + oxfmt
• pnpm lint — oxlint . && oxfmt --check .
• pnpm typecheck — tsgo --noEmit --skipLibCheck + ./typecheck.sh (bridge TS via tsconfig.bridge.json)
• pnpm vitest run — run the test suite

Changelog

See CHANGELOG.md for release notes.

License

MIT