@oh-my-pi/pi-coding-agent 11.0.2 → 11.0.3

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 ## [Unreleased]
 
+## [11.0.3] - 2026-02-05
+### Added
+
+- Added new subcommands to help text: `commit` for AI-assisted git commits, `stats` for AI usage statistics dashboard, and `jupyter` for managing the shared Jupyter gateway
+- Added `grep` subcommand to help text for testing the grep tool
+- Added `browser` tool documentation for browser automation using Puppeteer
+- Added `todo_write` tool documentation for managing todo and task lists
+- Added documentation for additional LLM provider API keys (Groq, Cerebras, xAI, OpenRouter, Mistral, z.ai, MiniMax, OpenCode, Cursor, Vercel AI Gateway) in environment variables reference
+- Added documentation for cloud provider configuration (AWS Bedrock, Google Vertex AI) in environment variables reference
+- Added documentation for search provider API keys (Perplexity, Anthropic Search) in environment variables reference
+- Added documentation for model override environment variables (`PI_SMOL_MODEL`, `PI_SLOW_MODEL`, `PI_PLAN_MODEL`) in CLI help text
+- Added comprehensive environment variables reference documentation at `docs/environment-variables.md` covering API keys, configuration, debugging, and testing variables
+- Added theme system with 44 customizable color tokens, two built-in themes (dark/light), and auto-detection based on terminal background
+- Added `/theme` command to interactively select and switch between themes
+- Added support for custom themes in `~/.pi/agent/themes/*.json` with live editing - changes apply immediately when files are saved
+- Added `userMessageText` theme token for customizing user message text color
+- Added `toolTitle` and `toolOutput` theme tokens for separate coloring of tool execution box titles and output
+
+### Changed
+
+- Updated help text to reflect expanded tool availability - default now enables all tools instead of just read, bash, edit, write
+- Updated available tools list in help documentation to include python, notebook, task, fetch, web_search, browser, and ask
+- Simplified main description in help text from 'AI coding assistant with read, bash, edit, write tools' to 'AI coding assistant'
+- Updated `--tools` option documentation to clarify default behavior and list all available tools
+- Changed all environment variable access from `process.env` to `Bun.env` throughout the codebase for Bun runtime compatibility
+- Updated documentation to reference `Bun.env` instead of `process.env` in examples and comments
+
+### Fixed
+
+- Fixed `Text` component to properly implement `invalidate()` method, ensuring theme changes apply correctly to all UI elements
+- Fixed `TruncatedText` component to properly pad all lines to exactly match the specified width, preventing rendering artifacts
+- Fixed `TruncatedText` component to stop at the first newline and only display the first line
+- Fixed invalid or malformed themes to fall back gracefully to dark theme instead of crashing the application
+
 ## [11.0.2] - 2026-02-05
 
 ### Fixed

package/README.md

