A minimal TypeScript toolkit for building AI agents and managing LLM deployments. Seven composable packages. MIT licensed. Built by Mario Zechner.
pi.Pi installs as a global npm package. You can authenticate via OAuth using an existing Claude/ChatGPT/Copilot subscription, or provide an API key directly.
If you already pay for Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot, Google Gemini CLI, or Google Antigravity, you can use your subscription without an API key.
| Path | Purpose |
|---|---|
| ~/.pi/agent/settings.json | Global settings (thinking level, theme, transport) |
| .pi/settings.json | Project-level overrides |
| ~/.pi/agent/SYSTEM.md | Global system prompt replacement |
| .pi/SYSTEM.md | Project system prompt replacement |
| ~/AGENTS.md or ./AGENTS.md | Context file (or CLAUDE.md) |
| ~/.pi/agent/prompts/ | Global prompt templates (invoked via /name) |
| ~/.pi/agent/skills/ | Global skills (Agent Skills standard) |
| ~/.pi/agent/models.json | Custom model definitions |
| ~/.pi/agent/themes/ | Theme files (hot-reload) |
A minimal terminal coding harness with four built-in tools: read, write, edit, bash. Everything else is opt-in via extensions.
Read files from the filesystem with line numbers. Supports ranges.
Create or overwrite files with specified content.
Exact string replacement edits—diff-based, reviewable changes.
Execute shell commands, capture stdout/stderr, and return output.
| Command | Purpose |
|---|---|
| /login | OAuth authentication flow (select provider) |
| /logout | Clear stored credentials |
| /model | Switch AI models interactively |
| /settings | Configure thinking, theme, delivery mode |
| /tree | Browse session history and branches |
| /fork | Create a new session branching from current point |
| /new | Start a fresh session |
| /compact | Summarize older messages to recover context |
| /copy | Copy assistant's last message to clipboard |
| /export [file] | Save session as HTML |
| /skill:name | Invoke a loaded skill by name |
| /templatename | Expand a prompt template |
Type @ to fuzzy-search and reference project files inline.
Shift+Enter for newline (Ctrl+Enter on Windows Terminal).
Ctrl+V to paste images, or drag-and-drop from the desktop.
!cmd runs and sends output; !!cmd runs silently.
| Shortcut | Action |
|---|---|
| Ctrl+L | Open model selector |
| Ctrl+P / Shift+Ctrl+P | Cycle through scoped models |
| Shift+Tab | Adjust thinking level (off / low / medium / high) |
| Escape (x2) | Open session tree navigator |
| Ctrl+O | Collapse / expand tool output |
| Ctrl+T | Collapse / expand thinking blocks |
Sessions persist as JSONL files with branching support. Every message can be the root of a new fork—experiment freely without losing prior work.
/fork creates a new branch at any point/tree browses the session graph/compact summarizes old turns to recover context window/export session.html renders a portable viewDefault TUI mode—multi-line editor, streaming, session branching.
Non-interactive output for scripting and pipelines.
Structured output for programmatic consumption.
Integration with parent processes over stdio RPC.
Embed Pi directly into your own TypeScript applications.
TypeScript library providing unified access to 20+ LLM providers with automatic model discovery, token tracking, cost monitoring, and context persistence.
| Event | Description |
|---|---|
| text_delta | Streamed response text chunk |
| toolcall_delta | Partial tool arguments (JSON streaming) |
| thinking_delta | Model reasoning content |
| done | Completion with stop reason and token usage |
| error | Failure with any partial content preserved |
<thinking> tagged text for providers that don't support native reasoning.Stateful agent with tool execution and event streaming, built on pi-ai. This is the engine powering the coding agent and the foundation for your own custom agents.
pi-agent-core distinguishes between two message formats:
user, assistant, toolResult, plus custom types| Event | Description |
|---|---|
| agent_start | Agent run has begun |
| agent_end | Final event—no more loop events will fire |
| turn_start | A new LLM-call-plus-tool-execution cycle begins |
| turn_end | The current turn completes |
| message_start | New assistant message begins streaming |
| message_update | Content delta for an in-progress message |
| message_end | Message fully assembled |
| tool_execution_start | A tool call is about to execute |
| tool_execution_update | Progress update from the tool |
| tool_execution_end | Tool call completed with result |
Tools are defined with AgentTool using TypeBox schemas for parameters. Two execution strategies are available:
Preflight sequentially, then execute all pending tool calls concurrently. Faster for independent operations.
Execute one-by-one in order. Safer when tool calls have implicit dependencies.
beforeToolCall hook can block execution; afterToolCall post-processes results.Interrupt running operations or queue work to run after completion.
Extend message types via TypeScript declaration merging—add your own discriminated variants.
Browser apps can proxy through backend servers to avoid exposing keys client-side.
Direct control via agentLoop for advanced use cases where the Agent class is too opinionated.
Seven packages that compose together. Use the full stack, or pick pieces for your own project.
Minimal terminal UI framework with flicker-free rendering. Three-strategy rendering only updates what changed, and CSI 2026 synchronized output prevents visual tearing.
Text, Input, Editor, Markdown, Loader, SelectList, SettingsList, Image, Box, Container
Multi-line editing, syntax-highlighted code blocks, vertical scrolling
Handles large pastes exceeding 10 lines without input glitches
CJK input methods with proper cursor positioning
Kitty or iTerm2 graphics protocols for rendering images
File paths and slash commands with fuzzy matching
An autonomous Slack bot powered by an LLM. Responds to @mentions, DMs, and can execute bash, read/write files, and manage its own development environment.
Reusable web components for building AI chat interfaces. Built on mini-lit web components and Tailwind CSS v4.
Primary high-level interface: messages + artifacts viewer
Lower-level chat for custom layouts with attachments and thinking
JavaScript REPL, HTML, SVG, Markdown rendering
PDFs, Word, spreadsheets, presentations, images
Sessions, credentials, preferences persist in the browser
Ollama, LM Studio, vLLM—plus automatic CORS proxy
A Node.js CLI for running large language models on remote GPU pods. Automates vLLM setup, configures tool calling for agentic models, and exposes OpenAI-compatible endpoints.
The Pi philosophy is minimalism at the core, extensibility everywhere else. Four layers let you shape the agent to your workflow.
~/.pi/agent/prompts/ — invoke with /name~/.pi/agent/themes/ with hot reloadSkills follow the Agent Skills standard: a SKILL.md file with YAML frontmatter describing the skill's purpose, plus supporting files (scripts, templates, references) in the same directory.
Extensions are TypeScript modules that can register:
Bundle prompts, skills, extensions, and themes into distributable Pi Packages. Ship via npm or git.
Add providers that aren't in pi-ai's built-in registry via ~/.pi/agent/models.json, as long as they speak the OpenAI or Anthropic API dialect.
Pi loads AGENTS.md (or CLAUDE.md for compatibility) from your home directory or project root. This is where project-specific instructions live—coding conventions, architectural notes, don't-do lists.
Deploy this documentation site (or your own pi-web-ui application) to Cloudflare Pages using the Wrangler CLI.
The guide you're reading is a single-file HTML SPA deployed to Cloudflare Pages. Here's the exact flow:
pi-web-ui ships reusable components for building a full chat UI in the browser. Because it uses IndexedDB for session/credential storage, no server is required—deploy as a static site on Cloudflare Pages.
For production workflows, connect your GitHub repository to Cloudflare Pages via the dashboard:
npm run build (or empty for static)dist (or . for static)main triggers a production deployproxyUrl option precisely for this pattern.Cloudflare Pages Analytics shows visits, bandwidth, and geographic distribution for free.
Built-in Core Web Vitals tracking—LCP, CLS, FID—for performance monitoring.
Add authentication via Cloudflare Access to gate internal tools.
Point your own domain via the Pages dashboard; SSL is automatic.