3.9 KiB
title, task, lineage_type, upstream_source, upstream_sha, imported_at, prompt_class, upstream_changes, author, validated
| title | task | lineage_type | upstream_source | upstream_sha | imported_at | prompt_class | upstream_changes | author | validated |
|---|---|---|---|---|---|---|---|---|---|
| Environment Variables | import | https://github.com/K-Dense-AI/scientific-agent-skills/blob/b2a92ba0/skills/pi-agent/references/environment-variables.md | b2a92ba0 | 2026-08-14 | prompt | accepted | upstream | false |
Environment Variables
Source: https://pi.dev/docs/latest/environment-variables
Pi uses environment variables three ways: variables that configure the Pi process, markers Pi sets so child processes know they run inside Pi, and session metadata injected into commands run by the LLM-callable bash tool. Provider API-key variables live in references/providers.md.
Process Markers
The CLI and RPC entry points set two markers:
AI_AGENT=pi— generic marker letting tooling identify Pi as the launching agent.PI_CODING_AGENT=true— Pi-specific marker for detecting that a process runs inside Pi.
Child processes inherit both. Neither is session-specific, and neither is set automatically when Pi is embedded through the SDK.
Bash Tool Session Environment
Commands run by the LLM-callable bash tool receive:
| Variable | Description |
|---|---|
PI_SESSION_ID |
Current session ID |
PI_SESSION_FILE |
Absolute path to the session JSONL file; unset for ephemeral sessions |
PI_PROVIDER |
Currently selected model provider |
PI_MODEL |
Currently selected model ID |
PI_REASONING_LEVEL |
Effective reasoning level: off, minimal, low, medium, high, xhigh, max |
Values resolve when each command starts, so switching models affects the next bash command without restarting. PI_PROVIDER/PI_MODEL identify the selected Pi model, not an upstream model a router picks internally. When asked which model is running, inspect these variables instead of inferring from the system prompt:
printf '%s/%s\n' "$PI_PROVIDER" "$PI_MODEL"
These are injected into the LLM-callable bash tool only — not into user-entered ! or !! commands.
Custom bash tools built with createBashTool() expose the same variables by default, injected before spawnHook so hooks see them in ctx.env. Disable with exposeSessionEnvironment: false; Pi then also clears inherited values so nested Pi processes do not leak stale parent-session metadata.
Pi Process Configuration
| Variable | Description |
|---|---|
PI_CODING_AGENT_DIR |
Override the config directory; default ~/.pi/agent |
PI_CODING_AGENT_SESSION_DIR |
Override session storage; overridden by --session-dir |
PI_PACKAGE_DIR |
Override the package directory (useful for Nix/Guix store paths) |
PI_OFFLINE |
Disable startup network operations: update checks, package updates, install/update telemetry |
PI_SKIP_VERSION_CHECK |
Disable the pi.dev latest-version request |
PI_TELEMETRY |
Override install/update telemetry and provider attribution headers: 1/true/yes or 0/false/no |
PI_CACHE_RETENTION |
Set to long for extended provider prompt caching where supported |
PI_SHARE_VIEWER_URL |
Override the base URL used by /share |
PI_HARDWARE_CURSOR |
Set to 1 to show the hardware cursor (IME positioning) |
PI_TUI_ESC_TIMEOUT |
Milliseconds to wait after a lone ESC before treating it as Escape; defaults to 100 over SSH and 10 otherwise. Increase when Alt-key input is misread as Escape |
VISUAL, EDITOR |
External editor fallback when the externalEditor setting is unset |
HTTP_PROXY, HTTPS_PROXY |
Proxy outbound HTTP requests |
Names are derived from the rebrandable app name (package.json piConfig.name), so a fork uses a different prefix — see references/development.md.
Other variables documented elsewhere: PI_EXPERIMENTAL (experimental first-time setup, references/settings.md), PI_TUI_WRITE_LOG (raw ANSI capture, references/tui.md), AWS_BEDROCK_FORCE_CACHE and other cloud variables (references/providers.md), LLAMA_BASE_URL/LLAMA_API_KEY (references/llama-cpp.md).