Configuration & Settings

Every key below is declared in settings-keys.json at the repository root, which is the source of truth for types, defaults, ranges, and env var names. This page covers the common ones; settings-keys.json lists the rest.

Settings Files

Both settings files accept .jsonc (JSON with comments) or plain .json. If a directory contains both names, the .jsonc file is used and the .json file is ignored.

Project settings file

{
  "pidash_enable": true,
  "pidash_port": 19190,
  "cli_agents": ["claude", "cursor"]
}

Global settings file

{
  "dream_interval_hours": 6,
  "review_loop_enforcement": true
}

Resolution order

project file -> global file -> environment variable -> default

Editing settings without a text editor

/pi-config-settings

Use it when you would rather not guess an env var name or a numeric range — the TUI shows the valid values for every key. For the internals — source indicators, smart pickers, and how writes are performed — see Project Settings Internals.

Git & Workflow Keys

commit_trailer

Note: A comma-separated string such as "Assisted-by,Co-authored-by" is treated as a list of trailer names; the user picks one per session and the choice is reused. The injected value is <Trailer>: PI (<model-id>) <noreply@pi.dev>.

{
  "commit_trailer": "Assisted-by"
}

export PI_COMMIT_TRAILER="Assisted-by"

allow_push_to_protected_branches

{
  "allow_push_to_protected_branches": true
}

export PI_ALLOW_PUSH_TO_PROTECTED_BRANCHES=true

use_worktrees

{
  "use_worktrees": true
}

export PI_USE_WORKTREES=true

dco

{
  "dco": true
}

export PI_DCO=true

orchestrator_edit_write_block

{
  "orchestrator_edit_write_block": true
}

See Managing Custom Agents for details.

Review & PR Keys

comment_signature

{
  "comment_signature": true
}

See Automating Code Reviews for details.

review_loop_enforcement

{
  "review_loop_enforcement": true
}

export PI_REVIEW_LOOP_ENFORCEMENT=true

See Automating Code Reviews for details.

review_loop_max_cycles

Warning: Accepted values are integers 1 through 10, or digit strings "1" through "10". Values such as 0, 11, "01", "10.0", "1e1", and "inf" are ignored.

{
  "review_loop_max_cycles": 5
}

export PI_REVIEW_LOOP_MAX_CYCLES=7

See Automating Code Reviews for details.

Provider Registration & Model Routing

cli_agents

Note: Values are lowercased, deduplicated, and invalid names are filtered out.

Tip: Set an explicit empty array ([]) in the project file to override inherited global or environment values.

{
  "cli_agents": ["claude", "cursor"]
}

export CLI_AGENTS="Cursor,Gemini"

See External AI Agents & CLI for details.

acpx_agents

Note: Values are lowercased, deduplicated, and any name that is not [a-z0-9_-]+ is dropped. Unlike cli_agents, the name is not checked against a built-in list — it must match an agent the acpx binary can launch.

{
  "acpx_agents": ["cursor"]
}

export ACPX_AGENTS="cursor,claude"

See ACPX Provider Integration for details.

agent_provider

{
  "agent_provider": "cli-cursor"
}

agent_model

{
  "agent_model": "cursor:cursor-grok-4.5-high-fast"
}

agent_overrides

{
  "agent_provider": "cli-cursor",
  "agent_model": "cursor:cursor-grok-4.5-high-fast",
  "agent_overrides": {
    "debugger": {
      "provider": null,
      "model": null
    },
    "reviewer": {
      "provider": "cli-claude",
      "model": "claude-sonnet"
    }
  }
}

See Managing Custom Agents for details.

vertex_claude_1m

{
  "vertex_claude_1m": true
}

export VERTEX_CLAUDE_1M=true

See Vertex Claude Provider for details.

Dashboard & UI Keys

pidash_enable

Note: Environment values false, 0, no, and off disable pidash.

{
  "pidash_enable": false
}

export PI_PIDASH_ENABLE=false

