Configurações

Pi usa arquivos de configurações JSON com configurações de projeto substituindo configurações globais.

Edite diretamente ou use /settings para opções comuns.

Na inicialização interativa, pi pergunta antes de confiar em uma pasta de projeto que contém configurações locais do projeto, recursos ou projeto .agents/skills e não tem decisão salva para a pasta ou pasta pai em ~/.pi/agent/trust.json. Confiar em um projeto permite que pi carregue recursos .pi/settings.json e .pi, instale pacotes de projeto ausentes e execute extensões de projeto.

Os modos não interativos (-p, --mode json e --mode rpc) não mostram um prompt de confiança. Sem uma decisão de confiança salva aplicável, eles usam defaultProjectTrust das configurações globais: ask (padrão) e never ignoram esses recursos do projeto, enquanto always confia neles. Passe --approve/-a ou --no-approve/-na para substituir a confiança do projeto em uma execução.

Se nenhuma extensão ou decisão salva se aplicar, defaultProjectTrust controla o comportamento de fallback. Defina-o como "ask", "always" ou "never" em ~/.pi/agent/settings.json ou altere-o com /settings.

Os comandos pi config e pacote usam o mesmo fluxo de confiança do projeto, exceto que pi update nunca solicita. Passe --approve para confiar nas configurações locais do projeto para um comando ou --no-approve para ignorá-las.

Use /trust no modo interativo para salvar uma decisão de confiança do projeto para sessões futuras, incluindo confiança para a pasta pai imediata. Ele escreve apenas ~/.pi/agent/trust.json; a sessão atual não é recarregada, então reinicie o pi para que as alterações tenham efeito.

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

Para VS Code, inclua --wait para que pi seja retomado após a saída do editor:

{
  "externalEditor": "code --wait"
}

enableInstallTelemetry controla apenas o ping anônimo de instalação/atualização para https://pi.dev/api/report-install. A desativação da telemetria não desativa as verificações de atualização; Pi ainda pode buscar https://pi.dev/api/latest-version para procurar a versão mais recente.

Defina PI_SKIP_VERSION_CHECK=1 para desativar a verificação de atualização de versão Pi. Use --offline ou PI_OFFLINE=1 para desabilitar todas as operações de inicialização da rede descritas aqui, incluindo verificações de atualização, verificações de atualização de pacotes e telemetria de instalação/atualização.

{
  "httpProxy": "http://127.0.0.1:7890"
}

{
  "warnings": {
    "anthropicExtraUsage": false
  }
}

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

Quando um provedor solicita um atraso de repetição maior que retry.provider.maxRetryDelayMs, a solicitação falha imediatamente com um erro informativo em vez de esperar silenciosamente. Defina como 0 para desativar o limite.

Mantenha retry.provider.maxRetries em 0, a menos que novas tentativas no nível do provedor sejam explicitamente necessárias. Definir acima de 0 pode fazer com que SDK/novas tentativas do provedor lide com erros de limite fora de uso antes que Pi os veja, o que pode bloquear o agente até que a cota do provedor seja redefinida em algumas circunstâncias.

{
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 2000,
    "provider": {
      "timeoutMs": 3600000,
      "maxRetries": 0,
      "maxRetryDelayMs": 60000
    }
  }
}

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

npmCommand é usado para todas as operações do gerenciador de pacotes npm, incluindo instalações, desinstalações e instalações de dependências dentro de pacotes git. Pacotes npm com escopo de usuário são instalados em ~/.pi/agent/npm/; pacotes npm com escopo de projeto são instalados em .pi/npm/. Use entradas no estilo argv exatamente como o processo deve ser iniciado. Quando npmCommand é configurado, as instalações de dependência do pacote git usam install simples para evitar sinalizadores específicos de npm em wrappers ou gerenciadores de pacotes alternativos.

{ "sessionDir": ".pi/sessions" }

Quando várias fontes especificam um diretório de sessão, a precedência é --session-dir, PI_CODING_AGENT_SESSION_DIR e, em seguida, sessionDir em settings.json.

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

Essas configurações definem de onde carregar extensões, habilidades, prompts e temas.

Caminhos em ~/.pi/agent/settings.json são resolvidos em relação a ~/.pi/agent. Caminhos em .pi/settings.json são resolvidos em relação a .pi. Caminhos absolutos e ~ são suportados.

Matrizes suportam padrões globais e exclusões. Use !pattern para excluir. Use +path para forçar a inclusão de um caminho exato e -path para forçar a exclusão de um caminho exato.

O formulário String carrega todos os recursos de um pacote:

{
  "packages": ["pi-skills", "@org/my-extension"]
}

O formulário do objeto filtra quais recursos carregar:

{
  "packages": [
    {
      "source": "pi-skills",
      "skills": ["brave-search", "transcribe"],
      "extensions": []
    }
  ]
}

Veja packages.md para detalhes de gerenciamento de pacotes.

{
  "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"],
  "warnings": {
    "anthropicExtraUsage": true
  },
  "packages": ["pi-skills"]
}

As configurações do projeto (.pi/settings.json) substituem as configurações globais. Objetos aninhados são mesclados:

// ~/.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 }
}