Usando Pi

Esta página coleta detalhes de uso diário que não cabem na página de início rápido.

A interface possui quatro áreas principais:

• Cabeçalho de inicialização - atalhos, context files, prompt templates carregados, habilidades e extensões
• Mensagens: mensagens do usuário, respostas do assistente, chamadas de ferramentas, resultados de ferramentas, notificações, erros e UI de extensão
• Editor - onde você digita; a cor da borda indica o nível de pensamento atual
• Rodapé - diretório de trabalho, nome da sessão, uso de token/cache, custo, uso de contexto e modelo atual. Os totais incluem respostas do assistente, uso relatado por ferramentas e geração de resumo.

O editor pode ser substituído temporariamente pela UI integrada, como /settings ou pela UI de extensão personalizada.

Recurso	Como
Referência de arquivo	Digite @ para pesquisar arquivos de projeto de forma difusa
Conclusão do caminho	Pressione Tab para completar caminhos
Entrada multilinha	Shift+Enter ou Ctrl+Enter no Terminal do Windows
Copiar resposta	Ctrl+X copia a última mensagem do assistente; em /tree, copia a mensagem selecionada
Imagens	Cole com Ctrl+V, Alt+V no Windows ou arraste para o terminal
Comando shell	!command executa e envia saída para o modelo
Comando de shell oculto	!!command é executado sem enviar saída para o modelo
Editor externo	Ctrl+G abre externalEditor, $VISUAL, $EDITOR, Bloco de notas no Windows ou nano em outro lugar

Consulte Keybindings para todos os atalhos e personalizações.

Digite / no editor para abrir a conclusão do comando. Extensions pode registrar comandos personalizados, habilidades estão disponíveis como /skill:name e prompt templates expandem via /templatename.

Comando	Descrição
/login, /logout	Gerenciar credenciais de chave OAuth ou API
/llama	Baixe, carregue e descarregue modelos de roteador llama.cpp
/model	Trocar modelos
/scoped-models	Ativar/desativar modelos para ciclismo Ctrl+P
/settings	Nível de pensamento, tema, entrega de mensagens, transporte
/resume	Pick de sessões anteriores
/new	Iniciar uma nova sessão
/name <name>	Definir nome de exibição da sessão
/session	Mostrar arquivo de sessão, ID, mensagens, tokens e custo
/tree	Vá para qualquer ponto da sessão e continue a partir daí
/trust	Salve a decisão de confiança do projeto para sessões futuras
/fork	Crie uma nova sessão a partir de uma mensagem de usuário anterior
/clone	Duplicar o branch ativo atual em uma nova sessão
/compact [prompt]	Contexto compacto manualmente, opcionalmente com instruções personalizadas
/copy	Copie a última mensagem do assistente para a área de transferência
/export [file]	Exportar sessão para HTML ou JSONL
/import <file>	Importe e retome uma sessão de um arquivo JSONL
/share	Carregar como essência GitHub privada com link HTML compartilhável
/reload	Recarregue atalhos de teclado, extensões, habilidades, prompts, temas e context files
/hotkeys	Mostrar todos os atalhos de teclado
/changelog	Exibir histórico de versões
/quit	Sair do pi

Você pode enviar mensagens enquanto o agente ainda está trabalhando:

• Enter coloca uma mensagem de direção na fila, entregue após o turno do assistente atual terminar de executar suas chamadas de ferramenta.
• Alt+Enter coloca uma mensagem de acompanhamento na fila, entregue depois que o agente termina todo o trabalho.
• Escape aborta e restaura mensagens enfileiradas no editor.
• Alt+Up recupera mensagens na fila de volta para o editor.

No Terminal Windows, Alt+Enter fica em tela cheia por padrão. Remapeie-o conforme descrito em Terminal setup se desejar que pi receba o atalho.

Configure a entrega em Settings com steeringMode e followUpMode.

As sessões são salvas automaticamente em ~/.pi/agent/sessions/, organizadas por diretório de trabalho.

pi -c                  # Continue most recent session
pi -r                  # Browse and select a session
pi --no-session        # Ephemeral mode; do not save
pi --name "my task"    # Set session display name at startup
pi --session <path|id> # Use a specific session file or session ID
pi --fork <path|id>    # Fork a session into a new session file

Comandos de sessão úteis:

• /session mostra o arquivo e ID da sessão atual.
• /tree navega no arquivo session tree e pode resumir ramificações abandonadas.
• /fork cria uma nova sessão a partir de uma mensagem anterior do usuário.
• /clone duplica o branch ativo atual em um novo arquivo de sessão.
• /compact resume mensagens mais antigas para liberar contexto.

Consulte Sessions e Compaction para obter detalhes.

Pi carrega AGENTS.md ou CLAUDE.md na inicialização de:

• ~/.pi/agent/AGENTS.md para instruções globais
• diretórios pai, subindo do diretório de trabalho atual
• o diretório atual

Se um diretório contém AGENTS.override.md, Pi carrega-o em vez de AGENTS.md ou CLAUDE.md desse diretório. Arquivos de contexto de outros diretórios ainda estão em camadas normalmente.

Use context files para convenções, comandos, regras de segurança e preferências do projeto. Desative o carregamento com --no-context-files ou -nc.

Substitua o prompt padrão do sistema por:

• .pi/SYSTEM.md para um projeto
• ~/.pi/agent/SYSTEM.md globalmente

Anexe ao prompt padrão sem substituí-lo por APPEND_SYSTEM.md em qualquer local.

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.

Antes da decisão de confiança, pi carrega apenas context files, extensões de usuário/globais e CLI -e extensões para que possam lidar com o evento project_trust. Extensões locais do projeto, extensões gerenciadas por pacote de projeto e configurações do projeto são carregadas somente depois que o projeto é confiável. Essa divisão também se aplica ao alternar para uma sessão de um cwd diferente cuja confiança não foi resolvida no processo atual.

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.

Use /export [file] para escrever uma sessão em HTML.

Use /share para fazer upload de uma essência GitHub privada com um link HTML compartilhável.

Se você usa pi para trabalho de código aberto e deseja publicar sessões para pesquisa de modelo, prompt, ferramenta e avaliação, consulte badlogic/pi-share-hf. Publica sessões em conjuntos de dados Hugging Face.

pi [options] [@files...] [messages...]

pi install <source> [-l]     # Install package, -l for project-local
pi remove <source> [-l]      # Remove package
pi uninstall <source> [-l]   # Alias for remove
pi update [source|self|pi]   # Update pi only, or one package source
pi update --all              # Update pi and packages; reconcile pinned git refs
pi update --extensions       # Update packages only; reconcile pinned git refs
pi update --models           # Refresh model catalogs only
pi update --self             # Update pi only
pi update --extension <src>  # Update one package
pi list                      # List installed packages
pi config                    # Enable/disable package resources

Esses comandos gerenciam pacotes pi e pi update podem atualizar a instalação do pi CLI. Para desinstalar o próprio pi, consulte Quickstart. Os comandos pi config e pacote de projeto aceitam --approve/--no-approve para confiar ou ignorar as configurações locais do projeto para um comando. pi update nunca solicita confiança no projeto.

Veja Pi Packages para fontes de pacotes e notas de segurança.

Bandeira	Descrição
padrão	Modo interativo
-p, --print	Imprimir resposta e sair
--mode json	Produza todos os eventos como JSON linhas; veja JSON mode
--mode rpc	Modo RPC acima de stdin/stdout; veja RPC mode
--export <in> [out]	Exportar uma sessão para HTML

No modo de impressão, pi também lê canalizado stdin e o mescla no prompt inicial:

cat README.md | pi -p "Summarize this text"

Opção	Descrição
--provider <name>	Provedor, como anthropic, openai ou google
--model <pattern>	Padrão ou ID do modelo; suporta provider/id e opcional :<thinking>
--api-key <key>	API key, substituindo variáveis ​​de ambiente
--thinking <level>	off, minimal, low, medium, high, xhigh, max
--models <patterns>	Padrões separados por vírgula para ciclismo Ctrl+P
--list-models [search]	Listar modelos disponíveis

Opção	Descrição
-c, --continue	Continuar a sessão mais recente
-r, --resume	Navegue e selecione uma sessão
`--sessão <caminho\	id>`
`--fork <caminho\	id>`
--session-dir <dir>	Diretório de armazenamento de sessão personalizado
--no-session	Modo efêmero; não salve
--name <name>, -n <name>	Definir o nome de exibição da sessão na inicialização