pidiff_enable

Note: Environment values false, 0, no, and off disable pidiff.

{
  "pidiff_enable": false
}

export PI_PIDIFF_ENABLE=off

pidash_port

Warning: Only integer values in the range 1-65535 are accepted. Invalid values fall back to the next resolution layer or the default.

{
  "pidash_port": 19191
}

export PI_PIDASH_PORT=19191

See Using the Web Dashboard for details.

pidiff_daemon_startup_timeout_s

Warning: Only integer values in the range 10-300 are accepted. Invalid values fall back to the next resolution layer or the default.

{
  "pidiff_daemon_startup_timeout_s": 120
}

export PI_PIDIFF_DAEMON_STARTUP_TIMEOUT_S=120

pidiff_stale_lock_timeout_ms

{
  "pidiff_stale_lock_timeout_ms": 60000
}

export PI_PIDIFF_STALE_LOCK_TIMEOUT_MS=60000

image_model

{
  "image_model": "gemini-3-pro-image"
}

export PI_IMAGE_MODEL=gemini-3-pro-image

See Image Generation for details.

Code Map Keys

trail_enable

{
  "trail_enable": true
}

export PI_TRAIL_ENABLE=true

Background & Async Keys

dream_interval_hours

{
  "dream_interval_hours": 6
}

export PI_DREAM_INTERVAL_HOURS=6

See Background Memory Consolidation (Dreaming) for details.

Memory tuning keys

These keys tune the memory system's budgets and similarity gates (issue #915). All defaults match the pre-setting hardcoded values.

{
  "memory_token_budget": 2000,
  "memory_inject_similarity": 0.7
}

See Memory Architecture for what each gate does.

internal_operations_provider

{
  "internal_operations_provider": "openai"
}

export PI_INTERNAL_OPERATIONS_PROVIDER=openai

internal_operations_model

{
  "internal_operations_model": "gpt-5.4"
}

export PI_INTERNAL_OPERATIONS_MODEL=gpt-5.4

Warning: Both internal_operations_provider and internal_operations_model must be set together. If either is missing, must-async work is skipped.

Warning: internal_operations_provider cannot be an acpx-* provider ID. Non-must-async work is coerced to sync instead of using the sidecar.

See Running Background Agents and Scheduled Tasks for details.

sync_agent_max_seconds

Warning: Only integer values in the range 10-300 are accepted. Invalid values fall back to the next resolution layer or the default.

{
  "sync_agent_max_seconds": 120
}

export PI_SYNC_AGENT_MAX_SECONDS=120

async_poll_interval_ms

Warning: Only integer values in the range 500-30000 are accepted. Invalid values fall back to the next resolution layer or the default.

{
  "async_poll_interval_ms": 5000
}

export PI_ASYNC_POLL_INTERVAL_MS=5000

async_phantom_timeout_ms

Warning: Only integer values in the range 5000-120000 are accepted. Invalid values fall back to the next resolution layer or the default.

{
  "async_phantom_timeout_ms": 60000
}

export PI_ASYNC_PHANTOM_TIMEOUT_MS=60000

See Running Background Agents and Scheduled Tasks for details.

Provider Stream Logging

log_providers

export PI_LOG_PROVIDERS=debug

The stream is written to ~/.pi/logs/providers/<session-id>/main.log under a [provider-stream] prefix, with one line per event and credential-shaped fields redacted. Capturing every event has a real cost, so the hook only registers at debug and costs nothing at the default level.

Every other log_<module> key follows the same shape — log_pidash, log_pidiff, log_coms, log_subagent, log_dreaming, log_enforcement, log_trail, and others — with env vars PI_LOG_<MODULE> and default info. The remaining module log levels are listed in Module File Logging below.

Safety Enforcement Keys

enforcement_sleep_threshold_s

{
  "enforcement_sleep_threshold_s": 30
}

export PI_ENFORCEMENT_SLEEP_THRESHOLD_S=30

enforcement_loop_sleep_threshold_s

