Pi Context Optimizer

VS Code extension that feeds rich editor context to the pi coding agent — giving pi real-time access to your files, selections, diagnostics, symbols, and more.

Quick Start

# 1. Install pi CLI globally
npm i -g @mariozechner/pi-coding-agent

# 2. Configure your API key (pick one provider)
export ANTHROPIC_API_KEY="sk-ant-..."
# or
export OPENAI_API_KEY="sk-..."
# or
export GOOGLE_API_KEY="AIza..."

# 3. Install the VS Code extension
ext install tufaan42.pi-context-optimizer

Then press Ctrl+Alt+3 (or click the Pi icon in the activity bar) to open pi with full VS Code context.

Prerequisites

Requirement	Why
pi CLI	The AI coding agent that runs in your terminal
VS Code 1.110+	For the extension host and bridge APIs
API key	At least one LLM provider (Anthropic, OpenAI, Google, etc.)

Installation

Step 1: Install the pi CLI

Choose your preferred package manager:

# npm (Node.js)
npm i -g @mariozechner/pi-coding-agent

# bun (fastest)
bun i -g @mariozechner/pi-coding-agent

# pnpm
pnpm add -g @mariozechner/pi-coding-agent

# yarn
yarn global add @mariozechner/pi-coding-agent

Verify the installation:

pi --version

Step 2: Configure an API Key

pi supports multiple LLM providers. Set up at least one:

# Anthropic (Claude)
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# OpenAI (GPT-4, o1, etc.)
export OPENAI_API_KEY="sk-..."

# Google (Gemini)
export GOOGLE_API_KEY="AIza..."

# Or use pi's built-in config
pi config

Tip: Add the export to your shell profile (~/.bashrc, ~/.zshrc, etc.) so it persists across sessions.

Step 3: Install the VS Code Extension

From VS Code:

Open the Extensions panel (Ctrl+Shift+X / Cmd+Shift+X)
Search for "Pi Context Optimizer"
Click Install

Or from the command line:

# VS Code / Cursor
ext install tufaan42.pi-context-optimizer

# Open VSX (VSCodium, Windsurf, etc.)
ovsx get tufaan42/pi-context-optimizer

Step 4: Install Pi Extensions (Recommended)

These pi-side extensions enhance pi's capabilities inside VS Code:

# Plan/Review/Execute workflow engine
pi install npm:pi-context-optimizer

# Autonomous nested sub-agents
pi install npm:@kmmuntasir/pi-nested-subagents

See Pi Extensions below for details on what these do.

Usage

Opening the Pi Terminal

Method	Action
Keyboard	`Ctrl+Alt+3`
Status bar	Click the Pi button (right side)
Activity bar	Click the Pi icon → opens sidebar

Sending Context to Pi

Open with file:

Right-click a file in the explorer → Pi Context: Open with File
Or use the editor title bar button
Sends the file path and your cursor/selection range

Send selection:

Select text in the editor
Run Pi Context: Send Selection from the command palette
The selected text appears in the pi terminal

Using @pi in VS Code Chat

Type @pi in VS Code's Chat panel for streamed responses:

@pi What does this function do?

This uses the RPC bridge for fast responses while keeping your terminal session separate.

Click the Pi activity bar icon to access:

Search — Find pi packages from npm
Install/Uninstall — One-click package management
Upgrade — Update pi CLI and all installed packages

Plan → Review → Execute Workflow

With the pi-context-optimizer pi extension installed, pi can:

Research — Analyze your codebase
Plan — Create an implementation plan (opens in VS Code)
Review — You approve or reject the plan
Execute — Pi implements the approved plan
Walkthrough — Summary of what changed

Start with: pi --ag-plan "add user authentication"

Pi Extensions

The VS Code extension works best with these pi-side companion extensions. They run inside pi's terminal (not as VS Code extensions).

pi-context-optimizer

The plan → review → execute → walkthrough engine.

pi install npm:pi-context-optimizer

What it does:

Structured workflow for complex tasks
Creates plan artifacts in .pi/context-optimizer/
Integrates with VS Code's plan status bar
Supports /approve and /reject slash commands

How it works:

Writes plan artifacts to <workspace>/.pi/context-optimizer/active.json
Pushes status to the VS Code bridge (via PI_CO_BRIDGE_* env vars)
VS Code watches the artifact files for real-time status updates

@kmmuntasir/pi-nested-subagents

Autonomous nested sub-agents for complex multi-step tasks.

pi install npm:@kmmuntasir/pi-nested-subagents

What it does:

Enables Claude Code-style autonomous sub-agents
Safe configurable nesting depth
Built-in ground-truth verification
Automatic — loads when pi runs, no configuration needed

Managing Extensions

# List installed extensions
pi list

# Update all extensions
pi update

# Update specific extension
pi update pi-context-optimizer

# Remove an extension
pi remove npm:pi-context-optimizer

Bridge Tools Exposed to Pi

Each pi terminal launched by the extension loads a bundled pi extension that can call back into live VS Code APIs. The same extension also updates pi's footer status every few seconds with the active VS Code file, cursor/selection, language id, unsaved-change marker, and diagnostic summary.

Inspection Tools

