Configuration and Environment Variables Reference

All configuration options for pi-config: project settings, environment variables, rules loading, and CodeRabbit setup.

For Docker-specific deployment configuration, see Running Pi in a Docker Container. For agent definitions and routing, see Specialist Agents Reference. For rule content and behavior, see Orchestrator Rules Reference.

Project Settings File

Location: .pi/pi-config-settings.json (relative to project root)

Project-level settings override environment variables and defaults. The file is loaded once and cached for 30 seconds before re-checking for changes.

Resolution order: Project file → Environment variable → Default

Settings Fields

Example File

{
  "co_author": true,
  "use_worktrees": false,
  "dream_interval_hours": 3
}

Note: Unknown keys in the file are preserved during migration but ignored by the settings loader. Only the three fields above are read.

Legacy Migration

If a .pi-co-author file exists in the project root, the settings module automatically migrates it to pi-config-settings.json with co_author: true on session_start, then deletes the legacy file. Symlink attacks are detected and skipped.

Environment Variables

Core Project Settings

These environment variables serve as fallbacks when the corresponding field is not set in .pi/pi-config-settings.json.

export PI_CO_AUTHOR=true
export PI_USE_WORKTREES=false
export PI_DREAM_INTERVAL_HOURS=3

ACPX Provider

# Single agent
export ACPX_AGENTS="cursor"

# Multiple agents
export ACPX_AGENTS="cursor,claude,gemini,copilot"

Agent names are validated against the pattern /^[a-z0-9_-]+$/i. Invalid names are silently filtered out. Each registered agent creates a provider named acpx-<agent> with models discovered at session start via the ACPX runtime library.

Note: ACPX providers are skipped entirely in subagent processes (PI_SUBAGENT_CHILD=1). Subagents use the parent session's model via --model flag.

Image Generation

export PI_IMAGE_MODEL="gemini-2.0-flash-exp"
export GEMINI_API_KEY="your-key-here"

Warning: Both PI_IMAGE_MODEL and an API key (GEMINI_API_KEY or GOOGLE_API_KEY) must be set for the generate_image tool to function. Missing either variable returns an error message to the LLM.

Dashboard and Diff Viewer

export PI_PIDASH_PORT=19190
export PI_PIDIFF_PORT=19290

# Disable dashboards
export PI_PIDASH_ENABLE=false
export PI_PIDIFF_ENABLE=false

For more on dashboards, see Using the Web Dashboard and Diff Viewer.

Discord Bot Integration

These variables configure the Discord bot embedded in the pidash daemon server.

export DISCORD_BOT_TOKEN="your-discord-bot-token"
export DISCORD_ALLOWED_USERS="123456789,987654321"

Warning: If DISCORD_ALLOWED_USERS is not set, all DMs to the bot are accepted.

Alternatively, credentials can be placed in ~/.pi/discord.env as KEY=VALUE lines (one per line). The pidash server reads this file at startup.

P2P Communication (Coms)

export PI_COMS_DIR="$HOME/.pi/coms"
export PI_COMS_MAX_HOPS=5

For more on inter-agent communication, see Communicating Between Pi Sessions.

Networked Communication (Coms-Net)

Client Variables

Server Variables

# Local auto-discovery (default)
# No env vars needed — client reads ~/.pi/coms-net/server.json

# Remote connection
export PI_COMS_NET_SERVER_URL="http://hub.example.com:8080"
export PI_COMS_NET_AUTH_TOKEN="your-auth-token"
export PI_COMS_NET_PROJECT="my-project"

Container and Docker

export PI_HOST_USER=myakove

When PI_HOST_USER is set to a value other than "node", the init entrypoint:

1. Creates /home/<PI_HOST_USER> with correct ownership
2. Symlinks container tool directories (.npm-global, .cache, .local, etc.) into the new HOME
3. Creates reverse symlinks in /home/node pointing to mounted content
4. Sets HOME and updates PATH to include the new home-based directories

Git and SSH

Note: The SSH timeout configuration detects dead connections during git fetch/push/pull. The keepalive sends a probe every 15 seconds, gives up after 3 missed responses (45 seconds total), and fails connections that don't establish within 10 seconds.

Debugging and Internal

Warning: Do not set PI_SUBAGENT_CHILD or PI_AGENT_NAME manually — they are managed internally by the subagent spawning system.

