oh-my-pi/packages/coding-agent/docs/environment-variables.md

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)