@@ -368,7 +368,7 @@ When disabled, neither case triggers automatic compaction (use `/compact` manual
 **Environment Variables (`env`):**
 
 - Automatically sets environment variables when the application starts
-- Only sets variables that aren't already present in `process.env`
+- Only sets variables that aren't already present in `Bun.env`
 - Supports any environment variable, not just API keys
 - Order of precedence: existing env vars > settings.json env vars > auth.json env vars
 

package/docs/environment-variables.md

@@ -0,0 +1,257 @@
+# Environment Variables Reference
+
+This document lists all environment variables used by the coding agent.
+
+## API Keys
+
+### Multi-Provider Support
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OPENAI_API_KEY` | OpenAI API key for GPT models | - |
+| `ANTHROPIC_API_KEY` | Anthropic API key for Claude models | - |
+| `ANTHROPIC_OAUTH_TOKEN` | Anthropic OAuth token (takes precedence over `ANTHROPIC_API_KEY`) | - |
+| `GOOGLE_API_KEY` | Google Gemini API key | - |
+| `COPILOT_GITHUB_TOKEN` | GitHub Copilot personal access token | `$GH_TOKEN` or `$GITHUB_TOKEN` |
+| `GH_TOKEN` | GitHub CLI token (fallback for Copilot) | - |
+| `GITHUB_TOKEN` | GitHub token (fallback for Copilot and API access) | - |
+| `EXA_API_KEY` | Exa search API key | - |
+| `GROQ_API_KEY` | Groq API key for Llama and other models | - |
+| `CEREBRAS_API_KEY` | Cerebras API key | - |
+| `XAI_API_KEY` | xAI API key for Grok models | - |
+| `OPENROUTER_API_KEY` | OpenRouter aggregated models API key | - |
+| `MISTRAL_API_KEY` | Mistral AI API key | - |
+| `ZAI_API_KEY` | z.ai API key (ZhipuAI/GLM models) | - |
+| `MINIMAX_API_KEY` | MiniMax API key | - |
+| `OPENCODE_API_KEY` | OpenCode API key | - |
+| `CURSOR_ACCESS_TOKEN` | Cursor AI access token | - |
+| `AI_GATEWAY_API_KEY` | Vercel AI Gateway API key | - |
+| `PERPLEXITY_API_KEY` | Perplexity search API key | - |
+
+### Provider-Specific Configuration
+
+#### AWS Bedrock
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AWS_REGION` | AWS region for Bedrock | `$AWS_DEFAULT_REGION` or `us-east-1` |
+| `AWS_DEFAULT_REGION` | AWS default region | - |
+| `AWS_PROFILE` | AWS CLI profile name | - |
+| `AWS_ACCESS_KEY_ID` | AWS access key ID | - |
+| `AWS_SECRET_ACCESS_KEY` | AWS secret access key | - |
+| `AWS_BEARER_TOKEN_BEDROCK` | AWS bearer token for Bedrock | - |
+| `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` | ECS container credentials URI | - |
+| `AWS_CONTAINER_CREDENTIALS_FULL_URI` | ECS container credentials full URI | - |
+| `AWS_WEB_IDENTITY_TOKEN_FILE` | Web identity token file path | - |
+| `AWS_ROLE_ARN` | IAM role ARN for web identity | - |
+
+#### Azure OpenAI
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AZURE_OPENAI_API_KEY` | Azure OpenAI API key (required) | - |
+| `AZURE_OPENAI_API_VERSION` | Azure OpenAI API version | `2024-10-01-preview` |
+| `AZURE_OPENAI_BASE_URL` | Azure OpenAI base URL | Constructed from resource name |
+| `AZURE_OPENAI_RESOURCE_NAME` | Azure OpenAI resource name | - |
+| `AZURE_OPENAI_DEPLOYMENT_NAME_MAP` | JSON map of model IDs to deployment names | `{}` |
+
+#### Google Cloud (Vertex AI)
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `GOOGLE_CLOUD_PROJECT` | Google Cloud project ID (required for Vertex AI) | `$GCLOUD_PROJECT` |
+| `GCLOUD_PROJECT` | Google Cloud project ID (alternative) | - |
+| `GOOGLE_CLOUD_PROJECT_ID` | Google Cloud project ID (used during OAuth discovery) | `$GOOGLE_CLOUD_PROJECT` |
+| `GOOGLE_CLOUD_LOCATION` | Google Cloud location (required for Vertex AI) | - |
+| `GOOGLE_APPLICATION_CREDENTIALS` | Path to Google service account JSON | - |
+
+#### Anthropic Search & Custom Base URLs
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `ANTHROPIC_BASE_URL` | Custom Anthropic API base URL | - |
+| `ANTHROPIC_SEARCH_API_KEY` | API key for Anthropic search (separate from main API) | - |
+| `ANTHROPIC_SEARCH_BASE_URL` | Custom base URL for Anthropic search | - |
+| `ANTHROPIC_SEARCH_MODEL` | Model to use for web search | `claude-sonnet-4` |
+
+#### Kimi
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `KIMI_CODE_BASE_URL` | Kimi Code API base URL | `https://kimi.moonshot.cn` |
+| `KIMI_CODE_OAUTH_HOST` | Kimi Code OAuth host | `$KIMI_OAUTH_HOST` or `https://kimi.moonshot.cn` |
+| `KIMI_OAUTH_HOST` | Kimi OAuth host (fallback) | - |
+
+## Model Configuration
+
+### Model Role Overrides
+
+Override model roles via environment variables (ephemeral, not persisted):
+
+| Variable | Description | CLI Flag |
+|----------|-------------|----------|
+| `PI_SMOL_MODEL` | Fast model for lightweight tasks | `--smol` |
+| `PI_SLOW_MODEL` | Reasoning model for thorough analysis | `--slow` |
+| `PI_PLAN_MODEL` | Model for architectural planning | `--plan` |
+
+## Agent Configuration
+
+### Core Settings
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PI_CODING_AGENT_DIR` | Directory for agent data (sessions, auth, cache) | `~/.omp/agent` |
+| `PI_SUBPROCESS_CMD` | Custom command for spawning subagents | Auto-detected |
+| `PI_NO_TITLE` | Disable automatic session title generation | `false` |
+| `NULL_PROMPT` | Use empty system prompt (testing) | `false` |
+| `PI_BLOCKED_AGENT` | Override agent type in task tool | - |
+
+### Caching
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PI_CACHE_RETENTION` | Prompt cache retention (`long` = 24h for OpenAI) | - |
+
+## Python Configuration
+
+### Python Kernel
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `VIRTUAL_ENV` | Python virtual environment path | Auto-detected (`.venv` or `venv`) |
+| `PI_PY` | Python tool mode (`per-session`, `per-call`, `off`) | `per-session` |
+| `PI_PYTHON_SKIP_CHECK` | Skip Python availability check (testing) | `false` |
+
+### External Python Gateway
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PI_PYTHON_GATEWAY_URL` | External Python gateway URL | - |
+| `PI_PYTHON_GATEWAY_TOKEN` | Authentication token for gateway | - |
+
+### Debugging
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PI_PYTHON_IPC_TRACE` | Trace Python IPC messages (`1` = enabled) | `false` |
+
+## Task & Subagent Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PI_TASK_MAX_OUTPUT_BYTES` | Maximum output bytes per subagent | `500000` |
+| `PI_TASK_MAX_OUTPUT_LINES` | Maximum output lines per subagent | `5000` |
+
+## TUI & Terminal Configuration
+
+### Terminal Capabilities
+
+| Variable | Description | Auto-Detected |
+|----------|-------------|---------------|
+| `COLORTERM` | Terminal color support (`truecolor`, `24bit`) | Yes |
+| `COLORFGBG` | Terminal foreground/background colors | Yes |
+| `TERM` | Terminal type | Yes |
+| `TERM_PROGRAM` | Terminal program name | Yes |
+| `TERM_PROGRAM_VERSION` | Terminal program version | Yes |
+| `TERMINAL_EMULATOR` | Terminal emulator name | Yes |
+| `WT_SESSION` | Windows Terminal session ID | Yes |
+
+### TUI Behavior
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PI_NOTIFICATIONS` | Desktop notifications (`off`, `0`, `false` = disabled) | Enabled |
+| `PI_TUI_WRITE_LOG` | Log all TUI write operations to file | - |
+| `PI_HARDWARE_CURSOR` | Show hardware cursor (`1` = enabled) | `false` |
+
+## Bash & Shell Configuration
+
+### Shell Detection
+
+| Variable | Description | Auto-Detected |
+|----------|-------------|---------------|
+| `SHELL` | User's default shell | Yes (Unix) |
+| `ComSpec` | Command processor | Yes (Windows) |
+
+### Editor
+
+| Variable | Description | Fallback |
+|----------|-------------|----------|
+| `VISUAL` | Visual editor for external editing (Ctrl+G) | `$EDITOR` |
+| `EDITOR` | Default text editor | - |
+
+### Bash Tool Behavior
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PI_BASH_NO_CI` | Don't set `CI=true` in bash environment | `$CLAUDE_BASH_NO_CI` |
+| `CLAUDE_BASH_NO_CI` | Legacy name for `PI_BASH_NO_CI` | - |
+| `PI_BASH_NO_LOGIN` | Don't use login shell for bash | `$CLAUDE_BASH_NO_LOGIN` |
+| `CLAUDE_BASH_NO_LOGIN` | Legacy name for `PI_BASH_NO_LOGIN` | - |
+| `PI_SHELL_PREFIX` | Prefix for bash commands | `$CLAUDE_CODE_SHELL_PREFIX` |
+| `CLAUDE_CODE_SHELL_PREFIX` | Legacy name for `PI_SHELL_PREFIX` | - |
+
+## Desktop Environment Detection
+
+These are auto-detected for system prompt context:
+
+| Variable | Purpose |
+|----------|---------|
+| `KDE_FULL_SESSION` | Detect KDE desktop |
+| `XDG_CURRENT_DESKTOP` | Current desktop environment |
+| `DESKTOP_SESSION` | Desktop session name |
+| `XDG_SESSION_DESKTOP` | XDG desktop session |
+| `GDMSESSION` | GDM session type |
+| `WINDOWMANAGER` | Window manager name |
+| `XDG_CONFIG_HOME` | User config directory |
+| `APPDATA` | Windows app data directory |
+| `HOME` | User home directory |
+
+## LSP Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PI_DISABLE_LSPMUX` | Disable lspmux integration (`1` = disabled) | `false` |
+
+## Debugging & Development
+
+### General Debugging
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DEBUG` | Enable debug logging | `false` |
+| `PI_DEV` | Development mode (verbose native addon loading) | `false` |
+| `PI_TIMING` | Log tool factory and operation timings (`1` = enabled) | `false` |
+
+### Startup Debugging
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PI_DEBUG_STARTUP` | Print startup stage timings to stderr | `false` |
+
+### Provider-Specific Debugging
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DEBUG_CURSOR` | Cursor provider debug logging (`1` = basic, `2` or `verbose` = detailed) | `false` |
+| `DEBUG_CURSOR_LOG` | Path to write Cursor debug log file | - |
+| `PI_CODEX_DEBUG` | OpenAI Codex debug logging (`1` or `true` = enabled) | `false` |
+
+## Commit Message Generation
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PI_COMMIT_TEST_FALLBACK` | Force fallback commit generation (testing) | `false` |
+| `PI_COMMIT_NO_FALLBACK` | Disable fallback commit generation | `false` |
+| `PI_COMMIT_MAP_REDUCE` | Enable/disable map-reduce for large diffs (`false` = disabled) | Enabled |
+
+## Testing & CI
+
+These are auto-detected but documented for completeness:
+
+| Variable | Description |
+|----------|-------------|
+| `BUN_ENV` | Bun environment (`test` skips certain checks) |
+| `NODE_ENV` | Node environment (`test` skips certain checks) |
+| `E2E` | Enable end-to-end tests (`1` or `true`) |
+| `PI_NO_LOCAL_LLM` | Skip local LLM tests (Ollama, LM Studio) |

package/docs/sdk.md

@@ -87,7 +87,7 @@ interface AgentSession {
 	prompt(text: string, options?: PromptOptions): Promise<void>;
 	sendUserMessage(
 		content: string | (TextContent | ImageContent)[],
-		options?: { deliverAs?: "steer" | "followUp" },
+		options?: { deliverAs?: "steer" | "followUp" }
 	): Promise<void>;
 	steer(text: string): void;
 	followUp(text: string): void;
@@ -106,7 +106,7 @@ interface AgentSession {
 	setThinkingLevel(level: ThinkingLevel): void;
 	cycleModel(direction?: "forward" | "backward"): Promise<ModelCycleResult | undefined>;
 	cycleRoleModels(
-		direction?: "forward" | "backward",
+		direction?: "forward" | "backward"
 	): Promise<{ model: Model; thinkingLevel: ThinkingLevel; role: ModelRole } | undefined>;
 	cycleThinkingLevel(): ThinkingLevel | undefined;
 
@@ -141,7 +141,7 @@ interface AgentSession {
 	// Compaction
 	compact(
 		customInstructions?: string,
-		options?: { onComplete?: (result: CompactionResult) => void; onError?: (error: Error) => void },
+		options?: { onComplete?: (result: CompactionResult) => void; onError?: (error: Error) => void }
 	): Promise<CompactionResult>;
 	abortCompaction(): void;
 
@@ -491,11 +491,7 @@ const { session } = await createAgentSession({
 Extensions intercept agent events and can register custom tools/commands. Hooks remain for legacy compatibility.
 
 ```typescript
-import {
-	createAgentSession,
-	discoverExtensions,
-	type ExtensionFactory,
-} from "@oh-my-pi/pi-coding-agent";
+import { createAgentSession, discoverExtensions, type ExtensionFactory } from "@oh-my-pi/pi-coding-agent";
 
 // Inline extension
 const loggingExtension: ExtensionFactory = (api) => {
@@ -878,8 +874,8 @@ import systemPrompt from "./SYSTEM.md" with { type: "text" };
 const authStorage = await discoverAuthStorage();
 
 // Runtime API key override (not persisted)
-if (process.env.MY_KEY) {
-	authStorage.setRuntimeApiKey("anthropic", process.env.MY_KEY);
+if (Bun.env.MY_KEY) {
+	authStorage.setRuntimeApiKey("anthropic", Bun.env.MY_KEY);
 }
 
 // Model registry

package/examples/sdk/README.md

@@ -78,7 +78,7 @@ const { session } = await createAgentSession({
 
 // Full control
 const customAuth = new AuthStorage("/my/app/auth.json");
-customAuth.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
+customAuth.setRuntimeApiKey("anthropic", Bun.env.MY_KEY!);
 const customRegistry = new ModelRegistry(customAuth);
 
 const { session } = await createAgentSession({

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "11.0.2",
+	"version": "11.0.3",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"ompConfig": {
@@ -80,12 +80,12 @@
 	},
 	"dependencies": {
 		"@mozilla/readability": "0.6.0",
-		"@oh-my-pi/omp-stats": "11.0.2",
-		"@oh-my-pi/pi-agent-core": "11.0.2",
-		"@oh-my-pi/pi-ai": "11.0.2",
-		"@oh-my-pi/pi-natives": "11.0.2",
-		"@oh-my-pi/pi-tui": "11.0.2",
-		"@oh-my-pi/pi-utils": "11.0.2",
+		"@oh-my-pi/omp-stats": "11.0.3",
+		"@oh-my-pi/pi-agent-core": "11.0.3",
+		"@oh-my-pi/pi-ai": "11.0.3",
+		"@oh-my-pi/pi-natives": "11.0.3",
+		"@oh-my-pi/pi-tui": "11.0.3",
+		"@oh-my-pi/pi-utils": "11.0.3",
 		"@openai/agents": "^0.4.5",
 		"@sinclair/typebox": "^0.34.48",
 		"ajv": "^8.17.1",

package/src/cli/args.ts

@@ -181,7 +181,7 @@ export function parseArgs(args: string[], extensionFlags?: Map<string, { type: "
 }
 
 export function printHelp(): void {
-	console.log(`${chalk.bold(APP_NAME)} - AI coding assistant with read, bash, edit, write tools
+	console.log(`${chalk.bold(APP_NAME)} - AI coding assistant
 
 ${chalk.bold("Usage:")}
   ${APP_NAME} [options] [@files...] [messages...]
@@ -191,7 +191,11 @@ ${chalk.bold("Subcommands:")}
   update    Check for and install updates
   config    Manage configuration settings
   setup     Install dependencies for optional features
+  commit    AI-assisted git commits
+  stats     AI usage statistics dashboard
+  jupyter   Manage the shared Jupyter gateway
   shell     Interactive shell console (brush-core test)
+  grep      Test grep tool
 
 ${chalk.bold("Options:")}
   --model <pattern>              Model to use (fuzzy match: "opus", "gpt-5.2", or "p-openai/gpt-5.2")
@@ -213,8 +217,9 @@ ${chalk.bold("Options:")}
                                  Supports globs (anthropic/*, *sonnet*) and fuzzy matching
   --no-tools                     Disable all built-in tools
   --no-lsp                       Disable LSP tools, formatting, and diagnostics
-  --tools <tools>                Comma-separated list of tools to enable (default: read,bash,edit,write)
-                                 Available: read, bash, edit, write, grep, find, ls
+  --tools <tools>                Comma-separated list of tools to enable (default: all)
+                                 Available: read, bash, edit, write, grep, find, lsp,
+                                 python, notebook, task, fetch, web_search, browser, ask
   --thinking <level>             Set thinking level: off, minimal, low, medium, high, xhigh
   --hook <path>                  Load a hook/extension file (can be used multiple times)
   --extension, -e <path>         Load an extension file (can be used multiple times)
@@ -261,33 +266,51 @@ ${chalk.bold("Examples:")}
   ${APP_NAME} --thinking high "Solve this complex problem"
 
   # Read-only mode (no file modifications possible)
-  ${APP_NAME} --tools read,grep,find,ls -p "Review the code in src/"
+  ${APP_NAME} --tools read,grep,find -p "Review the code in src/"
 
   # Export a session file to HTML
   ${APP_NAME} --export ~/${CONFIG_DIR_NAME}/agent/sessions/--path--/session.jsonl
   ${APP_NAME} --export session.jsonl output.html
 
 ${chalk.bold("Environment Variables:")}
-  ${chalk.dim("# Model providers")}
-  ANTHROPIC_API_KEY       - Anthropic Claude API key
-  ANTHROPIC_OAUTH_TOKEN   - Anthropic OAuth token (alternative to API key)
-  OPENAI_API_KEY          - OpenAI GPT API key
-  GEMINI_API_KEY          - Google Gemini API key
-  GROQ_API_KEY            - Groq API key
-  CEREBRAS_API_KEY        - Cerebras API key
-  XAI_API_KEY             - xAI Grok API key
-  OPENROUTER_API_KEY      - OpenRouter API key
-  MISTRAL_API_KEY         - Mistral API key
-  ZAI_API_KEY             - ZAI API key
-  GITHUB_TOKEN            - GitHub Copilot models (or GH_TOKEN, COPILOT_GITHUB_TOKEN)
+  ${chalk.dim("# Core Providers")}
+  ANTHROPIC_API_KEY          - Anthropic Claude models
+  ANTHROPIC_OAUTH_TOKEN      - Anthropic OAuth (takes precedence over API key)
+  OPENAI_API_KEY             - OpenAI GPT models
+  GEMINI_API_KEY             - Google Gemini models
+  GITHUB_TOKEN               - GitHub Copilot (or GH_TOKEN, COPILOT_GITHUB_TOKEN)
 
-  ${chalk.dim("# Web search providers")}
-  EXA_API_KEY             - Exa search API key
-  PERPLEXITY_API_KEY      - Perplexity search API key
+  ${chalk.dim("# Additional LLM Providers")}
+  AZURE_OPENAI_API_KEY       - Azure OpenAI models
+  GROQ_API_KEY               - Groq models
+  CEREBRAS_API_KEY           - Cerebras models
+  XAI_API_KEY                - xAI Grok models
+  OPENROUTER_API_KEY         - OpenRouter aggregated models
+  MISTRAL_API_KEY            - Mistral models
+  ZAI_API_KEY                - z.ai models (ZhipuAI/GLM)
+  MINIMAX_API_KEY            - MiniMax models
+  OPENCODE_API_KEY           - OpenCode models
+  CURSOR_ACCESS_TOKEN        - Cursor AI models
+  AI_GATEWAY_API_KEY         - Vercel AI Gateway
+
+  ${chalk.dim("# Cloud Providers")}
+  AWS_PROFILE                - AWS Bedrock (or AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
+  GOOGLE_CLOUD_PROJECT       - Google Vertex AI (requires GOOGLE_CLOUD_LOCATION)
+  GOOGLE_APPLICATION_CREDENTIALS - Service account for Vertex AI
+
+  ${chalk.dim("# Search & Tools")}
+  EXA_API_KEY                - Exa web search
+  PERPLEXITY_API_KEY         - Perplexity web search
+  ANTHROPIC_SEARCH_API_KEY   - Anthropic search provider
 
   ${chalk.dim("# Configuration")}
-  PI_CODING_AGENT_DIR    - Session storage directory (default: ~/${CONFIG_DIR_NAME}/agent)
+  PI_CODING_AGENT_DIR        - Session storage directory (default: ~/${CONFIG_DIR_NAME}/agent)
+  PI_SMOL_MODEL              - Override smol/fast model (see --smol)
+  PI_SLOW_MODEL              - Override slow/reasoning model (see --slow)
+  PI_PLAN_MODEL              - Override planning model (see --plan)
 
+  For complete environment variable reference, see:
+  ${chalk.dim("docs/environment-variables.md")}
 ${chalk.bold("Available Tools (all enabled by default):")}
   read       - Read file contents
   bash       - Execute bash commands
@@ -295,11 +318,12 @@ ${chalk.bold("Available Tools (all enabled by default):")}
   write      - Write files (creates/overwrites)
   grep       - Search file contents
   find       - Find files by glob pattern
-  ls         - List directory contents
   lsp        - Language server protocol (code intelligence)
   python     - Execute Python code (requires: ${APP_NAME} setup python)
   notebook   - Edit Jupyter notebooks
+  browser    - Browser automation (Puppeteer)
   task       - Launch sub-agents for parallel tasks
+  todo_write - Manage todo/task lists
   fetch      - Fetch and process URLs
   web_search - Search the web
   ask        - Ask user questions (interactive mode only)

package/src/config/model-registry.ts

@@ -150,7 +150,7 @@ function emptyCustomModelsResult(error?: string): CustomModelsResult {
  * Checks environment variable first, then treats as literal.
  */
 function resolveApiKeyConfig(keyConfig: string): string | undefined {
-	const envValue = process.env[keyConfig];
+	const envValue = Bun.env[keyConfig];
 	if (envValue) return envValue;
 	return keyConfig;
 }

package/src/config/settings.ts

@@ -418,7 +418,7 @@ export class Settings {
 				prev[role] = modelId;
 			}
 		}
-		this.set("modelRoles", prev);
+		this.override("modelRoles", prev);
 	}
 
 	/**

package/src/debug/report-bundle.ts

@@ -86,7 +86,7 @@ export async function createReportBundle(options: ReportBundleOptions): Promise<
 	files.push("system.json");
 
 	// Sanitized environment
-	data["env.json"] = JSON.stringify(sanitizeEnv(process.env as Record<string, string>), null, 2);
+	data["env.json"] = JSON.stringify(sanitizeEnv(Bun.env as Record<string, string>), null, 2);
 	files.push("env.json");
 
 	// Settings/config

package/src/debug/system-info.ts

@@ -28,8 +28,8 @@ export async function collectSystemInfo(): Promise<SystemInfo> {
 	const cpuModel = cpus[0]?.model ?? "Unknown CPU";
 
 	// Try to get shell from environment
-	const shell = process.env.SHELL ?? process.env.ComSpec ?? "unknown";
-	const terminal = process.env.TERM_PROGRAM ?? process.env.TERM ?? undefined;
+	const shell = Bun.env.SHELL ?? Bun.env.ComSpec ?? "unknown";
+	const terminal = Bun.env.TERM_PROGRAM ?? Bun.env.TERM ?? undefined;
 
 	return {
 		os: `${os.type()} ${os.release()} (${os.platform()})`,

package/src/discovery/codex.ts

@@ -160,7 +160,7 @@ function extractMCPServersFromToml(toml: Record<string, unknown>): Record<string
 		const env: Record<string, string> = { ...config.env };
 		if (config.env_vars) {
 			for (const varName of config.env_vars) {
-				const value = process.env[varName];
+				const value = Bun.env[varName];
 				if (value !== undefined) {
 					env[varName] = value;
 				}
@@ -174,14 +174,14 @@ function extractMCPServersFromToml(toml: Record<string, unknown>): Record<string
 		const headers: Record<string, string> = { ...config.http_headers };
 		if (config.env_http_headers) {
 			for (const [headerName, envVarName] of Object.entries(config.env_http_headers)) {
-				const value = process.env[envVarName];
+				const value = Bun.env[envVarName];
 				if (value !== undefined) {
 					headers[headerName] = value;
 				}
 			}
 		}
 		if (config.bearer_token_env_var) {
-			const token = process.env[config.bearer_token_env_var];
+			const token = Bun.env[config.bearer_token_env_var];
 			if (token) {
 				headers.Authorization = `Bearer ${token}`;
 			}

package/src/discovery/helpers.ts

@@ -294,7 +294,7 @@ export async function loadSkillsFromDir(
  */
 export function expandEnvVars(value: string, extraEnv?: Record<string, string>): string {
 	return value.replace(/\$\{([^}:]+)(?::-([^}]*))?\}/g, (_, varName: string, defaultValue?: string) => {
-		const envValue = extraEnv?.[varName] ?? process.env[varName];
+		const envValue = extraEnv?.[varName] ?? Bun.env[varName];
 		if (envValue !== undefined) return envValue;
 		if (defaultValue !== undefined) return defaultValue;
 		return `\${${varName}}`;

package/src/exa/mcp-client.ts

@@ -18,9 +18,9 @@ import type {
 	MCPToolWrapperConfig,
 } from "./types";
 
-/** Find EXA_API_KEY from process.env or .env files */
+/** Find EXA_API_KEY from Bun.env or .env files */
 export async function findApiKey(): Promise<string | null> {
-	// Check process.env first
+	// Check Bun.env first
 	if ($env.EXA_API_KEY) {
 		return $env.EXA_API_KEY;
 	}

package/src/extensibility/plugins/doctor.ts

@@ -29,7 +29,7 @@ export async function runDoctorChecks(): Promise<DoctorCheck[]> {
 	];
 
 	for (const key of apiKeys) {
-		const hasKey = !!process.env[key.name];
+		const hasKey = !!Bun.env[key.name];
 		checks.push({
 			name: key.name,
 			status: hasKey ? "ok" : "warning",

package/src/ipy/executor.ts

@@ -225,7 +225,7 @@ export async function warmPythonEnvironment(
 	useSharedGateway?: boolean,
 	sessionFile?: string,
 ): Promise<{ ok: boolean; reason?: string; docs: PreludeHelper[] }> {
-	const isTestEnv = process.env.BUN_ENV === "test" || process.env.NODE_ENV === "test";
+	const isTestEnv = Bun.env.BUN_ENV === "test" || Bun.env.NODE_ENV === "test";
 	let cacheState: PreludeCacheState | null = null;
 	try {
 		debugStartup("warmPython:ensureKernel:start");

package/src/ipy/kernel.ts

@@ -108,7 +108,7 @@ export interface PythonKernelAvailability {
 }
 
 export async function checkPythonKernelAvailability(cwd: string): Promise<PythonKernelAvailability> {
-	if (process.env.BUN_ENV === "test" || process.env.NODE_ENV === "test" || $env.PI_PYTHON_SKIP_CHECK === "1") {
+	if (Bun.env.BUN_ENV === "test" || Bun.env.NODE_ENV === "test" || $env.PI_PYTHON_SKIP_CHECK === "1") {
 		return { ok: true };
 	}
 

package/src/lsp/client.ts

@@ -412,7 +412,7 @@ export async function getOrCreateClient(config: ServerConfig, cwd: string, initT
 		const proc = ptree.spawn([command, ...args], {
 			cwd,
 			stdin: "pipe",
-			env: env ? { ...process.env, ...env } : undefined,
+			env: env ? { ...Bun.env, ...env } : undefined,
 		});
 
 		const client: LspClient = {

package/src/lsp/lspmux.ts

@@ -66,11 +66,11 @@ function getConfigPath(): string {
 	const home = os.homedir();
 	switch (os.platform()) {
 		case "win32":
-			return path.join(process.env.APPDATA ?? path.join(home, "AppData", "Roaming"), "lspmux", "config.toml");
+			return path.join(Bun.env.APPDATA ?? path.join(home, "AppData", "Roaming"), "lspmux", "config.toml");
 		case "darwin":
 			return path.join(home, "Library", "Application Support", "lspmux", "config.toml");
 		default:
-			return path.join(process.env.XDG_CONFIG_HOME ?? path.join(home, ".config"), "lspmux", "config.toml");
+			return path.join(Bun.env.XDG_CONFIG_HOME ?? path.join(home, ".config"), "lspmux", "config.toml");
 	}
 }
 

package/src/main.ts

@@ -657,11 +657,11 @@ export async function main(args: string[]) {
 	const slowModel = parsed.slow ?? $env.PI_SLOW_MODEL;
 	const planModel = parsed.plan ?? $env.PI_PLAN_MODEL;
 	if (smolModel || slowModel || planModel) {
-		const currentRoles = settings.get("modelRoles") as Record<string, string>;
-		if (smolModel) currentRoles.smol = smolModel;
-		if (slowModel) currentRoles.slow = slowModel;
-		if (planModel) currentRoles.plan = planModel;
-		settings.override("modelRoles", currentRoles);
+		settings.overrideModelRoles({
+			smol: smolModel,
+			slow: slowModel,
+			plan: planModel,
+		});
 	}
 
 	await initTheme(settings.get("theme"), isInteractive, settings.get("symbolPreset"), settings.get("colorBlindMode"));

package/src/mcp/transports/stdio.ts

@@ -47,7 +47,7 @@ export class StdioTransport implements MCPTransport {
 
 		const args = this.config.args ?? [];
 		const env = {
-			...process.env,
+			...Bun.env,
 			...this.config.env,
 		};
 

package/src/modes/rpc/rpc-client.ts

@@ -114,7 +114,7 @@ export class RpcClient {
 
 		this.process = ptree.spawn(["bun", cliPath, ...args], {
 			cwd: this.options.cwd,
-			env: { ...process.env, ...this.options.env },
+			env: { ...Bun.env, ...this.options.env },
 			stdin: "pipe",
 		});
 

package/src/modes/theme/theme.ts

@@ -1053,15 +1053,15 @@ type ColorMode = "truecolor" | "256color";
 // ============================================================================
 
 function detectColorMode(): ColorMode {
-	const colorterm = process.env.COLORTERM;
+	const colorterm = Bun.env.COLORTERM;
 	if (colorterm === "truecolor" || colorterm === "24bit") {
 		return "truecolor";
 	}
 	// Windows Terminal supports truecolor
-	if (process.env.WT_SESSION) {
+	if (Bun.env.WT_SESSION) {
 		return "truecolor";
 	}
-	const term = process.env.TERM || "";
+	const term = Bun.env.TERM || "";
 	// Only fall back to 256color for truly limited terminals
 	if (term === "dumb" || term === "" || term === "linux") {
 		return "256color";
@@ -1706,7 +1706,7 @@ export async function getThemeByName(name: string): Promise<Theme | undefined> {
 }
 
 function detectTerminalBackground(): "dark" | "light" {
-	const colorfgbg = process.env.COLORFGBG || "";
+	const colorfgbg = Bun.env.COLORFGBG || "";
 	if (colorfgbg) {
 		const parts = colorfgbg.split(";");
 		if (parts.length >= 2) {

package/src/patch/index.ts

@@ -218,7 +218,7 @@ export class EditTool implements AgentTool<TInput> {
 			PI_EDIT_FUZZY: editFuzzy = "auto",
 			PI_EDIT_FUZZY_THRESHOLD: editFuzzyThreshold = "auto",
 			PI_EDIT_VARIANT: envEditVariant = "auto",
-		} = process.env;
+		} = Bun.env;
 		this.envEditVariant = envEditVariant;
 
 		if (envEditVariant !== "replace" && envEditVariant !== "patch" && envEditVariant !== "auto") {

package/src/sdk.ts

@@ -17,7 +17,7 @@
  * // Full control
  * const session = await createAgentSession({
  *   model: myModel,
- *   getApiKey: async () => process.env.MY_KEY,
+ *   getApiKey: async () => Bun.env.MY_KEY,
  *   toolNames: ["read", "bash", "edit", "write"], // Filter tools
  *   extensions: [],
  *   skills: [],
@@ -566,7 +566,7 @@ function createCustomToolsExtension(tools: CustomTool[]): ExtensionFactory {
  * // Full control
  * const { session } = await createAgentSession({
  *   model: myModel,
- *   getApiKey: async () => process.env.MY_KEY,
+ *   getApiKey: async () => Bun.env.MY_KEY,
  *   systemPrompt: 'You are helpful.',
  *   tools: codingTools({ cwd: process.cwd() }),
  *   skills: [],
@@ -814,7 +814,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 
 		// If we extracted Exa API keys from MCP configs and EXA_API_KEY isn't set, use the first one
 		if (mcpResult.exaApiKeys.length > 0 && !$env.EXA_API_KEY) {
-			process.env.EXA_API_KEY = mcpResult.exaApiKeys[0];
+			Bun.env.EXA_API_KEY = mcpResult.exaApiKeys[0];
 		}
 
 		// Log MCP errors

package/src/system-prompt.ts

@@ -193,15 +193,15 @@ async function getGpuModel(): Promise<string | null> {
 }
 
 function getTerminalName(): string {
-	const termProgram = process.env.TERM_PROGRAM;
-	const termProgramVersion = process.env.TERM_PROGRAM_VERSION;
+	const termProgram = Bun.env.TERM_PROGRAM;
+	const termProgramVersion = Bun.env.TERM_PROGRAM_VERSION;
 	if (termProgram) {
 		return termProgramVersion ? `${termProgram} ${termProgramVersion}` : termProgram;
 	}
 
-	if (process.env.WT_SESSION) return "Windows Terminal";
+	if (Bun.env.WT_SESSION) return "Windows Terminal";
 
-	const term = firstNonEmpty(process.env.TERM, process.env.COLORTERM, process.env.TERMINAL_EMULATOR);
+	const term = firstNonEmpty(Bun.env.TERM, Bun.env.COLORTERM, Bun.env.TERMINAL_EMULATOR);
 	return term ?? "unknown";
 }
 
@@ -216,12 +216,12 @@ function normalizeDesktopValue(value: string): string {
 }
 
 function getDesktopEnvironment(): string {
-	if (process.env.KDE_FULL_SESSION === "true") return "KDE";
+	if (Bun.env.KDE_FULL_SESSION === "true") return "KDE";
 	const raw = firstNonEmpty(
-		process.env.XDG_CURRENT_DESKTOP,
-		process.env.DESKTOP_SESSION,
-		process.env.XDG_SESSION_DESKTOP,
-		process.env.GDMSESSION,
+		Bun.env.XDG_CURRENT_DESKTOP,
+		Bun.env.DESKTOP_SESSION,
+		Bun.env.XDG_SESSION_DESKTOP,
+		Bun.env.GDMSESSION,
 	);
 	return raw ? normalizeDesktopValue(raw) : "unknown";
 }
@@ -252,10 +252,10 @@ function matchKnownWindowManager(value: string): string | null {
 }
 
 function getWindowManager(): string {
-	const explicit = firstNonEmpty(process.env.WINDOWMANAGER);
+	const explicit = firstNonEmpty(Bun.env.WINDOWMANAGER);
 	if (explicit) return explicit;
 
-	const desktop = firstNonEmpty(process.env.XDG_CURRENT_DESKTOP, process.env.DESKTOP_SESSION);
+	const desktop = firstNonEmpty(Bun.env.XDG_CURRENT_DESKTOP, Bun.env.DESKTOP_SESSION);
 	if (desktop) {
 		const matched = matchKnownWindowManager(desktop);
 		if (matched) return matched;

package/src/tools/index.ts

@@ -239,7 +239,7 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		!skipPythonPreflight &&
 		pythonMode !== "bash-only" &&
 		(requestedTools === undefined || requestedTools.includes("python"));
-	const isTestEnv = process.env.BUN_ENV === "test" || process.env.NODE_ENV === "test";
+	const isTestEnv = Bun.env.BUN_ENV === "test" || Bun.env.NODE_ENV === "test";
 	const skipPythonWarm = isTestEnv || $env.PI_PYTHON_SKIP_CHECK === "1";
 	if (shouldCheckPython) {
 		const availability = await checkPythonKernelAvailability(session.cwd);