Rules Loading Order

Orchestrator rules are auto-loaded from the rules/ directory in alphabetical order on every before_agent_start event. Files must end in .md. Numeric prefixes control ordering.

Note: Rules are loaded into the orchestrator system prompt only — specialist agents (subagents) do not receive orchestrator rules. Subagents receive only the memory situation report.

For detailed rule content, see Orchestrator Rules Reference.

Adding a Custom Rule

Place a .md file in rules/ with a numeric prefix to control ordering:

# Loads after agent routing but before code review loop
rules/12-my-custom-rule.md

Changes take effect on the next pi session — running sessions are not affected.

Agent Discovery Order

Agents are discovered from three sources in priority order (later sources override earlier):

Agent files use Markdown with YAML frontmatter:

---
name: my-agent
description: What this agent does
tools: read, write, edit, bash
model: optional-model-override
---

System prompt instructions here...

For the full list of bundled agents, see Specialist Agents Reference.

Async-Only Agents

The following agents are enforced to run with async: true only. Synchronous calls are automatically promoted to async by the subagent tool:

• code-reviewer-quality
• code-reviewer-guidelines
• code-reviewer-security

This list is defined in the ASYNC_ONLY_AGENTS set in extensions/orchestrator/subagent-tool.ts.

CodeRabbit Configuration

Location: .coderabbit.yaml (project root)

Pi-config ships a CodeRabbit configuration for local AI code reviews via the CodeRabbit CLI (cr command).

language: en-US
reviews:
  profile: assertive
  poem: false
  sequence_diagrams: false
  auto_review:
    enabled: false  # Uses CLI, not PR auto-review

Enabled Linters

Disabled Linters

PHP (phpstan, phpmd, phpcs), Ruby (rubocop), Swift (swiftlint), Kotlin (detekt), Java (pmd), Protobuf (buf), SQL (sqlfluff), Terraform (tflint), IaC (checkov), Rust (clippy).

Knowledge Base

knowledge_base:
  code_guidelines:
    enabled: true  # Auto-picks up AGENTS.md

Memory System Files

The memory system uses several files under .pi/memory/. These are not directly edited but are referenced by configuration.

Tip: Add .pi/memory/ to your global gitignore to prevent committing memory data. The container entrypoint does this automatically.

For memory system internals, see Memory Scoring, Embeddings, and Situation Reports.

Temp Directory Structure

All runtime data lives under project-scoped temp directories.

Base path: /tmp/pi-data/<project>/

Project name format: cwd with / replaced by __ (e.g., home__user__git__my-project).

The helper function getProjectTmpDir(cwd) in extensions/orchestrator/utils.ts creates and returns the project temp directory.

Mode-Aware Feature Guards

Pi operates in four modes. Extensions use ctx.mode to conditionally enable features.

Extension Registration Order

The orchestrator extension (extensions/orchestrator/index.ts) registers modules in a specific order. Some modules depend on others being registered first.

1. registerExtendedAutocomplete — Must be first (wraps registerCommand for completions)
2. registerAskUser — ask_user tool
3. registerAsyncAgents — Background agent infrastructure (provides spawnAsyncAgent)
4. registerSubagentTool — Subagent tool (depends on async agents)
5. registerProjectSettings — Settings migration and cache
6. registerEnforcement — Command blocking rules
7. registerRules — Rule injection and memory loading (depends on async agent job list)
8. registerStatusLine — Git status, container indicator
9. registerBtw — /btw side questions
10. registerDreaming — Memory consolidation (depends on spawnAsyncAgent)
11. registerCron — Scheduled tasks (depends on spawnAsyncAgent)
12. registerSessionValidation — Tool checks, upgrade notifications
13. registerGithubAutocomplete — GitHub issue # autocomplete
14. registerStatus — /status command
15. registerNvim — Neovim integration
16. registerPreferenceExtractor — Auto-extract user preferences
17. registerMemoryTools — AI-accessible memory tools
18. registerSessionSearch — Session history keyword search

Required and Optional CLI Tools

Checked on session_start by the session validation module.

Required

Optional

Related Pages

• Running Pi in a Docker Container
• Customization and Extension Recipes
• Working with Project Memory
• Orchestrator Rules Reference
• Extension Architecture and Lifecycle Hooks