pi-mono-master
  • English

      • Settings

      Pi uses JSON settings files with project settings overriding global settings.

      LocationScope
      ~/.pi/agent/settings.jsonGlobal (all projects)
      .pi/settings.jsonProject (current directory)

      Edit directly or use /settings for common options.

      All Settings

      Model & Thinking

      SettingTypeDefaultDescription
      defaultProviderstring-Default provider (e.g., "anthropic", "openai")
      defaultModelstring-Default model ID
      defaultThinkingLevelstring-"off", "minimal", "low", "medium", "high", "xhigh"
      hideThinkingBlockbooleanfalseHide thinking blocks in output
      thinkingBudgetsobject-Custom token budgets per thinking level

      thinkingBudgets

      {
  "thinkingBudgets": {
    "minimal": 1024,
    "low": 4096,
    "medium": 10240,
    "high": 32768
  }
}

      UI & Display

      SettingTypeDefaultDescription
      themestring"dark"Theme name
      quietStartupbooleanfalseHide startup header
      collapseChangelogbooleanfalseCondensed changelog after updates
      doubleEscapeActionstring"tree"Double-escape: "tree", "fork", or "none"
      editorPaddingXnumber0Horizontal padding (0-3)
      autocompleteMaxVisiblenumber5Max autocomplete items (3-20)
      showHardwareCursorbooleanfalseShow terminal cursor

      Compaction

      SettingTypeDefaultDescription
      compaction.enabledbooleantrueEnable auto-compaction
      compaction.reserveTokensnumber16384Tokens reserved for response
      compaction.keepRecentTokensnumber20000Recent tokens to keep
      {
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

      Branch Summary

      SettingTypeDefaultDescription
      branchSummary.reserveTokensnumber16384Tokens reserved for branch summarization

      Retry

      SettingTypeDefaultDescription
      retry.enabledbooleantrueEnable automatic retry
      retry.maxRetriesnumber3Max retry attempts
      retry.baseDelayMsnumber2000Base delay for exponential backoff
      retry.maxDelayMsnumber60000Max server-requested delay before failing
      {
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 2000,
    "maxDelayMs": 60000
  }
}

      Message Delivery

      SettingTypeDefaultDescription
      steeringModestring"one-at-a-time"How steering messages are sent
      followUpModestring"one-at-a-time"How follow-up messages are sent
      transportstring"sse"Preferred transport: "sse", "websocket", or "auto"

      Terminal & Images

      SettingTypeDefaultDescription
      terminal.showImagesbooleantrueShow images in terminal
      terminal.clearOnShrinkbooleanfalseClear empty rows on shrink
      images.autoResizebooleantrueResize images to 2000x2000 max
      images.blockImagesbooleanfalseBlock all images to LLM

      Shell

      SettingTypeDefaultDescription
      shellPathstring-Custom shell path
      shellCommandPrefixstring-Prefix for every bash command

      Model Cycling

      {
  "enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
}

      Resources

      SettingTypeDefaultDescription
      packagesarray[]npm/git packages to load
      extensionsstring[][]Extension paths
      skillsstring[][]Skill paths
      promptsstring[][]Prompt template paths
      themesstring[][]Theme paths
      enableSkillCommandsbooleantrueRegister skills as commands

      Example

      {
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3
  },
  "enabledModels": ["claude-*", "gpt-4o"],
  "packages": ["pi-skills"]
}

      Project Overrides

      Project settings override global. Nested objects are merged:

      // ~/.pi/agent/settings.json (global)
{ "theme": "dark", "compaction": { "enabled": true, "reserveTokens": 16384 } }

// .pi/settings.json (project)
{ "compaction": { "reserveTokens": 8192 } }

// Result
{ "theme": "dark", "compaction": { "enabled": true, "reserveTokens": 8192 } }