Pi Familiar Tools
adityavkk/pi-familiar-tools
Traduz ferramentas Pi para nomes nativos de IA mantendo segurança
Ver no GitHubAgent que mapeia as ferramentas canônicas do Pi para nomes nativos de Claude, Codex e Gemini, mantendo os limites de capabilidade originais. Melhora o comportamento do modelo ao usar nomenclatura familiar ao seu treinamento, sem ampliar indevidamente as permissões.
Instalação
npx convez-ai adityavkk/pi-familiar-tools1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Agentes de código que precisam usar Claude, GPT ou Gemini com interfaces familiares
- Projetos Pi que querem melhorar o desempenho de modelos com nomes de ferramentas conhecidos
- Cenários que exigem mapeamento consistente de capabilities entre múltiplos provedores
Veredito

Solução técnica precisa para o problema real de nomenclatura de ferramentas entre provedores. Mantém rigorosamente os limites de segurança originais enquanto melhora a compreensão do modelo — recomendado para quem usa o ecossistema Pi com múltiplos LLMs.
README
A tradução para o português deste README ainda está na fila.
pi-familiar-tools
Provider-familiar tool surfaces for Pi.
Pi has its own canonical tools: read, bash, edit, write, grep,
find, and ls. Models often behave better when the tool names and schemas
look like the environment they were trained to use. pi-familiar-tools keeps
Pi's capability boundary and translates only the active canonical tools into
Claude Code, Codex, or Gemini-style tool names.
Install
Install from GitHub:
pi install git:github.com/adityavkk/pi-familiar-tools
Try it for one session without installing:
pi -e git:github.com/adityavkk/pi-familiar-tools
Load it from a local checkout while developing:
pi -e /path/to/pi-familiar-tools
Pi reads the package manifest in package.json:
{
"keywords": ["pi-package"],
"pi": {
"extensions": ["./extensions/provider-tool-profiles/index.ts"]
}
}
What It Does
pi-familiar-tools detects the active model family and maps Pi's current tool
capabilities to provider-native names:
| Pi capability | Claude tools | Codex/GPT tools | Gemini tools |
|---|---|---|---|
read | Read | read | read_file, read_many_files |
bash | Bash | shell_command | run_shell_command |
edit | Edit, MultiEdit | apply_patch | replace |
write | Write | apply_patch | write_file |
grep | Grep | shell_command | grep_search, search_file_content |
find | Glob | shell_command | glob |
ls | LS | shell_command | list_directory |
The mapping is capability-aware. A read-only role does not get edit tools just
because the model is Claude or Gemini. A Codex role does not get apply_patch
unless Pi already exposed edit or write.
Codex has one deliberate limitation: this package keeps Pi's canonical read
tool for read-only Codex sessions. It does not grant shell_command just to
emulate reading files. Dedicated Codex read/list wrappers can be added later
without widening today's read-only boundary.
Why This Exists
The useful part of provider-native tools is the model contract:
- Claude sees
Bash,Read,Edit,MultiEdit,Glob,Grep, andLS. - Codex sees
shell_command,apply_patch,update_plan, andview_imagewhen those capabilities are appropriate. - Gemini sees
run_shell_command,read_file,read_many_files,list_directory,glob,grep_search,search_file_content,replace, andwrite_file.
The risky part is accidentally broadening what the agent can do. This package keeps the provider naming but preserves Pi's original capability set.
Configuration
Global config:
~/.pi/agent/provider-tool-profiles.json
Project config:
.pi/provider-tool-profiles.json
Project config overrides global config.
{
"enabled": true,
"preserveExtensionTools": true,
"fallbackTools": ["read", "bash", "edit", "write"],
"profiles": {
"claude": true,
"codex": true,
"gemini": true
}
}
Environment overrides:
PI_PROVIDER_TOOL_PROFILES=0
PI_PROVIDER_TOOL_PROFILE=claude
PI_PROVIDER_TOOL_PROFILE=codex
PI_PROVIDER_TOOL_PROFILE=gemini
PI_PROVIDER_TOOL_PROFILE=off
Safety Boundaries
Always:
- The extension registers all provider wrappers once, then activates only the wrappers mapped from active Pi capabilities.
- The extension preserves unrelated extension tools when
preserveExtensionToolsis enabled. - The extension restores the previous Pi core tools when no provider profile applies.
Never:
- It does not auto-activate new Letta tools just because their schemas are vendored.
- It does not grant mutation or shell capability only because a model family changed.
- It does not implement Codex
exec_commandorwrite_stdin; those require explicit session, stdin, polling, cancellation, and PTY semantics.
Development
Install dependencies:
bun install
Run the package tests:
bun test extensions/provider-tool-profiles/*.test.ts extensions/provider-tool-profiles/tools/*.test.ts
Run compatibility checks:
bun extensions/provider-tool-profiles/scripts/check-pi-compat.ts --mode locked
bun extensions/provider-tool-profiles/scripts/check-letta-drift.ts --ref main
Run the focused strict type check for the pure activation core:
npm run typecheck:activation
The extension source lives in extensions/provider-tool-profiles/. The
top-level package intentionally does not include GitHub workflows; consumers
can install it directly from GitHub or npm once published.
Registry Status
This repository is a Pi package: it has the pi-package keyword and a
pi.extensions manifest. It is installable from GitHub today:
pi install git:github.com/adityavkk/pi-familiar-tools
The public Pi package gallery is npm-oriented. Publishing pi-familiar-tools
to npm will make the package eligible for the gallery entry at
https://pi.dev/packages/pi-familiar-tools.
License
MIT