Skip to main content

​
Overview

Pi is a minimal TypeScript/Node.js coding agent with custom TUI (not Ink/React), supporting interactive, print, and RPC modes.
Binary path: ~/.local/bin/pi (via npm global)
Config: ~/.pi/agent/
License: MIT (open source)

​
Sandbox Profile

(allow file-read* file-write*
    (home-prefix "/.local/bin/pi")
    (home-subpath "/.pi")
)

(allow file-read-metadata
   (home-subpath "/Library")
)

​
Running in Safehouse

# Interactive mode
safehouse --enable=network --add-dirs="$PWD" -- pi

# Print mode (non-interactive)
safehouse --enable=network --add-dirs="$PWD" -- pi -p "write a function"

# RPC mode (headless JSON protocol)
safehouse --enable=network --add-dirs="$PWD" -- pi --rpc

​
Custom TUI

Pi uses its own terminal UI library (@mariozechner/pi-tui):
  • Differential rendering (ANSI escape codes to stdout)
  • Kitty keyboard protocol support
  • Terminal image support (Kitty, iTerm2)
  • OSC 8 hyperlink support

​
Credentials

No keyring integration. Credentials stored in:
  • ~/.pi/agent/auth.json (mode 0o600, plain JSON)
  • API keys and OAuth tokens in one file
  • File locking via proper-lockfile

​
OAuth Flows

ProviderPortEndpoints
AnthropicNone (manual paste)claude.ai/oauth/authorize
GitHub CopilotNone (device code)github.com/login/device/code
Google Antigravity127.0.0.1:51121accounts.google.com/o/oauth2/v2/auth
Google Gemini CLI127.0.0.1:8085accounts.google.com/o/oauth2/v2/auth
OpenAI Codex127.0.0.1:1455auth.openai.com/oauth/authorize

​
Extension System

Extensions can:
  • Register custom tools (including replacing bash tool)
  • Register custom commands
  • Hook into session events
  • Spawn subprocesses, access filesystem, make network requests
Loaded via jiti (TypeScript-in-Node.js runtime).

​
Optional Sandbox Extension

Pi includes an optional sandbox extension using @anthropic-ai/sandbox-runtime:
  • Uses sandbox-exec on macOS, bubblewrap on Linux
  • Opt-in via pi -e ./sandbox
  • NOT enabled by default

​
Tool Binaries

Pi auto-downloads fd and rg (ripgrep) if not on PATH:
  • Downloads from GitHub releases
  • Installs to ~/.pi/agent/bin/
  • Adds to PATH for agent use

​
Configuration Paths

PathPurpose
~/.pi/agent/auth.jsonCredentials (mode 0o600)
~/.pi/agent/settings.jsonUser settings
~/.pi/agent/models.jsonCustom model definitions
~/.pi/agent/sessions/Session history (JSONL)
~/.pi/agent/bin/Auto-downloaded tools (fd, rg)
~/.pi/agent/extensions/Global extensions
<cwd>/.pi/Project-local config

Build docs developers (and LLMs) love

Get started for freeTalk to us