{
  "enforcement_loop_sleep_threshold_s": 10
}

export PI_ENFORCEMENT_LOOP_SLEEP_THRESHOLD_S=10

enforcement_allowed_commands

{
  "enforcement_allowed_commands": "sleep 5, ls -la"
}

export PI_ENFORCEMENT_ALLOWED_COMMANDS="sleep 5,ls -la"

Warning: this is an exemption list for the enforcement guards. Anything added here runs past them, so keep it as narrow as the task allows.

See Safety Enforcements for details.

Inter-Agent Communication Keys

coms_task_heartbeat_ms

{
  "coms_task_heartbeat_ms": 60000
}

export PI_COMS_TASK_HEARTBEAT_MS=60000

coms_probe_timeout_ms

{
  "coms_probe_timeout_ms": 500
}

export PI_COMS_PROBE_TIMEOUT_MS=500

coms_timeout_ms

{
  "coms_timeout_ms": 1800000
}

export PI_COMS_TIMEOUT_MS=1800000

coms_max_hops

{
  "coms_max_hops": 5
}

export PI_COMS_MAX_HOPS=5

coms_entry_grace_period_ms

{
  "coms_entry_grace_period_ms": 30000
}

export PI_COMS_ENTRY_GRACE_PERIOD_MS=30000

coms_dir

{
  "coms_dir": "/run/user/1000/coms"
}

export PI_COMS_DIR=/run/user/1000/coms

See Inter-Agent Communication for details.

Sidecar Server Logging

sidecar_log_level

{
  "sidecar_log_level": "debug"
}

export PI_SIDECAR_LOG_LEVEL=debug

See Pi-Sidecar for details.

Module File Logging

Each key below is a level string, not a boolean. Accepted values are off, debug, info, warn, and error; anything else is ignored and the next resolution layer is used. off disables the module's file log entirely.

A module resolves its level in this order: the log_<module> setting → the PI_LOG_<MODULE> environment variable → info. Lines below that level are dropped before the file is touched, and the resolved level is cached for 30 seconds.

Note: Async agent logs nest under the parent pi session directory, not the subagent's own session id, so a whole job tree stays in one place. Subagent and child-process logs use the same <name>/<parent-session-id>/<file> layout.

{
  "log_orchestrator": "debug",
  "log_async_agents": "debug"
}

export PI_LOG_ORCHESTRATOR=debug

Tip: The Settings TUI renders each of these as a select list from the schema enum, so the valid values never have to be remembered.

Task Lifecycle Keys

task_auto_clear_enabled

{
  "task_auto_clear_enabled": false
}

export PI_TASK_AUTO_CLEAR_ENABLED=false

task_auto_clear_minutes

Warning: Only integer values in the range 1-1440 are accepted. Invalid values fall back to the next resolution layer or the default.

{
  "task_auto_clear_minutes": 60
}

task_reminder_enabled

{
  "task_reminder_enabled": false
}

export PI_TASK_REMINDER_ENABLED=false

task_reminder_interval_minutes

Warning: Only integer values in the range 1-60 are accepted. Invalid values fall back to the next resolution layer or the default.

{
  "task_reminder_interval_minutes": 30
}

task_stale_in_progress_enabled

{
  "task_stale_in_progress_enabled": false
}

export PI_TASK_STALE_IN_PROGRESS_ENABLED=false

task_stale_in_progress_minutes

Warning: Only integer values in the range 5-1440 are accepted. Invalid values fall back to the next resolution layer or the default.

{
  "task_stale_in_progress_minutes": 60
}

See Managing Custom Agents for details.

Environment-only Process Flag

PI_SUBAGENT_CHILD

PI_SUBAGENT_CHILD=1

See Running Background Agents and Scheduled Tasks for details.

Related Pages

• Installation & Quickstart
• Daemon & Websocket Networking
• Curating Project Memory
• Running Background Agents and Scheduled Tasks
• ACPX Provider Integration