Tool	What it returns
`vscode_get_editor_state`	Aggregate snapshot of workspace folders, active editor metadata, current selection, latest cached selection, and open editors
`vscode_get_selection`	Current editor selection including selected text, file path, and coordinates; falls back to the latest cached selection when pi terminal focus hides the active editor
`vscode_get_latest_selection`	Most recent cached selection seen by the extension, even if focus already moved
`vscode_get_diagnostics`	VS Code diagnostics for a specific file or the whole workspace
`vscode_get_open_editors`	Visible/open file editors with language, dirty state, and active flag
`vscode_get_workspace_folders`	Workspace folders for the current VS Code window
`vscode_get_document_symbols`	Outline symbols for a file from the active language server
`vscode_get_definitions`	Symbol definition locations at a given file position
`vscode_get_type_definitions`	Symbol type-definition locations at a given file position
`vscode_get_implementations`	Concrete implementation locations for an interface or abstract member
`vscode_get_declarations`	Symbol declaration locations at a given file position
`vscode_get_hover`	Hover docs, inferred types, signatures, and markdown/code snippets from the language server
`vscode_get_workspace_symbols`	Global workspace symbol search through VS Code language providers
`vscode_get_references`	Symbol references at a given file position
`vscode_get_code_actions`	Available code actions / quick fixes for a selection or explicit range, plus intersecting diagnostics
`vscode_get_notifications`	Buffered bridge events such as selection, editor, diagnostics, save, and dirty-state changes

Action Tools

Tool	What it does
`vscode_open_file`	Opens a file in VS Code and can reveal/select a range
`vscode_check_document_dirty`	Checks whether a file is open and whether it has unsaved changes
`vscode_save_document`	Saves a document through VS Code
`vscode_execute_code_action`	Executes a previously returned code action by `actionId`
`vscode_apply_workspace_edit`	Applies explicit range-based text replacements through VS Code so open buffers stay synchronized
`vscode_format_document`	Runs the active document formatter for a file and applies the resulting edits through VS Code
`vscode_format_range`	Runs the active range formatter for a selection/range and applies the resulting edits
`vscode_clear_notifications`	Clears the buffered bridge notification queue
`vscode_show_notification`	Shows an info, warning, or error notification inside VS Code

Bridge Notes

Paths accepted by file-based tools can be absolute or workspace-relative.
vscode_get_code_actions accepts either selection or explicit start / end positions.
vscode_execute_code_action only works with an actionId returned by recent vscode_get_code_actions calls.
vscode_apply_workspace_edit applies replacements via VS Code rather than editing files behind the editor's back.
vscode_format_document / vscode_format_range use VS Code formatting providers for safe buffer editing.
vscode_get_selection falls back to the latest cached selection when the pi terminal has focus.
vscode_get_notifications supports since and limit parameters for incremental polling.
Oversized bridge tool results are capped with a truncated: true wrapper.

Commands

Command	Keybinding	Description
`Pi Context: Open`	`Ctrl+Alt+3`	Open or focus the pi terminal
`Pi Context: Open with File`	Editor title bar	Open pi with current file context
`Pi Context: Send Selection`	—	Send selected text to pi terminal
`Pi Context: Upgrade Pi and Packages`	—	Upgrade pi CLI and installed packages

Configuration

Setting	Default	Description
`pi-context-optimizer.path`	`""`	Absolute path to the pi binary (auto-detected if empty)

Auto-detection checks these paths in order:

~/.bun/bin/pi
~/.local/bin/pi
~/.npm-global/bin/pi
~/node_modules/.bin/pi
$(npm prefix -g)/bin/pi
$(pnpm root -g)/../bin/pi
PATH lookup

On Windows, extensionless shims are probed for .cmd/.exe/.ps1 variants.

Troubleshooting

"pi binary not found"

Solution: Either install pi globally (see Step 1) or set the path manually:

// settings.json
{
  "pi-context-optimizer.path": "/absolute/path/to/pi"
}

"No API key configured"

Solution: Set an environment variable or use pi config:

# Add to ~/.bashrc or ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-..."

Pi terminal opens but context isn't working

Solution: Ensure the pi extensions are installed:

pi list  # Should show pi-context-optimizer and pi-nested-subagents
pi install npm:pi-context-optimizer
pi install npm:@kmmuntasir/pi-nested-subagents

Bridge tools not available to pi

Solution: The VS Code extension automatically injects bridge environment variables. If tools aren't showing:

Close the pi terminal
Press Ctrl+Alt+3 to reopen it
The bridge should reconnect automatically

Plan status bar not updating

Solution: Ensure the pi-context-optimizer pi extension is installed and the workspace has a .pi/context-optimizer/ directory. The status bar updates via both RPC push and file watching.

License

MIT

Pi Context Optimizer

Towfique Ahmed

Pi Context Optimizer

Quick Start

Prerequisites

Installation

Step 1: Install the pi CLI

Step 2: Configure an API Key

Step 3: Install the VS Code Extension

Step 4: Install Pi Extensions (Recommended)

Usage

Opening the Pi Terminal

Sending Context to Pi

Using @pi in VS Code Chat

Package Manager Sidebar

Plan → Review → Execute Workflow

Pi Extensions

pi-context-optimizer

@kmmuntasir/pi-nested-subagents

Managing Extensions

Bridge Tools Exposed to Pi

Inspection Tools

Action Tools

Bridge Notes

Commands

Configuration

Troubleshooting

"pi binary not found"

"No API key configured"

Pi terminal opens but context isn't working

Bridge tools not available to pi

Plan status bar not updating

License