Configuration & Settings

This page serves as a comprehensive reference for configuring the Pi environment, overriding defaults, and registering CLI or asynchronous agents.

Configuration values resolve in the following order (highest precedence first):

  1. Project settings: <project-root>/.pi/pi-config-settings.json
  2. Global settings: ~/.pi/pi-config-settings.json
  3. Environment variables: E.g., PI_COMMIT_TRAILER
  4. Default values

Core Settings

Settings that modify the orchestrator's behavior, git operations, and default parameters.

commit_trailer

Appends a custom git commit trailer (e.g., Assisted-by) to every commit generated by the agent.

Parameter Type Default Env Var Description
commit_trailer boolean | string false PI_COMMIT_TRAILER If a string, adds the trailer String: PI (<model>). If multiple comma-separated names are given, the UI asks the user which one to apply. false disables it. 
{
  "commit_trailer": "Assisted-by"
}

use_worktrees

Forces the agent to use git worktrees rather than switching branches in the main working directory.

Parameter Type Default Env Var Description
use_worktrees boolean false PI_USE_WORKTREES If enabled, the agent executes tasks in isolated git worktrees. 
{
  "use_worktrees": true
}

dco

Enforces the Developer Certificate of Origin on all git commits.

Parameter Type Default Env Var Description
dco boolean false PI_DCO Adds the --signoff flag to all commits made by the orchestrator or subagents. 
{
  "dco": true
}

comment_signature

Appends a small AI signature identifier to PR comments left by the agent.

Parameter Type Default Env Var Description
comment_signature boolean false None Whether to add an AI branding signature to PR comments. 
{
  "comment_signature": true
}

orchestrator_edit_write_block

Restricts the orchestrator agent from directly altering files.

Parameter Type Default Env Var Description
orchestrator_edit_write_block boolean false None Blocks the orchestrator from using edit and write tools directly, forcing it to delegate file modification tasks to subagents. 
{
  "orchestrator_edit_write_block": true
}

Agent Configuration

Configuration determining default models, external agent execution, and specific tool assignments. For creating new agent roles, see Managing Custom Agents.

cli_agents

Registers specific model providers to run purely via CLI execution environments (such as Cursor, Claude, or Gemini). See External AI Agents & CLI for detailed usage.

Parameter Type Default Env Var Description
cli_agents string | string[] [] CLI_AGENTS The list of agents to register as cli-* providers. Valid formats include a comma-separated string or an array of strings. 
{
  "cli_agents": ["cursor", "claude"]
}

acpx_agents

Registers specific models for executing asynchronous subagent routines.

Parameter Type Default Env Var Description
acpx_agents string | string[] [] ACPX_AGENTS The list of agents to register as acpx-* models. Enables detached, fire-and-forget capabilities. 
{
  "acpx_agents": ["cursor"]
}

agent_provider and agent_model

Sets the fallback default execution provider and model string for spawned subagents.

Parameter Type Default Env Var Description
agent_provider string "" None Default provider for all subagents (e.g. cli-cursor).
agent_model string "" None Default model ID for all subagents. 
{
  "agent_provider": "cli-cursor",
  "agent_model": "cursor:cursor-grok-4.5-high-fast"
}

agent_overrides

Overrides the global fallback provider or model for specifically named subagents.

Parameter Type Default Env Var Description
agent_overrides object {} None Per-agent provider/model mapping. Setting a value to null forces the subagent to inherit the parent session's model. 
{
  "agent_overrides": {
    "test-automator": {
      "provider": "cli-claude",
      "model": "claude-3-5-sonnet"
    },
    "reviewer": {
      "provider": null,
      "model": null
    }
  }
}

image_model

Specifies the model to use when generating images from tools. See Image Generation for exact capabilities.

Parameter Type Default Env Var Description
image_model string "" PI_IMAGE_MODEL Set to a valid Gemini image generation model string (e.g. gemini-3-pro-image). 
{
  "image_model": "gemini-3-pro-image"
}

Background Task Configuration

Controls the timing and detached execution configurations for background operations.

dream_interval_hours

Configures how often the background dream routines execute to index or score session topics.

Parameter Type Default Env Var Description
dream_interval_hours number 3 PI_DREAM_INTERVAL_HOURS Time between automated project dream phases in hours. 
{
  "dream_interval_hours": 4
}

async_llm_provider and async_llm_model

Explicitly defines what provider/model to route LLM queries to when the parent session is operating purely through acpx (which lacks native LLM tools itself).

Parameter Type Default Env Var Description
async_llm_provider string "" PI_ASYNC_LLM_PROVIDER Provider for detached LLM async children. Both provider and model must be set.
async_llm_model string "" PI_ASYNC_LLM_MODEL Model ID for detached LLM async children. If unset, the system drops pending must-async LLM operations. 
{
  "async_llm_provider": "cli-gemini",
  "async_llm_model": "gemini-2.5-pro"
}

Environment Variables only

These configurations apply globally via shell profiles and cannot be embedded in pi-config-settings.json.

Note: The current project settings resolution does support falling back to environment variables for many configurations detailed above. The following variables exist exclusively as environment or process flags.

Variable Description
PI_SUBAGENT_CHILD When set to "1", signals that the current process is a background subagent execution. Bypasses settings cache resets and UI mounts.