Environment variables

Resolution order

omp resolves env vars through a layered .env chain. The first source that defines a key wins:

1. The existing process environment.

2. $PWD/.env — the project’s .env in the directory omp was launched from.

3. ~/.omp/agent/.env — or $PI_CODING_AGENT_DIR/.env / $PI_CONFIG_DIR/agent/.env if those are set.

4. ~/.omp/.env — honouring PI_CONFIG_DIR.

5. ~/.env — your home .env.

Inside each .env file, keys written as OMP_FOO are mirrored to PI_FOO, so old configs from the OMP_* era still work without renaming. Settings in ~/.omp/agent/config.yml override built-in defaults; CLI flags override both. See CLI reference for the flag list.

Env vars are read at startup. After editing ~/.env or a project .env, restart omp.

Treat anything ending in _API_KEY, _TOKEN, or _OAUTH_TOKEN as a secret. Never commit .env files; never paste them into chat logs. chmod 600 any .env file containing credentials.

.env file format

One KEY=value per line, # for comments, quotes optional but recommended for values containing spaces or shell metacharacters. No interpolation, no export keyword required.

# ~/.omp/.env — applies to every project
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
PI_SLOW_MODEL="openai/gpt-5.3-codex:high"
PI_NO_PTY=1

Runtime knobs

The flags people reach for most often. Each has a higher-priority CLI flag or settings key; the env var is the lowest-friction way to set one for a shell session or CI job.

| Variable | What it does | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | | PI_CODING_AGENT_DIR | Move the agent data directory off ~/.omp/agent — useful on shared boxes or when isolating profiles. | | PI_CONFIG_DIR | Rename the config root under $HOME (default .omp). Agent dir becomes ~/<PI_CONFIG_DIR>/agent unless PI_CODING_AGENT_DIR is also set. | | PI_PACKAGE_DIR | Point package asset resolution (docs, examples, changelog) at a custom install path — handy on Nix/Guix. | | PI_SMOL_MODEL | Pin the smol role for the session. CLI --smol wins if both are set. | | PI_SLOW_MODEL | Pin the slow/reasoning role. CLI --slow wins. | | PI_PLAN_MODEL | Pin the plan role. CLI --plan wins. | | PI_NO_PTY | Set to 1 to disable the PTY path of the bash tool. Equivalent to --no-pty. | | PI_PY | Gate the Python backend of the eval tool: truthy (1/true/yes/on) enables, any other value disables; unset defers to the eval.py setting (default enabled). | | PI_JS | Companion gate for the JavaScript backend of eval (eval.js setting). | | OMP_GITHUB_CACHE_DB | Override the SQLite cache file backing pr:// and issue://. Default ~/.omp/cache/github-cache.db. | | OMP_AUTORESEARCH_DB_DIR | Override the directory holding the autoresearch SQLite database. | | VISUAL, EDITOR | Preferred external editor and fallback, used by Ctrl+G. | | PUPPETEER_EXECUTABLE_PATH | Tell the browser tool which Chromium binary to launch. | |

Provider credentials

One key per provider you want to use. For Anthropic, OpenAI Codex, GitHub Copilot, Kimi, Cursor, and Qwen Portal, interactive /login writes OAuth credentials to ~/.omp/agent/agent.db and is usually less hassle than managing API keys. See Providers for the full OAuth matrix and login flows.

Cloud providers

Anthropic Foundry & mTLS

Reach for this when your organisation fronts Anthropic with an Azure Foundry or enterprise gateway that needs custom headers or a client certificate. Setting CLAUDE_CODE_USE_FOUNDRY flips the Anthropic provider into Foundry mode for both streaming and search.

Anthropic resolution with Foundry enabled becomes ANTHROPIC_FOUNDRY_API_KEY → ANTHROPIC_OAUTH_TOKEN → ANTHROPIC_API_KEY; otherwise OAuth token then API key.

Amazon Bedrock

Region resolves options.region → AWS_REGION → AWS_DEFAULT_REGION → us-east-1.

Azure OpenAI Responses

Base URL resolves option → AZURE_OPENAI_BASE_URL → AZURE_OPENAI_RESOURCE_NAME → the model’s default.

Google Vertex AI

Web search

Credentials and endpoint overrides for built-in web-search providers. Some keys (e.g. Z.AI, Anthropic search) are also read by the corresponding model provider.

Eval & Python kernel

When BUN_ENV=test or NODE_ENV=test, Python availability checks are treated as OK and warming is skipped. The Python runner strips common API-key vars from its subprocess env and only forwards LC_, XDG_, and PI_ prefixes plus a safe base set.

Subagent caps

Behaviour toggles

Performance & debug

Local server discovery

Shell execution

How the bash tool wraps the user’s shell when running commands. Each PI_* key has a legacy CLAUDE_* alias that still works.

TUI runtime

Terminal-side knobs. Most are auto-detected; set these only when the defaults misbehave.

Commit pipeline

The /commit slash command and the underlying commit agent honour these toggles. Mostly used during development of the commit pipeline itself.

| Variable | Behavior | | ------------------------- | ------------------------------------------------------------------------------------- | --- | | PI_COMMIT_TEST_FALLBACK | If true, force the heuristic fallback path instead of asking the agent. | | PI_COMMIT_NO_FALLBACK | If true, leave the proposal empty when the agent doesn’t produce one (no fallback). | | PI_COMMIT_MAP_REDUCE | If false, disable the map-reduce analysis path for large diffs. | | DEBUG | If set, the commit agent prints its full error stack on failure. | \n |