Opção	Descrição
--tools <list>, -t <list>	Lista de permissões específicas de ferramentas integradas, de extensão e personalizadas
--exclude-tools <list>, -xt <list>	Desative ferramentas específicas integradas, de extensão e personalizadas
--no-builtin-tools, -nbt	Desative as ferramentas integradas, mas mantenha as ferramentas de extensão/personalizadas ativadas
--no-tools, -nt	Desative todas as ferramentas

Ferramentas integradas: read, bash, edit, write, grep, find, ls.

Opção	Descrição
-e, --extension <source>	Carregue uma extensão do caminho, npm ou git; repetível
--no-extensions	Desativar descoberta de extensão
--skill <path>	Carregue uma habilidade; repetível
--no-skills	Desativar descoberta de habilidades
--prompt-template <path>	Carregue um modelo de prompt; repetível
--no-prompt-templates	Desativar descoberta de modelo de prompt
--theme <path>	Carregue um tema; repetível
--no-themes	Desativar descoberta de tema
--no-context-files, -nc	Desativar descoberta AGENTS.md e CLAUDE.md

Combine --no-* com sinalizadores explícitos para carregar exatamente o que você precisa, ignorando as configurações. Exemplo:

pi --no-extensions -e ./my-extension.ts

Opção	Descrição
--system-prompt <text>	Substitua o prompt padrão; context files e habilidades ainda estão anexadas
--append-system-prompt <text>	Anexar ao prompt do sistema
--tui-mode <mode>	Modo TUI: regular (padrão) ou experimental fullscreen
--verbose	Forçar inicialização detalhada
-a, --approve	Confie nos arquivos locais do projeto para esta execução
-na, --no-approve	Ignore os arquivos locais do projeto para esta execução
-h, --help	Mostrar ajuda
-v, --version	Mostrar versão

No modo fullscreen, a transcrição rola dentro da janela de visualização do terminal enquanto as mensagens na fila, o status de trabalho, os widgets de extensão, o editor e o rodapé permanecem fixos na parte inferior. A entrada do mouse/trackpad rola a região sob o ponteiro; as ações da janela de visualização do teclado sempre permanecem disponíveis. As imagens embutidas funcionam em terminais que suportam o protocolo gráfico Kitty, incluindo Kitty e Ghostty. No iTerm2, eles são renderizados como espaços reservados para texto porque seu protocolo de imagem embutido não pode excluir ou cortar posicionamentos durante a rolagem do aplicativo. No modo regular, pi usa a tela principal e a rolagem do terminal, e as imagens embutidas do iTerm2 continuam a renderizar normalmente.

Defina o modo TUI em /settings para alternar entre regular e fullscreen imediatamente e escolha o padrão para sessões futuras. Saída de saída em tela cheia controla se sair da tela cheia imprime a transcrição final ou restaura a tela anterior e imprime apenas a dica de retomada da sessão.

Prefixe os arquivos com @ para incluí-los na mensagem:

pi @prompt.md "Answer this"
pi -p @screenshot.png "What's in this image?"
pi @code.ts @test.ts "Review these files"

# Interactive with initial prompt
pi "List all .ts files in src/"

# Non-interactive
pi -p "Summarize this codebase"

# Non-interactive with piped stdin
cat README.md | pi -p "Summarize this text"

# Named one-shot session
pi --name "release audit" -p "Audit this repository"

# Different model
pi --provider openai --model gpt-4o "Help me refactor"

# Model with provider prefix
pi --model openai/gpt-4o "Help me refactor"

# Model with thinking level shorthand
pi --model sonnet:high "Solve this complex problem"

# Limit model cycling
pi --models "claude-*,gpt-4o"

# Read-only mode
pi --tools read,grep,find,ls -p "Review the code"

# Disable one extension or built-in tool while keeping the rest available
pi --exclude-tools ask_question

Pi mantém o núcleo pequeno e empurra o comportamento específico do fluxo de trabalho para extensões, habilidades, prompt templates e pacotes.

Intencionalmente não inclui MCP integrado, subagentes, pop-ups de permissão, modo de plano, tarefas ou bash em segundo plano. Você pode criar ou instalar esses fluxos de trabalho como extensões ou pacotes, ou usar ferramentas externas, como contêineres e tmux.

Para o raciocínio completo, leia o blog post.