O ecossistema Salesforce acaba de ganhar uma ferramenta poderosa e open source: o sf-pi. Lançado oficialmente em abril de 2026, o sf-pi é um bundle de extensões opinativas para o pi coding agent, desenvolvido para devs que trabalham com código Salesforce e Salesforce-adjacente.
Neste tutorial avançado, vamos além da instalação básica. Você vai aprender a configurar cada extensão, explorar workflows reais de desenvolvimento, e extrair o máximo do que o sf-pi oferece, desde diagnósticos Apex em tempo real até diagramas determinísticos com tldraw.
O Que é o sf-pi Exatamente?
O sf-pi é mantido por Jag Valaiyapathy (@Jaganpro), Senior Forward Deployed Engineer na Salesforce e Certified Technical Architect. Ele se baseia no runtime do pi coding agent de Mario Zechner e incorpora o melhor do ecossistema de extensões da comunidade pi.
Na prática, o sf-pi transforma o terminal em um ambiente de desenvolvimento Salesforce completo:
- SF Apex — Diagnósticos, trace/log/watch, Anonymous Apex e testes direcionados
- SF LWC — Scan de projeto, inspeção de componentes, diagnósticos focados e Jest tests
- SF SOQL — Schema search, relationship discovery, query drafting, validação e execução
- SF Agent Script — Compile-on-save diagnostics, eval/regression testing via Salesforce Evaluation API
- SF Docs — Documentação Salesforce lookup com resultados citados
- SF tldraw — Diagramas determinísticos renderizados via Canvas API offline
- SF Data 360 — Ferramentas completas para Data Cloud: discover, connect, prepare, harmonize
- SF Guardrail — Políticas de proteção de arquivos e gating de comandos perigosos
- SF LLM Gateway — Provider de LLM com discovery de modelos via gateway corporativo
- SF DevBar — Status bar com contexto de org, modelo, git e progresso de context window
Pré-requisitos
Antes de começar, garanta que você tem:
- Node.js >= 22.19 — obrigatório para pi e sf-pi
- Terminal com suporte a Nerd Fonts — para os glyphs do DevBar e splash screen
- Acesso a um Salesforce org — para as integrações de diagnóstico e SOQL
- sf CLI instalado — para workflows que interagem com metadata
Passo 1: Instalando o Runtime
Se você ainda não tem o pi coding agent instalado:
# Instale o Node.js (macOS)
brew install node
# Ou use nvm para version management
nvm install 22
nvm use 22
nvm alias default 22
# Verifique
node --version # v22.19.0 ou superior
npm --versionEm seguida, instale o pi coding agent globalmente:
npm install -g --ignore-scripts @earendil-works/pi-coding-agentPasso 2: Instalando o sf-pi
A instalação é feita diretamente via pi. Você pode instalar globalmente (visível em todas as sessões) ou por projeto:
# Instalação global (recomendado para começar)
pi install git:github.com/salesforce/sf-pi
# Ou instalação por projeto (ativada apenas naquele diretório)
pi install -l git:github.com/salesforce/sf-piApós instalar, reinicie o pi ou execute /reload. Todas as extensões são habilitadas por padrão.
Passo 3: Configurando o Terminal (One-Time)
O splash screen e a status bar usam glyphs do Nerd Font. Se você vê ? ou fallbacks ASCII:
/sf-setup-fontsConfigure a fonte do seu terminal para MesloLGM Nerd Font Mono e reabra o terminal.
Passo 4: Instalando o Bundle de Extensões da Comunidade
O sf-pi espera algumas extensões da comunidade pi para a melhor experiência:
/sf-pi recommended install bundle:defaultIsso instala 8 extensões MIT-licensed de uma vez:
- pi-skills — Biblioteca baseline de skills (Google Workspace, browser automation, YouTube)
- pi-web-access — Web search, URL fetching, GitHub repo cloning, PDF extraction
- pi-aliases — Helpers de muscle-memory (
/clear → /new,/exit → /quit) - pi-interview — Ferramenta structured interview para requirement gathering
- glimpseui — Micro-UI cross-platform para charts e HTML previews
- pi-tool-display — Renderização compacta de tool calls e diffs
- pi-subagents — Delegação para subagents paralelos e assíncronos
- pi-herdr — Orchestration de workspaces, tabs e panes
Gerenciando Extensões
O comando /sf-pi é seu centro de controle. Aqui estão os comandos essenciais:
# Listar todas as extensões com status
/sf-pi list
# Habilitar/desabilitar extensões específicas
/sf-pi enable sf-apex
/sf-pi disable sf-llm-gateway-internal
# Habilitar/desabilitar tudo
/sf-pi enable-all
/sf-pi disable-all
# Ver o perfil de display efetivo
/sf-pi display compact # resumos concisos
/sf-pi display balanced # padrão com previews úteis
/sf-pi display verbose # previews ricos e detalhados
# Diagnosticar problemas
/sf-pi doctor
/sf-pi doctor fix startup
/sf-pi doctor fix skillsVocê pode adicionar global ou project para direcionar o escopo:
/sf-pi disable sf-ohana-spinner project
/sf-pi enable-all globalWorkflows Avançados: SF Apex
A extensão SF Apex é provavelmente a mais poderosa do bundle. Ela oferece workflows completos de ciclo de vida Apex:
Diagnósticos em Tempo Real
Com o SF LSP habilitado, erros e warnings aparecem automaticamente ao salvar. O DevBar mostra a saúde do LSP em tempo real.
Anonymous Apex
Execute trechos de Apex diretamente do terminal:
// O sf-pi conecta ao seu org e executa
List<Account> accs = [SELECT Id, Name FROM Account LIMIT 5];
System.debug('Accounts: ' + accs);Testes Direcionados
Rode testes Apex específicos sem precisar abrir o Developer Console. O sf-pi executa via API e formata os resultados no terminal.
Workflows Avançados: SF SOQL
A extensão SF SOQL vai muito além de um simples query runner:
- Schema Search — Encontre objetos e campos por nome ou tipo
- Relationship Discovery — Mapeie relacionamentos entre objetos automaticamente
- Query Drafting — O agente sugere queries baseado no seu intent
- Query Plans — Analise custo de queries antes de executar
- Execução Limitada — Queries com bounds de segurança para evitar acidentes
- Export — Exporte resultados para CSV ou JSON
Workflows Avançados: SF LWC
Para desenvolvedores LWC, a extensão oferece:
- Project Scan — Mapeia todos os componentes LWC do projeto
- Component Inspection — Analisa estrutura, imports, e dependências
- Diagnostics — Erros de compilação e warnings em tempo real
- Jest Tests — Execute testes Jest para componentes específicos
- Artifacts — Gere boilerplate para novos componentes
SF Agent Script: O Diferencial
O Agent Script é uma das features mais inovadoras. Ele permite criar e testar scripts declarativos para Agentforce:
# Exemplo: .agent file com lifecycle completo
name: lead-qualification
version: 1.0
steps:
- id: qualify
action: analyze
input: "{{lead.email}}"
output: qualified_scoreO sf-pi oferece:
- Compile-on-save diagnostics — Erros aparecem instantaneamente ao salvar
- LLM-callable compile tool — O agente pode compilar e validar scripts
- Multi-turn eval — Teste regressivo contra a Salesforce Evaluation API
SF tldraw: Diagramas Determinísticos
Uma das extensões mais recentes e impressionantes. O SF tldraw gera diagramas Salesforce diretamente no terminal usando a Canvas API offline do tldraw:
- Data Model diagrams com entidades e relacionamentos
- Architecture diagrams com layouts automáticos
- Sequence diagrams com labels de cross-lane
- Suporte a SLDS icons inferidos
- Zero canvas lints e zero marker overlaps
Validado contra todas as 230 páginas únicas do Salesforce Data Model Gallery: 4.916 entidades e 7.559 relacionamentos.
SF LLM Gateway: Conectando ao Seu Provider
Se sua organização usa um LLM gateway corporativo:
# Setup via wizard interativo
/sf-llm-gateway
# Ou configure manualmente
/sf-llm-gateway setup
/sf-llm-gateway on
/sf-llm-gateway set-default
# Diagnósticos
/sf-llm-gateway doctor
/sf-llm-gateway models
/sf-llm-gateway tokensO gateway suporta importação de configurações do Claude Code:
/sf-llm-gateway import-claudeSF Guardrail: Segurança em Primeiro Lugar
O sf-pi leva segurança a sério. O SF Guardrail oferece:
- File Protection Policies — Impede edição acidental de arquivos críticos
- Dangerous Command Gating — Confirma antes de executar comandos destrutivos
- Org-aware Confirmation — Detecta qual org está ativa e pede confirmação para mutações
- High-value Mutation Mediation — Mediação nativa para operações de alto impacto
Usando Skills de Outros Harnesses
O sf-pi suporta interoperabilidade com skills de Claude Code, Codex e Cursor:
# Configuração manual em ~/.pi/agent/settings.json
{
"skills": ["~/.claude/skills", "~/.codex/skills"]
}
# Ou use o comando assistido
/sf-pi skillsAs skills funcionam em paralelo — wirear um diretório do Claude Code não copia, move ou altera os arquivos. O pi lê in-place e o Claude Code continua usando normalmente.
Telemetria e Privacidade
O sf-pi não coleta telemetria ativa. Nenhuma extensão bundled envia prompts, respostas, tool calls, caminhos de arquivo, identificadores de org, ou uso de comandos.
Por padrão, o sf-pi desabilita até o ping anônimo de instalação do pi runtime:
/sf-pi telemetry status # mostra o estado atual
/sf-pi telemetry on # opt-in explícito
/sf-pi telemetry off # opt-out (padrão)SF Data Explorer: TUI Interativo
O Data Explorer é um TUI read-only para explorar dados diretamente no terminal:
- Execute SOQL e SOSL de forma interativa
- Data 360 SQL para Data Cloud
- Navegação por resultados com paginação
- Export para múltiplos formatos
Dicas de Produtividade
1. Use Display Profiles
Mude entre compact, balanced e verbose dependendo da tarefa. Use compact para foco e verbose para debugging.
2. Combine SF Skills com pi-interview
Para scaffolding de novos features, use o pi-interview para requirement gathering e depois o sf-agentscript para gerar os scripts.
3. Aproveite o SF Brain
O SF Brain injeta regras operacionais por sessão: describe-before-query rules, API picker, anonymous Apex verification loop, e CLI power moves.
4. Pipeline de CI/CD Local
Combine sf-pi com o sf-code-analyzer para scans automáticos antes de commits:
/sf-code-analyzer scan
/sf-code-analyzer report5. Session Storage Customizado
Para ambientes de equipe, redirecione sessions para um diretório compartilhado:
export PI_CODING_AGENT_SESSION_DIR="$HOME/.pi-sessions"Compatibilidade e Plataformas
O sf-pi suporta:
- macOS — Suporte completo (recomendado)
- Linux — Suporte completo
- WSL — Recomendado para Windows
- Windows nativo — Funciona em x64 e ARM64 com sf CLI instalado
O range de Pi compatível: >=0.81.1 <1.0.0, com Pi 0.82.0 recomendado.
Contribuindo para o Projeto
O sf-pi é open source (Apache 2.0) e aceita contribuições. Para adicionar uma nova extensão:
# Clone o repositório
git clone https://github.com/salesforce/sf-pi.git
cd sf-pi
npm install
# Scaffold uma nova extensão
npm run scaffold -- --id sf-minha-ext --category ui --name "Minha Extensão"
# Valide
npm run validateVeja o CONTRIBUTING.md para o workflow completo de contribuição.
Conclusão
O sf-pi representa um salto na produtividade de desenvolvedores Salesforce. Ao trazer diagnósticos em tempo real, execução de queries, testes automatizados, e diagramas determinísticos para o terminal, ele elimina a necessidade de alternar entre Developer Console, VS Code, e ferramentas externas.
Com 22 extensões bundled e 8 extensões recomendadas da comunidade, o sf-pi é o toolkit mais completo disponível para desenvolvimento Salesforce com coding agents. E por ser open source, ele só tende a melhorar com as contribuições da comunidade.
Links úteis: