Pi, Minimalny Narzędzie do Kodowania: Rozszerzenia, Umiejętności, Sesje i Bezpieczeństwo
Dlaczego mały zestaw do kodowania z czterema narzędziami i krótkim komunikatem systemowym może przewyższyć agenty pełne funkcji: instalacja, modele, drzewa sesji, rozszerzenia, umiejętności i środowisko izolowane.
Agenty do kodowania w terminalu, takie jak Claude Code, Cursor i OpenCode, stały się normalną częścią codziennych zajęć wielu programistów, szczególnie od kwietnia, gdy OpenAI udostępniło open source narzędzie Codex CLI. Pi, celowo proste narzędzie do programowania, powstało w odpowiedzi na skargi dotyczące wszystkich tych rozwiązań: narzędzie to ciągle się zmienia.
Skargi te nie dotyczą błędów. Chodzi o to, że samo narzędzie ulega zmianom, a wraz z nim zmienia się również zachowanie modelu. Inżynierowie chcą narzędzi, na których mogą polegać. Same modele językowe są niestabilne, ale przynajmniej elementy otoczenia, w tym narzędzia, prompty systemowe oraz wszystko, co jest do nich wprowadzane, można uczynić deterministycznymi.
Claude Code i Codex wprowadzają wiele elementów do kontekstu bez pokazywania ich w interfejsie, a te ukryte dodatki w subtelny sposób zakłócają przepływ pracy. Wersje aktualizacji wychodzą raz dziennie, a nawet kilka razy dziennie. Przepływ pracy, który funkcjonuje perfekcyjnie o dziewiątej rano, może się załamać o dziesiątej i zachowywać się zupełnie inaczej o trzeciej, przy tym model pozostaje niezmieniony, a zmienia się tylko narzędzie do jego obsługi. Nowe funkcje pojawiają się niemal co miesiąc – wśród nich MCP, subagenty, tryb planowania oraz wykonywanie w tle – i staje się coraz trudniej śledzić to, co dzieje się w tle.
Odpowiedzią Pi jest zasada projektowa: jeśli coś nie jest potrzebne, nie jest tworzone. Istniejące narzędzia wprowadzają kontekst w sposób niewidoczny, więc użytkownicy nie mogą zobaczyć, co się dzieje. To była motywacja.
Co inspirowało minimalizm
Zanim stworzyciel Pi, Mario Zechner, rozpoczął jego rozwój, sprawdził listę liderów Terminal Bench, na której wyróżniał się narzędzie o nazwie Terminus. Daje ono modelowi dokładnie jeden narzędzie – interfejs do sesji tmux. LLM wysyła pojedyncze naciśnięcia klawiszy i odczytuje wynik w formacie ANSI z tmux, aby ukończyć zadanie. Dzięki temu niemal zawsze plasuje się w czołowej trójce, a często zajmuje pierwsze miejsce.
To wskazuje na przydatną intuicję: modele są obecnie intensywnie szkolenie za pomocą uczenia się wzmacniającego, więc już wiedzą, czym jest narzędzie do programowania, i nie potrzebują dodatkowych elementów. Pi realizuje tę ideę jako minimalne, a jednocześnie rozszerzalne narzędzie.
Co czyni Pi wyjątkowym
Cechą wyróżniającą Pi jest to, co pomija – funkcje, które inne narzędzia kodujące traktują jako standardowe. Weźmy MCP: po połączeniu z serwerem każda definicja narzędzia wypełnia kontekst na początku każdej sesji. Narzędzia CLI mają pliki README, które są czytane i uruchamiane tylko w razie potrzeby, więc nie ma powodu, by ciągle przeznaczać zasoby kontekstu na nie.
Co ma, czego brakuje innym
Pi został zaprojektowany poprzez eliminację niepotrzebnego, a mimo to posiada funkcje, których brakuje Claude Code. Rozszerzenia i pakiety instaluje się za pomocą kilku poleceń:
pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi config # Enable or disable
Mechanizm rozszerzeń
Rozszerzenia są pisane przy użyciu API importowanego z pakietu Pi:
import { ExtensionAPI } from "@mariozechner/pi-coding-agent";
Rozszerzenie może być powiązane z wydarzeniami takimi jak wywołania narzędzi. Jeden z przykładów chroni przed niebezpiecznymi poleceniami w shellu:
export default function (pi: ExtensionAPI) {
pi.on("tool_call", async (event, ctx) => {
if (event.toolName === "bash"
&& event.input.command.includes("rm -rf")) {
const ok = await ctx.ui.confirm(
"Dangerous!", "Allow rm -rf?"
);
if (!ok) return { block: true, reason: "Blocked" };
}
});
}
1. Instalacja
Instalacja wymaga jednego polecenia:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
Alternatywą jest skrypt instalacyjny:
curl -fsSL https://pi.dev/install.sh | sh
Istnieją dwa sposoby uwierzytelniania. Jeden wykorzystuje klucz API:
# Use an API key
export ANTHROPIC_API_KEY=sk-ant-...
pi
Druga opcja wykorzystuje subskrypcję, którą już posiadasz:
# Use an existing subscription
pi
/login # Select a provider
Dzięki /login istniejące subskrypcje takie jak Anthropic Claude Pro lub Max, OpenAI ChatGPT Plus lub Pro (Codex) oraz GitHub Copilot mogą być używane bez żadnych zmian. Proces nauki jest bardzo prosty: wystarczy je zainstalować, zacząć z nimi rozmawiać i już działają.
2. Konfiguracja modelu
Pi obsługuje ponad 15 dostawców modeli LLM. Do najważniejszych należą:
- Anthropic
- OpenAI
- Google Gemini / Vertex
- DeepSeek
- xAI
- OpenRouter
- Amazon Bedrock
- Azure OpenAI
- Groq / Cerebras / Mistral など
Zmiana modeli w trakcie sesji jest zupełnie normalna:
/model # Model selection screen
Ctrl+L # Same as above
Shift+Tab # Switch thinking level (off–max)
Dostawców dostosowanych można dodać do pliku ~/.pi/agent/models.json. Każda API kompatybilna z OpenAI, Anthropic lub Google działa wyłącznie dzięki konfiguracji, a serwery routera, takie jak llama.cpp, mogą obsługiwać lokalne modele. „Brak przywiązania do konkretnego dostawcy” to jedna z najważniejszych zalet, na które kładzie nacisk Pi.
3. Zarządzanie sesjami
Sesje są przechowywane jako plik JSONL o strukturze drzewiastej, w katalogu ~/.pi/agent/sessions/, przy czym każda wiadomość zawiera pola id i parentId. Dzięki taka strukturze jeden plik umożliwia wykonywanie wszystkich tych operacji:
pi -c # Continue the most recent session
pi -r # Select from previous sessions
Komenda /tree jest szczególnie interesująca. Można wrócić do dowolnego momentu rozmowy i stamtąd kontynuować. Cała historia znajduje się w jednym pliku, więc łatwo jest powiedzieć „Chcę iść tą drogą, którą obrałem pół godziny temu” i faktycznie to zrobić.
/compact podsumowuje stare wiadomości w celu skompresowania kontekstu. Automatyczna kompresja jest włączona domyślnie, a jeśli kontekst się przepełni, system sam to naprawia i próbuje ponownie.
4. Rozszerzenia w szczegółach
Tutaj Pi pokazuje, do czego naprawdę służy. Personalizacja ma cztery poziomy:
Extensions (TypeScript) → Tools, commands, UI, and event handling
Skills → Procedures/instructions written in Markdown
Prompt Templates → Reusable prompts
Themes → Display themes
Pakiety z npm lub git są zarządzane w ten sposób:
pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi list
pi update --all
Rozszerzenia mogą wykonywać wszystko, co następuje:
- Dodawać własne narzędzia, w tym zamienniki dla tych wbudowanych.
- Tworzyć własne podagenty oraz tryby planowania.
- Wprowadzać mechanizmy kontroli uprawnień oraz ochrony ścieżek.
- Dodawać elementy interfejsu, takie jak linia stanu, nagłówek i stopka.
- Tworzyć punkty kontrolne w Git lub automatyczne komitowanie.
- Integrować serwery MCP.
- Jeśli chcesz, możesz uruchomić Doom podczas oczekiwania.
Kluczowym punktem jest to, że każda funkcja, którą inne agenty włączają do produktu – w tym podagenty, tryby planowania oraz okna z informacjami o uprawnieniach – może zostać stworzona jako rozszerzenie. Dlatego filozofia polega na utrzymaniu minimalnego rdzenia produktu.
5. Umiejętności
Umiejętności to pakiety zdolności napisane w formacie Markdown. Zgodnie ze standardem Agent Skills, folder zawierający plik SKILL.md stanowi jedną umiejętność.
<!-- ~/.pi/agent/skills/my-skill/SKILL.md -->
# My Skill
Use this skill when a user asks about X.
```
```text ## Steps 1. Perform this action. 2. Then perform that action. ```
Umiejętność można wywołać wyraźnie za pomocą /skill:name, a agent ładowa ją również samodzielnie, gdy zadanie na to pozwala. Kluczową decyzją projektową jest to, że umiejętności trafiają do kontekstu tylko wtedy, gdy są potrzebne. Zamiast wkładać wszystko do promptu systemu, one są aktywowane podczas użycia, dzięki czemu prompt systemu pozostaje na poziomie około tysiąca tokenów.
6. Pi Web, interfejs przeglądarki
Istnieje również interfejs przeglądarki o nazwie Pi Web:
npx @agegr/pi-web@latest
Jego główne funkcje:
- Przestrzeń robocza sesji umożliwiająca wyświetlanie, wznowienie, przemianowanie i usuwanie wcześniejszych rozmów według projektu.
- Dwa sposoby tworzenia gałęzi: rozpoczęcie nowej sesji od wiadomości lub utworzenie gałęzi w ramach obecnej sesji.
- Przeglądanie plików projektu oraz wyświetlanie różnic w plikach Git.
- Przełączanie drzewa roboczego Git.
- Logowanie do usługodawcy oraz ustawienia modelu, pakietu i umiejętności w przeglądarce.
Ponieważ dzieli ustawienia i pliki sesji z ~/.pi/agent z wersją terminalową, przechodzenie między przeglądarką a terminalą odbywa się bez problemów.
7. Pamięć
Kwestia pamięci okazuje się prosta. Zasada jest taka, że Pi nie potrzebuje oddzielnego bazy danych pamięci długoterminowej. Zamiast tego istnieją trzy mechanizmy:
1. The session itself is memory
The entire history is saved as JSONL and can be resumed at any time.
2. AGENTS.md / CLAUDE.md
Write project conventions, instructions, and commands in these files.
They are loaded at startup from global settings and the directory hierarchy.
3. Compaction
Long sessions are compressed by summarizing older parts.
However, the complete history remains in JSONL, so you can go back with /tree.
Innymi słowy, to, co zostało zrobione, znajduje się w sesji, a to, co chcesz mieć pod ręką, znajduje się w pliku AGENTS.md. Dodawanie pamięci za pomocą rozszerzeń to również częsty przypadek użycia.
8. Bezpieczeństwo
Pi nie posiada wbudowanej przestrzeni sandbox. Operacje czytania, zapisu, edycji oraz wykonywania poleceń bash odbywają się z uprawnieniami osoby, która je uruchomiła, i to samo dotyczy rozszerzeń. Jest to celowe. Półwbudowana przestrzeń sandbox wewnątrz procesu oferuje jedynie pozornie bezpieczne granice, dlatego oficjalna zasada polega na pozostawieniu rzeczywistej izolacji systemowi operacyjnemu oraz warstwom kontenerów lub maszyn wirtualnych. Niezaufane repozytoria oraz uruchomienia bez nadzoru powinny znajdować się w izolowanym środowisku.
Jedną z opcji jest umieszczenie całego środowiska Pi w Dockerze – to najprostsze rozwiązanie:
# 1. Put the entire pi environment in Docker (simplest)
Kolejnym rozwiązaniem jest uruchomienie Pi na hostzie i kierowanie wykonywania narzędzi wyłącznie do lokalnej mikro-VM:
# 2. Run pi on the host and route only tool execution
# to a local micro-VM (Gondolin)
pi -e ~/.pi/agent/extensions/gondolin
Funkcja o nazwie project trust dodaje mechanizm ochrony wprowadzanych danych. Zapobiega ona temu, by repozytoria potajemnie nadpisywały ustawienia lub rozszerzenia Pi, a domyślnie wymaga potwierdzenia przy pracach z niezweryfikowanymi projektami. Nie zapobiega ona jednak w pełni iniekcji poleceń, więc miej to na uwadze podczas pracy z nieznajomym kodem lub dokumentami.
9. Tworzenie własnego rozszerzenia
Najprostsze rozszerzenie to pojedynczy plik TypeScript. Rejestruje ono narzędzie:
export default function (pi: ExtensionAPI) {
pi.registerTool({
name: "deploy",
// Tool definition (input schema, execution logic)
});
może dodawać polecenia lub przerywać wywołania narzędzi:
pi.registerCommand("stats", {
// Custom command definition }); pi.on("tool_call", async (event, ctx) => {
// Intercept tool calls and process them
}); }
Umieść plik w katalogu ~/.pi/agent/extensions/ dla wszystkich projektów lub w .pi/extensions/ dla jednego projektu – wtedy zostanie on automatycznie załadowany po uruchomieniu Pi. Do jednorazowego testu wystarczy polecenie pi -e ./my-ext.ts. Oficjalny repozytorium zawiera wiele przykładów: automatyczne komitowanie, punkty kontrolne Git, integrację MCP oraz dostosowaną kompresję danych. Na Pi brak określonej funkcji jest czymś normalnym. Zwykłym rozwiązaniem jest dodanie jej samodzielnie lub zainstalowanie odpowiedniego pakietu.
Czego uczy Pi
Dla wszystkich, którzy tworzą własnego agenta, decyzje Pi stanowią przydatny punkt odniesienia. Unikaj pakietów obejmujących wszystko – zacznij od czterech narzędzi oraz systemowego promptu o długości około tysiąca tokenów, dodając tylko to, co jest konieczne. Projektowanie powinno zaczynać się od ustalenia, co usunąć, a nie od tego, co dodać.
Literatura pokrewna
- Pięć warstw agent harness, wraz z kodem, który nie działa bez nich — praktyczny przegląd pięciu miejsc, w których agent harness egzekwuje zasady w kodzie, od granic wykonywania po łańcuchy kontekstowe, oraz tego, co badania mogą, a czego nie mogą udowodnić.
- Notatki praktyczne: Budowa agenta do programowania w chmurze prywatnej: OpenCode + lokalny LLM — szczegółowy przewodnik po Notatkach praktycznych: Budowa agenta do programowania w chmurze prywatnej: OpenCode + lokalny LLM: umowy, sprawdzenia oraz miejsca na kod do wstawienia dla zespołów wdrażających ten wzorzec.