@phi-code-admin/phi-code 0.74.2 → 0.75.0

package/README.md

@@ -1,554 +1,653 @@
 <p align="center">
-  <h1 align="center">Φ Phi Code</h1>
-  <p align="center"><strong>The Ultimate Open-Source Coding Agent</strong></p>
-  <p align="center">Built on <a href="https://github.com/badlogic/pi-mono">Pi</a> — supercharged with memory, sub-agents, orchestration, and smart routing.</p>
+  <a href="https://pi.dev">
+    <img alt="pi logo" src="https://pi.dev/logo-auto.svg" width="128">
+  </a>
+</p>
+<p align="center">
+  <a href="https://discord.com/invite/3cU7Bz4UPx"><img alt="Discord" src="https://img.shields.io/badge/discord-community-5865F2?style=flat-square&logo=discord&logoColor=white" /></a>
+  <a href="https://www.npmjs.com/package/@earendil-works/pi-coding-agent"><img alt="npm" src="https://img.shields.io/npm/v/@earendil-works/pi-coding-agent?style=flat-square" /></a>
 </p>
-
 <p align="center">
-  <a href="https://www.npmjs.com/package/@phi-code-admin/phi-code"><img alt="npm" src="https://img.shields.io/npm/v/@phi-code-admin/phi-code?style=flat-square&label=npm" /></a>
-  <a href="https://github.com/uglyswap/phi-code"><img alt="GitHub" src="https://img.shields.io/badge/github-phi--code-181717?style=flat-square&logo=github" /></a>
-  <a href="https://github.com/uglyswap/phi-code/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-green?style=flat-square" /></a>
+  <a href="https://pi.dev">pi.dev</a> domain graciously donated by
+  <br /><br />
+  <a href="https://exe.dev"><img src="docs/images/exy.png" alt="Exy mascot" width="48" /><br />exe.dev</a>
 </p>
 
+> New issues and PRs from new contributors are auto-closed by default. Maintainers review auto-closed issues daily. See [CONTRIBUTING.md](../../CONTRIBUTING.md).
+
 ---
 
-## What is Phi Code?
+Pi is a minimal terminal coding harness. Adapt pi to your workflows, not the other way around, without having to fork and modify pi internals. Extend it with TypeScript [Extensions](#extensions), [Skills](#skills), [Prompt Templates](#prompt-templates), and [Themes](#themes). Put your extensions, skills, prompt templates, and themes in [Pi Packages](#pi-packages) and share them with others via npm or git.
 
-Phi Code is a **production-grade** coding agent for the terminal. It extends [Pi](https://github.com/badlogic/pi-mono) (the minimal terminal coding harness) with everything you need for serious development work:
+Pi ships with powerful defaults but skips features like sub agents and plan mode. Instead, you can ask pi to build what you want or install a third party pi package that matches your workflow.
 
-- 🧠 **Persistent Memory** — Notes, ontology, and vector search across sessions
-- 🤖 **5 Sub-Agents** — Specialized agents for code, exploration, planning, review, and testing
-- 🎯 **Smart Routing** — Automatically assigns the right model to the right task
-- 📋 **Orchestrator** — Plan complex projects, execute with parallel sub-agents
-- 🔍 **Web Search** — Brave API integration for real-time research
-- ⚡ **Benchmark** — Test your models and find the best ones for each role
-- 🧩 **12 Built-in Skills** — API design, security, testing, DevOps, and more
-- 🔌 **Provider-Neutral** — Works with any OpenAI-compatible API
+Pi runs in four modes: interactive, print or JSON, RPC for process integration, and an SDK for embedding in your own apps. See [openclaw/openclaw](https://github.com/openclaw/openclaw) for a real-world SDK integration.
 
-**Phi Code works with any LLM provider:** Alibaba Cloud, OpenAI, Anthropic, Google, OpenRouter, Groq, Ollama, LM Studio, and more.
+## Share your OSS coding agent sessions
 
----
+If you use pi for open source work, please share your coding agent sessions.
+
+Public OSS session data helps improve models, prompts, tools, and evaluations using real development workflows.
+
+For the full explanation, see [this post on X](https://x.com/badlogicgames/status/2037811643774652911).
+
+To publish sessions, use [`badlogic/pi-share-hf`](https://github.com/badlogic/pi-share-hf). Read its README.md for setup instructions. All you need is a Hugging Face account, the Hugging Face CLI, and `pi-share-hf`.
+
+You can also watch [this video](https://x.com/badlogicgames/status/2041151967695634619), where I show how I publish my `pi-mono` sessions.
+
+I regularly publish my own `pi-mono` work sessions here:
+
+- [badlogicgames/pi-mono on Hugging Face](https://huggingface.co/datasets/badlogicgames/pi-mono)
 
 ## Table of Contents
 
 - [Quick Start](#quick-start)
-- [Setup Wizard](#setup-wizard)
-- [API Key Management](#api-key-management)
 - [Providers & Models](#providers--models)
-- [Commands](#commands)
-- [Sub-Agents](#sub-agents)
-- [Orchestrator](#orchestrator)
-- [Memory System](#memory-system)
-- [Smart Routing](#smart-routing)
-- [Benchmark](#benchmark)
-- [Skills](#skills)
-- [Extensions](#extensions)
-- [Configuration Files](#configuration-files)
-- [Keyboard Shortcuts](#keyboard-shortcuts)
+- [Interactive Mode](#interactive-mode)
+  - [Editor](#editor)
+  - [Commands](#commands)
+  - [Keyboard Shortcuts](#keyboard-shortcuts)
+  - [Message Queue](#message-queue)
 - [Sessions](#sessions)
-- [CLI Reference](#cli-reference)
+  - [Branching](#branching)
+  - [Compaction](#compaction)
+- [Settings](#settings)
+- [Context Files](#context-files)
+- [Customization](#customization)
+  - [Prompt Templates](#prompt-templates)
+  - [Skills](#skills)
+  - [Extensions](#extensions)
+  - [Themes](#themes)
+  - [Pi Packages](#pi-packages)
+- [Programmatic Usage](#programmatic-usage)
 - [Philosophy](#philosophy)
-- [Credits](#credits)
+- [CLI Reference](#cli-reference)
 
 ---
 
 ## Quick Start
 
-### Install
-
 ```bash
-npm install -g @phi-code-admin/phi-code
+curl -fsSL https://pi.dev/install.sh | sh
 ```
 
-The installer automatically sets up:
-- 9 extensions → `~/.phi/agent/extensions/`
-- 5 sub-agent definitions → `~/.phi/agent/agents/`
-- 12 skills → `~/.phi/agent/skills/`
-
-### First Run
+Or with npm:
 
 ```bash
-phi
+npm install -g @earendil-works/pi-coding-agent
 ```
 
-Then run the setup wizard:
+Authenticate with an API key:
 
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+pi
 ```
-/phi-init
+
+Or use your existing subscription:
+
+```bash
+pi
+/login  # Then select provider
 ```
 
-The wizard will:
-1. Ask you to **choose a provider** (numbered list)
-2. Ask you to **paste your API key**
-3. **Save everything** to `~/.phi/agent/models.json` (persistent)
-4. Let you **choose models** for each role
+Then just talk to pi. By default, pi gives the model four tools: `read`, `write`, `edit`, and `bash`. The model uses these to fulfill your requests. Add capabilities via [skills](#skills), [prompt templates](#prompt-templates), [extensions](#extensions), or [pi packages](#pi-packages).
 
-That's it. No environment variables, no JSON editing, no command line flags.
+**Platform notes:** [Windows](docs/windows.md) | [Termux (Android)](docs/termux.md) | [tmux](docs/tmux.md) | [Terminal setup](docs/terminal-setup.md) | [Shell aliases](docs/shell-aliases.md)
 
-### Example
+---
 
-```bash
-$ phi
-> /phi-init
-⚠️ No API keys detected. Let's set one up!
-
-Available providers:
-  1. Alibaba Coding Plan
-  2. OpenAI
-  3. Anthropic
-  4. Google
-  ...
-
-Choose provider (number): 1
-Enter your Alibaba Coding Plan API key: sk-sp-xxxxx
-
-✅ API key saved to ~/.phi/agent/models.json
-⚠️ Restart phi for models to load.
-```
+## Providers & Models
 
-Restart `phi`, run `/phi-init` again → models are detected → pick a setup mode → done.
+For each built-in provider, pi maintains a list of tool-capable models, updated with every release. Authenticate via subscription (`/login`) or API key, then select any model from that provider via `/model` (or Ctrl+L).
+
+**Subscriptions:**
+- Anthropic Claude Pro/Max
+- OpenAI ChatGPT Plus/Pro (Codex)
+- GitHub Copilot
+
+**API keys:**
+- Anthropic
+- OpenAI
+- Azure OpenAI
+- DeepSeek
+- Google Gemini
+- Google Vertex
+- Amazon Bedrock
+- Mistral
+- Groq
+- Cerebras
+- Cloudflare AI Gateway
+- Cloudflare Workers AI
+- xAI
+- OpenRouter
+- Vercel AI Gateway
+- ZAI
+- OpenCode Zen
+- OpenCode Go
+- Hugging Face
+- Fireworks
+- Together AI
+- Kimi For Coding
+- MiniMax
+- Xiaomi MiMo
+- Xiaomi MiMo Token Plan (China)
+- Xiaomi MiMo Token Plan (Amsterdam)
+- Xiaomi MiMo Token Plan (Singapore)
+
+See [docs/providers.md](docs/providers.md) for detailed setup instructions.
+
+**Custom providers & models:** Add providers via `~/.pi/agent/models.json` if they speak a supported API (OpenAI, Anthropic, Google). For custom APIs or OAuth, use extensions. See [docs/models.md](docs/models.md) and [docs/custom-provider.md](docs/custom-provider.md).
 
 ---
 
-## Setup Wizard
+## Interactive Mode
 
-The `/phi-init` wizard has **3 modes**:
+<p align="center"><img src="docs/images/interactive-mode.png" alt="Interactive Mode" width="600"></p>
 
-| Mode | What it does | Time |
-|------|-------------|------|
-| **auto** | Assigns optimal defaults based on available models | Instant |
-| **benchmark** | Tests each model with real coding tasks, assigns by score | 10-15 min |
-| **manual** | You choose the model for each role interactively | 2-5 min |
+The interface from top to bottom:
 
-The wizard creates:
-- `~/.phi/agent/routing.json` — Model assignments per task type
-- `~/.phi/agent/agents/` — Sub-agent definitions
-- `~/.phi/memory/AGENTS.md` — Your project instructions template
+- **Startup header** - Shows shortcuts (`/hotkeys` for all), loaded AGENTS.md files, prompt templates, skills, and extensions
+- **Messages** - Your messages, assistant responses, tool calls and results, notifications, errors, and extension UI
+- **Editor** - Where you type; border color indicates thinking level
+- **Footer** - Working directory, session name, total token/cache usage, cost, context usage, current model
 
----
+The editor can be temporarily replaced by other UI, like built-in `/settings` or custom UI from extensions (e.g., a Q&A tool that lets the user answer model questions in a structured format). [Extensions](#extensions) can also replace the editor, add widgets above/below it, a status line, custom footer, or overlays.
 
-## API Key Management
+### Editor
 
-### Option 1: Interactive Setup (recommended)
+| Feature | How |
+|---------|-----|
+| File reference | Type `@` to fuzzy-search project files |
+| Path completion | Tab to complete paths |
+| Multi-line | Shift+Enter (or Ctrl+Enter on Windows Terminal) |
+| Images | Ctrl+V to paste (Alt+V on Windows), or drag onto terminal |
+| Bash commands | `!command` runs and sends output to LLM, `!!command` runs without sending |
 
-Run `/phi-init` — it asks for your provider and key, saves automatically.
+Standard editing keybindings for delete word, undo, etc. See [docs/keybindings.md](docs/keybindings.md).
 
-### Option 2: In-Session Command
+### Commands
 
-```
-/api-key set alibaba sk-sp-your-key-here
-/api-key set openai sk-your-key-here
-/api-key set anthropic sk-ant-your-key-here
-```
+Type `/` in the editor to trigger commands. [Extensions](#extensions) can register custom commands, [skills](#skills) are available as `/skill:name`, and [prompt templates](#prompt-templates) expand via `/templatename`.
 
-This **saves to `~/.phi/agent/models.json`** (persistent across sessions).
-Restart `phi` for new models to load.
+| Command | Description |
+|---------|-------------|
+| `/login`, `/logout` | OAuth authentication |
+| `/model` | Switch models |
+| `/scoped-models` | Enable/disable models for Ctrl+P cycling |
+| `/settings` | Thinking level, theme, message delivery, transport |
+| `/resume` | Pick from previous sessions |
+| `/new` | Start a new session |
+| `/name <name>` | Set session display name |
+| `/session` | Show session info (file, ID, messages, tokens, cost) |
+| `/tree` | Jump to any point in the session and continue from there |
+| `/fork` | Create a new session from a previous user message |
+| `/clone` | Duplicate the current active branch into a new session |
+| `/compact [prompt]` | Manually compact context, optional custom instructions |
+| `/copy` | Copy last assistant message to clipboard |
+| `/export [file]` | Export session to HTML file |
+| `/share` | Upload as private GitHub gist with shareable HTML link |
+| `/reload` | Reload keybindings, extensions, skills, prompts, and context files (themes hot-reload automatically) |
+| `/hotkeys` | Show all keyboard shortcuts |
+| `/changelog` | Display version history |
+| `/quit` | Quit pi |
+
+### Keyboard Shortcuts
+
+See `/hotkeys` for the full list. Customize via `~/.pi/agent/keybindings.json`. See [docs/keybindings.md](docs/keybindings.md).
+
+**Commonly used:**
 
-### Option 3: View Configured Keys
+| Key | Action |
+|-----|--------|
+| Ctrl+C | Clear editor |
+| Ctrl+C twice | Quit |
+| Escape | Cancel/abort |
+| Escape twice | Open `/tree` |
+| Ctrl+L | Open model selector |
+| Ctrl+P / Shift+Ctrl+P | Cycle scoped models forward/backward |
+| Shift+Tab | Cycle thinking level |
+| Ctrl+O | Collapse/expand tool output |
+| Ctrl+T | Collapse/expand thinking blocks |
 
-```
-/api-key list       # Show configured keys (masked)
-/api-key providers  # List all supported providers
-```
+### Message Queue
+
+Submit messages while the agent is working:
+
+- **Enter** queues a *steering* message, delivered after the current assistant turn finishes executing its tool calls
+- **Alt+Enter** queues a *follow-up* message, delivered only after the agent finishes all work
+- **Escape** aborts and restores queued messages to editor
+- **Alt+Up** retrieves queued messages back to editor
+
+On Windows Terminal, `Alt+Enter` is fullscreen by default. Remap it in [docs/terminal-setup.md](docs/terminal-setup.md) so pi can receive the follow-up shortcut.
+
+Configure delivery in [settings](docs/settings.md): `steeringMode` and `followUpMode` can be `"one-at-a-time"` (default, waits for response) or `"all"` (delivers all queued at once). `transport` selects provider transport preference (`"sse"`, `"websocket"`, or `"auto"`) for providers that support multiple transports.
+
+---
+
+## Sessions
 
-### Option 4: Environment Variables
+Sessions are stored as JSONL files with a tree structure. Each entry has an `id` and `parentId`, enabling in-place branching without creating new files. See [docs/session-format.md](docs/session-format.md) for file format.
 
-For CI/CD or scripting, you can still use environment variables:
+### Management
+
+Sessions auto-save to `~/.pi/agent/sessions/` organized by working directory.
 
 ```bash
-# Linux/Mac
-export ALIBABA_CODING_PLAN_KEY="sk-sp-xxx"
-export OPENAI_API_KEY="sk-xxx"
-export ANTHROPIC_API_KEY="sk-ant-xxx"
-
-# Windows (persistent)
-setx ALIBABA_CODING_PLAN_KEY "sk-sp-xxx"
-setx OPENAI_API_KEY "sk-xxx"
+pi -c                  # Continue most recent session
+pi -r                  # Browse and select from past sessions
+pi --no-session        # Ephemeral mode (don't save)
+pi --session <path|id> # Use specific session file or ID
+pi --fork <path|id>    # Fork specific session file or ID into a new session
 ```
 
-### Option 5: models.json (Direct Edit)
+Use `/session` in interactive mode to see the current session ID before reusing it with `--session <id>` or `--fork <id>`.
 
-Edit `~/.phi/agent/models.json` directly for advanced configurations:
+### Branching
 
-```json
-{
-  "providers": {
-    "my-provider": {
-      "baseUrl": "https://api.example.com/v1",
-      "api": "openai-completions",
-      "apiKey": "your-key-here",
-      "models": [
-        {
-          "id": "model-name",
-          "name": "Display Name",
-          "reasoning": true,
-          "input": ["text"],
-          "contextWindow": 131072,
-          "maxTokens": 16384
-        }
-      ]
-    }
-  }
-}
-```
+**`/tree`** - Navigate the session tree in-place. Select any previous point, continue from there, and switch between branches. All history preserved in a single file.
 
-The `apiKey` field supports:
-- **Direct value**: `"sk-xxx"` — uses as-is
-- **Environment variable name**: `"OPENAI_API_KEY"` — resolved at runtime
-- **Shell command**: `"!cat ~/.secrets/key"` — executed and output used
+<p align="center"><img src="docs/images/tree-view.png" alt="Tree View" width="600"></p>
 
----
+- Search by typing, fold/unfold and jump between branches with Ctrl+←/Ctrl+→ or Alt+←/Alt+→, page with ←/→
+- Filter modes (Ctrl+O): default → no-tools → user-only → labeled-only → all
+- Press Shift+L to label entries as bookmarks and Shift+T to toggle label timestamps
 
-## Providers & Models
+**`/fork`** - Create a new session file from a previous user message on the active branch. Opens a selector, copies the active path up to that point, and places the selected prompt in the editor for modification.
 
-### Supported Providers
+**`/clone`** - Duplicate the current active branch into a new session file at the current position. The new session keeps the full active-path history and opens with an empty editor.
 
-| Provider | API Key Env Var | Notes |
-|----------|----------------|-------|
-| Alibaba Cloud | `ALIBABA_CODING_PLAN_KEY` | DashScope (Qwen, Kimi, GLM, MiniMax) |
-| OpenAI | `OPENAI_API_KEY` | GPT-4o, o1, o3, etc. |
-| Anthropic | `ANTHROPIC_API_KEY` | Claude Sonnet, Opus, Haiku |
-| Google | `GOOGLE_API_KEY` | Gemini Pro, Flash, Ultra |
-| OpenRouter | `OPENROUTER_API_KEY` | 200+ models from all providers |
-| Groq | `GROQ_API_KEY` | Ultra-fast inference |
-| Ollama | — | Local, `ollama serve` on port 11434 |
-| LM Studio | — | Local, start server on port 1234 |
+**`--fork <path|id>`** - Fork an existing session file or partial session UUID directly from the CLI. This copies the full source session into a new session file in the current project.
 
-Plus all Pi built-in providers: Azure OpenAI, Google Vertex, Amazon Bedrock, Mistral, Cerebras, xAI, Hugging Face, and more.
+### Compaction
 
-### Switching Models
+Long sessions can exhaust context windows. Compaction summarizes older messages while keeping recent ones.
 
-- **Ctrl+L** — Open model selector (pick from list)
-- **Ctrl+P** — Cycle through scoped models
-- `/model <name>` — Switch by name
+**Manual:** `/compact` or `/compact <custom instructions>`
+
+**Automatic:** Enabled by default. Triggers on context overflow (recovers and retries) or when approaching the limit (proactive). Configure via `/settings` or `settings.json`.
+
+Compaction is lossy. The full history remains in the JSONL file; use `/tree` to revisit. Customize compaction behavior via [extensions](#extensions). See [docs/compaction.md](docs/compaction.md) for internals.
 
 ---
 
-## Commands
+## Settings
 
-Phi Code adds these commands on top of Pi's built-in commands:
+Use `/settings` to modify common options, or edit JSON files directly:
 
-| Command | Description |
-|---------|-------------|
-| `/phi-init` | Interactive setup wizard — configure providers, keys, and models |
-| `/api-key` | Manage API keys (`set`, `list`, `providers`, `help`) |
-| `/plan` | Full orchestration — analyze project, create spec, execute with sub-agents |
-| `/run` | Execute a todo.md plan with parallel sub-agents |
-| `/agents` | List available sub-agents and their capabilities |
-| `/benchmark` | Test model performance (`/benchmark all`, `/benchmark code-gen`) |
-| `/search` | Web search via Brave API |
-| `/crawl` | Fetch and extract content from a URL |
+| Location | Scope |
+|----------|-------|
+| `~/.pi/agent/settings.json` | Global (all projects) |
+| `.pi/settings.json` | Project (overrides global) |
 
-### Pi Built-in Commands
+See [docs/settings.md](docs/settings.md) for all options.
 
-| Command | Description |
-|---------|-------------|
-| `/login`, `/logout` | OAuth authentication |
-| `/model` | Switch models |
-| `/settings` | Thinking level, theme, transport |
-| `/resume` | Pick from previous sessions |
-| `/new` | Start a new session |
-| `/tree` | Navigate session history |
-| `/compact` | Manually compact context |
-| `/copy` | Copy last response to clipboard |
-| `/export` | Export session to HTML |
-| `/reload` | Reload extensions, skills, prompts |
+### Telemetry and update checks
+
+Pi has two separate startup features:
+
+- **Update check:** fetches `https://pi.dev/api/latest-version` to check whether a newer Pi version exists. Disable it with `PI_SKIP_VERSION_CHECK=1`. Disabling update checks only turns off this check.
+- **Install/update telemetry:** after first install or a changelog-detected update, sends an anonymous version ping to `https://pi.dev/api/report-install`. Opt out by setting `enableInstallTelemetry` to `false` in `settings.json`, or by setting `PI_TELEMETRY=0`. This does not disable update checks; Pi may still contact `pi.dev` for the latest version unless update checks are disabled or offline mode is enabled.
+
+Use `--offline` or `PI_OFFLINE=1` to disable all startup network operations described here, including update checks, package update checks, and install/update telemetry.
 
 ---
 
-## Sub-Agents
+## Context Files
 
-Phi Code ships with **5 specialized sub-agents**, each with its own system prompt and tool set:
+Pi loads `AGENTS.md` (or `CLAUDE.md`) at startup from:
+- `~/.pi/agent/AGENTS.md` (global)
+- Parent directories (walking up from cwd)
+- Current directory
 
-| Agent | Role | Tools |
-|-------|------|-------|
-| **code** | Write and edit code, run commands | `read`, `write`, `edit`, `bash` |
-| **explore** | Investigate codebases, read-only analysis | `read`, `bash` |
-| **plan** | Architecture, design, technical planning | `read`, `bash` |
-| **review** | Code review, security audit, best practices | `read`, `bash` |
-| **test** | Write tests, fix tests, run test suites | `read`, `write`, `edit`, `bash` |
+Use for project instructions, conventions, common commands. All matching files are concatenated.
 
-View agents: `/agents`
-View details: `/agents code`
+Disable context file loading with `--no-context-files` (or `-nc`).
 
-Agent definitions are Markdown files with YAML frontmatter in `~/.phi/agent/agents/`. You can customize them or add your own.
+### System Prompt
+
+Replace the default system prompt with `.pi/SYSTEM.md` (project) or `~/.pi/agent/SYSTEM.md` (global). Append without replacing via `APPEND_SYSTEM.md`.
 
 ---
 
-## Orchestrator
+## Customization
 
-The `/plan` command is a **full-cycle project orchestrator**:
+### Prompt Templates
 
-```
-/plan Build a REST API with authentication and tests
-```
+Reusable prompts as Markdown files. Type `/name` to expand.
 
-This single command:
-1. **Analyzes** your project structure
-2. **Creates** a detailed spec (`spec.md`)
-3. **Generates** a task list with dependencies (`todo.md`)
-4. **Executes** all tasks with parallel sub-agents
-5. **Reports** progress in real-time (`progress.md`)
+```markdown
+<!-- ~/.pi/agent/prompts/review.md -->
+Review this code for bugs, security issues, and performance problems.
+Focus on: {{focus}}
+```
 
-### How It Works
+Place in `~/.pi/agent/prompts/`, `.pi/prompts/`, or a [pi package](#pi-packages) to share with others. See [docs/prompt-templates.md](docs/prompt-templates.md).
 
-- Tasks are organized into **waves** based on dependencies
-- Independent tasks run **in parallel** via `Promise.all`
-- Each sub-agent receives **shared context**: project description, spec summary, and results from completed dependency tasks
-- Failed tasks are skipped; dependents are also skipped with a clear report
-- All files are written to `.phi/plans/<timestamp>/`
+### Skills
 
-### Step-by-Step Mode
+On-demand capability packages following the [Agent Skills standard](https://agentskills.io). Invoke via `/skill:name` or let the agent load them automatically.
 
-Use `/run` to execute an existing plan:
+```markdown
+<!-- ~/.pi/agent/skills/my-skill/SKILL.md -->
+# My Skill
+Use this skill when the user asks about X.
 
-```
-/run .phi/plans/2026-03-07T21-00-00/todo.md
+## Steps
+1. Do this
+2. Then that
 ```
 
----
+Place in `~/.pi/agent/skills/`, `~/.agents/skills/`, `.pi/skills/`, or `.agents/skills/` (from `cwd` up through parent directories) or a [pi package](#pi-packages) to share with others. See [docs/skills.md](docs/skills.md).
 
-## Memory System
+### Extensions
 
-Phi Code remembers across sessions via **sigma-memory**:
+<p align="center"><img src="docs/images/doom-extension.png" alt="Doom Extension" width="600"></p>
 
-### Components
+TypeScript modules that extend pi with custom tools, commands, keyboard shortcuts, event handlers, and UI components.
 
-| Component | What it stores | Location |
-|-----------|---------------|----------|
-| **Notes** | Free-form text notes | `~/.phi/memory/notes/` |
-| **Ontology** | Structured knowledge graph (entities + relations) | `~/.phi/memory/ontology/` |
-| **QMD** | Vector embeddings for semantic search | `~/.phi/memory/qmd/` |
-| **AGENTS.md** | Global project instructions | `~/.phi/memory/AGENTS.md` |
+```typescript
+export default function (pi: ExtensionAPI) {
+  pi.registerTool({ name: "deploy", ... });
+  pi.registerCommand("stats", { ... });
+  pi.on("tool_call", async (event, ctx) => { ... });
+}
+```
 
-### Auto-Recall
+The default export can also be `async`. pi waits for async extension factories before startup continues, which is useful for one-time initialization such as fetching remote model lists before calling `pi.registerProvider()`.
 
-Memory is automatically searched before every response. When you ask "how did we implement the auth system?", Phi Code searches its memory and includes relevant context.
+**What's possible:**
+- Custom tools (or replace built-in tools entirely)
+- Sub-agents and plan mode
+- Custom compaction and summarization
+- Permission gates and path protection
+- Custom editors and UI components
+- Status lines, headers, footers
+- Git checkpointing and auto-commit
+- SSH and sandbox execution
+- MCP server integration
+- Make pi look like Claude Code
+- Games while waiting (yes, Doom runs)
+- ...anything you can dream up
 
-### Manual Commands
+Place in `~/.pi/agent/extensions/`, `.pi/extensions/`, or a [pi package](#pi-packages) to share with others. See [docs/extensions.md](docs/extensions.md) and [examples/extensions/](examples/extensions/).
 
-Memory tools are available to the LLM:
-- `memory_search` — Semantic search across all memory
-- `memory_note` — Save a note for future sessions
-- `memory_entity` / `memory_relation` — Build the knowledge graph
+### Themes
 
----
+Built-in: `dark`, `light`. Themes hot-reload: modify the active theme file and pi immediately applies changes.
 
-## Smart Routing
+Place in `~/.pi/agent/themes/`, `.pi/themes/`, or a [pi package](#pi-packages) to share with others. See [docs/themes.md](docs/themes.md).
 
-The smart router automatically assigns the best model to each task based on your `routing.json` configuration:
+### Pi Packages
 
-| Task Type | Best For |
-|-----------|----------|
-| **code-generation** | Writing new code, refactoring |
-| **debugging** | Finding and fixing bugs |
-| **planning** | Architecture, design decisions |
-| **tool-calling** | File operations, bash commands |
-| **orchestration** | Managing sub-agents, complex workflows |
-| **default** | Everything else |
+Bundle and share extensions, skills, prompts, and themes via npm or git. Find packages on [npmjs.com](https://www.npmjs.com/search?q=keywords%3Api-package) or [Discord](https://discord.com/channels/1456806362351669492/1457744485428629628).
+
+> **Security:** Pi packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables. Review source code before installing third-party packages.
+
+```bash
+pi install npm:@foo/pi-tools
+pi install npm:@foo/pi-tools@1.2.3      # pinned version
+pi install git:github.com/user/repo
+pi install git:github.com/user/repo@v1  # tag or commit
+pi install git:git@github.com:user/repo
+pi install git:git@github.com:user/repo@v1  # tag or commit
+pi install https://github.com/user/repo
+pi install https://github.com/user/repo@v1      # tag or commit
+pi install ssh://git@github.com/user/repo
+pi install ssh://git@github.com/user/repo@v1    # tag or commit
+pi remove npm:@foo/pi-tools
+pi uninstall npm:@foo/pi-tools          # alias for remove
+pi list
+pi update                               # update pi and packages (skips pinned packages)
+pi update --extensions                  # update packages only
+pi update --self                        # update pi only
+pi update --self --force                # reinstall pi even if current
+pi update npm:@foo/pi-tools             # update one package
+pi config                               # enable/disable extensions, skills, prompts, themes
+```
 
-Configuration: `~/.phi/agent/routing.json`
+Packages install to `~/.pi/agent/git/` (git) or global npm. Use `-l` for project-local installs (`.pi/git/`, `.pi/npm/`). Git packages install dependencies with `npm install --omit=dev` by default, so runtime deps must be listed under `dependencies`; when `npmCommand` is configured, git packages use plain `install` for compatibility with wrappers. If you use a Node version manager and want package installs to reuse a stable npm context, set `npmCommand` in `settings.json`, for example `["mise", "exec", "node@20", "--", "npm"]`.
+
+Create a package by adding a `pi` key to `package.json`:
 
 ```json
 {
-  "code-generation": { "preferred": "qwen3.5-plus", "fallback": "default" },
-  "debugging": { "preferred": "kimi-k2.5", "fallback": "default" },
-  "default": { "preferred": "default", "fallback": "default" }
+  "name": "my-pi-package",
+  "keywords": ["pi-package"],
+  "pi": {
+    "extensions": ["./extensions"],
+    "skills": ["./skills"],
+    "prompts": ["./prompts"],
+    "themes": ["./themes"]
+  }
 }
 ```
 
-Set models to `"default"` to use whatever model is currently active.
+Without a `pi` manifest, pi auto-discovers from conventional directories (`extensions/`, `skills/`, `prompts/`, `themes/`).
+
+See [docs/packages.md](docs/packages.md).
 
 ---
 
-## Benchmark
+## Programmatic Usage
 
-Test your models with real coding tasks:
+### SDK
 
+```typescript
+import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@earendil-works/pi-coding-agent";
+
+const authStorage = AuthStorage.create();
+const modelRegistry = ModelRegistry.create(authStorage);
+const { session } = await createAgentSession({
+  sessionManager: SessionManager.inMemory(),
+  authStorage,
+  modelRegistry,
+});
+
+await session.prompt("What files are in the current directory?");
 ```
-/benchmark all              # Test all available models
-/benchmark code-gen         # Test only code generation
-/benchmark debug            # Test only debugging
-```
 
-### Categories
+For advanced multi-session runtime replacement, use `createAgentSessionRuntime()` and `AgentSessionRuntime`.
+
+See [docs/sdk.md](docs/sdk.md) and [examples/sdk/](examples/sdk/).
+
+### RPC Mode
 
-| Category | Weight | What it tests |
-|----------|--------|---------------|
-| code-gen | ×2 | Write a function from spec |
-| debug | ×2 | Find and fix a bug |
-| planning | ×2 | Design an architecture |
-| tool-calling | ×1 | Structured tool use |
-| speed | ×1 | Response latency |
-| orchestration | ×2 | Multi-step task planning |
+For non-Node.js integrations, use RPC mode over stdin/stdout:
 
-### Scoring
+```bash
+pi --mode rpc
+```
 
-Models are scored 0-100 and ranked into tiers:
+RPC mode uses strict LF-delimited JSONL framing. Clients must split records on `\n` only. Do not use generic line readers like Node `readline`, which also split on Unicode separators inside JSON payloads.
 
-| Tier | Score | Meaning |
-|------|-------|---------|
-| **S** | 80+ | Elite — best for critical tasks |
-| **A** | 65+ | Strong — reliable for most work |
-| **B** | 50+ | Decent — good for simple tasks |
-| **C** | 35+ | Weak — use as fallback only |
-| **D** | <35 | Avoid — not recommended |
+See [docs/rpc.md](docs/rpc.md) for the protocol.
 
 ---
 
-## Skills
-
-Phi Code ships with **12 built-in skills**:
+## Philosophy
 
-| Skill | Description |
-|-------|-------------|
-| api-design | REST API patterns, versioning, error handling |
-| coding-standards | Code quality, naming conventions, best practices |
-| database | Database design, queries, migrations, optimization |
-| devops | CI/CD pipelines, deployment, monitoring |
-| docker-ops | Docker containers, Compose, orchestration |
-| git-workflow | Branching, commits, merges, collaboration |
-| github | GitHub Actions, PRs, issues, releases |
-| performance | Profiling, optimization, caching |
-| prompt-architect | Crafting structured prompts for AI systems |
-| security | Vulnerability scanning, hardening |
-| self-improving | Learning from errors and corrections |
-| testing | Test strategy, unit/integration tests |
+Pi is aggressively extensible so it doesn't have to dictate your workflow. Features that other tools bake in can be built with [extensions](#extensions), [skills](#skills), or installed from third-party [pi packages](#pi-packages). This keeps the core minimal while letting you shape pi to fit how you work.
 
-Skills are loaded automatically when relevant. Invoke manually with `/skill:name`.
+**No MCP.** Build CLI tools with READMEs (see [Skills](#skills)), or build an extension that adds MCP support. [Why?](https://mariozechner.at/posts/2025-11-02-what-if-you-dont-need-mcp/)
 
-Add your own skills in `~/.phi/agent/skills/` or `.phi/skills/`.
+**No sub-agents.** There's many ways to do this. Spawn pi instances via tmux, or build your own with [extensions](#extensions), or install a package that does it your way.
 
----
+**No permission popups.** Run in a container, or build your own confirmation flow with [extensions](#extensions) inline with your environment and security requirements.
 
-## Extensions
+**No plan mode.** Write plans to files, or build it with [extensions](#extensions), or install a package.
 
-Phi Code ships with **9 extensions**:
+**No built-in to-dos.** They confuse models. Use a TODO.md file, or build your own with [extensions](#extensions).
 
-| Extension | What it adds |
-|-----------|-------------|
-| **init** | `/phi-init` wizard + `/api-key` management |
-| **orchestrator** | `/plan` and `/run` commands with parallel sub-agents |
-| **memory** | Persistent memory (notes, ontology, QMD search) |
-| **smart-router** | Automatic model routing by task type |
-| **skill-loader** | Dynamic skill scanning and loading |
-| **benchmark** | `/benchmark` for model testing |
-| **web-search** | `/search` and `/crawl` commands via Brave API |
-| **agents** | `/agents` command to list sub-agents |
+**No background bash.** Use tmux. Full observability, direct interaction.
 
-Extensions are TypeScript files loaded at runtime by [jiti](https://github.com/unjs/jiti). Add your own in `~/.phi/agent/extensions/`.
+Read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/) for the full rationale.
 
 ---
 
-## Configuration Files
+## CLI Reference
 
-All configuration lives in `~/.phi/agent/`:
+```bash
+pi [options] [@files...] [messages...]
+```
 
-| File | Purpose |
-|------|---------|
-| `models.json` | **API keys & custom providers** (created by `/phi-init` or `/api-key`) |
-| `routing.json` | Model assignments per task type |
-| `settings.json` | Pi settings (thinking level, compaction, etc.) |
-| `agents/*.md` | Sub-agent definitions |
-| `skills/*/SKILL.md` | Skill definitions |
-| `extensions/*.ts` | Extension files |
-| `AGENTS.md` | Global project instructions |
-| `keybindings.json` | Custom keyboard shortcuts |
+### Package Commands
 
-Memory lives in `~/.phi/memory/`:
+```bash
+pi install <source> [-l]     # Install package, -l for project-local
+pi remove <source> [-l]      # Remove package
+pi uninstall <source> [-l]   # Alias for remove
+pi update [source|self|pi]   # Update pi and packages (skips pinned packages)
+pi update --extensions       # Update packages only
+pi update --self             # Update pi only
+pi update --self --force     # Reinstall pi even if current
+pi update --extension <src>  # Update one package
+pi list                      # List installed packages
+pi config                    # Enable/disable package resources
+```
 
-| Path | Content |
-|------|---------|
-| `AGENTS.md` | Global memory / instructions |
-| `notes/` | Saved notes |
-| `ontology/` | Knowledge graph |
-| `qmd/` | Vector search index |
+### Modes
 
----
+| Flag | Description |
+|------|-------------|
+| (default) | Interactive mode |
+| `-p`, `--print` | Print response and exit |
+| `--mode json` | Output all events as JSON lines (see [docs/json.md](docs/json.md)) |
+| `--mode rpc` | RPC mode for process integration (see [docs/rpc.md](docs/rpc.md)) |
+| `--export <in> [out]` | Export session to HTML |
 
-## Keyboard Shortcuts
+In print mode, pi also reads piped stdin and merges it into the initial prompt:
 
-| Key | Action |
-|-----|--------|
-| **Ctrl+L** | Open model selector |
-| **Ctrl+P** | Cycle models forward |
-| **Shift+Ctrl+P** | Cycle models backward |
-| **Shift+Tab** | Cycle thinking level |
-| **Ctrl+O** | Collapse/expand tool output |
-| **Ctrl+T** | Collapse/expand thinking |
-| **Ctrl+G** | Open external editor |
-| **Escape** | Cancel/abort |
-| **Ctrl+C** | Clear editor |
-| **Ctrl+C twice** | Quit |
-| **Alt+Enter** | Queue follow-up message |
-
-Full list: `/hotkeys`
+```bash
+cat README.md | pi -p "Summarize this text"
+```
 
----
+### Model Options
 
-## Sessions
+| Option | Description |
+|--------|-------------|
+| `--provider <name>` | Provider (anthropic, openai, google, etc.) |
+| `--model <pattern>` | Model pattern or ID (supports `provider/id` and optional `:<thinking>`) |
+| `--api-key <key>` | API key (overrides env vars) |
+| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
+| `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |
+| `--list-models [search]` | List available models |
 
-Sessions auto-save to `~/.phi/agent/sessions/` as JSONL files with a tree structure.
+### Session Options
 
-```bash
-phi -c                  # Continue last session
-phi -r                  # Browse past sessions
-phi --no-session        # Ephemeral mode
-```
+| Option | Description |
+|--------|-------------|
+| `-c`, `--continue` | Continue most recent session |
+| `-r`, `--resume` | Browse and select session |
+| `--session <path\|id>` | Use specific session file or partial UUID |
+| `--fork <path\|id>` | Fork specific session file or partial UUID into a new session |
+| `--session-dir <dir>` | Custom session storage directory |
+| `--no-session` | Ephemeral mode (don't save) |
 
-**Branching:** Use `/tree` to navigate history and branch from any point.
-**Compaction:** Automatic context management when approaching limits.
-**Export:** `/export file.html` or `--export` flag.
-**Debug log:** `~/.phi/agent/phi-debug.log` (toggle with Ctrl+D).
+### Tool Options
 
----
+| Option | Description |
+|--------|-------------|
+| `--tools <list>`, `-t <list>` | Allowlist specific tool names across built-in, extension, and custom tools |
+| `--no-builtin-tools`, `-nbt` | Disable built-in tools by default but keep extension/custom tools enabled |
+| `--no-tools`, `-nt` | Disable all tools by default |
 
-## CLI Reference
+Available built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`
 
-```bash
-phi [options] [@files...] [messages...]
-```
+### Resource Options
+
+| Option | Description |
+|--------|-------------|
+| `-e`, `--extension <source>` | Load extension from path, npm, or git (repeatable) |
+| `--no-extensions` | Disable extension discovery |
+| `--skill <path>` | Load skill (repeatable) |
+| `--no-skills` | Disable skill discovery |
+| `--prompt-template <path>` | Load prompt template (repeatable) |
+| `--no-prompt-templates` | Disable prompt template discovery |
+| `--theme <path>` | Load theme (repeatable) |
+| `--no-themes` | Disable theme discovery |
+| `--no-context-files`, `-nc` | Disable AGENTS.md and CLAUDE.md context file discovery |
+
+Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings.json (e.g., `--no-extensions -e ./my-ext.ts`).
+
+### Other Options
 
 | Option | Description |
 |--------|-------------|
-| `--provider <name>` | Provider name |
-| `--model <pattern>` | Model pattern or ID |
-| `--api-key <key>` | API key (session only) |
-| `--thinking <level>` | off, minimal, low, medium, high, xhigh |
-| `-c`, `--continue` | Continue last session |
-| `-r`, `--resume` | Browse sessions |
-| `-p`, `--print` | Print mode (non-interactive) |
-| `--no-session` | Don't save session |
-| `--verbose` | Verbose startup |
+| `--system-prompt <text>` | Replace default prompt (context files and skills still appended) |
+| `--append-system-prompt <text>` | Append to system prompt |
+| `--verbose` | Force verbose startup |
+| `-h`, `--help` | Show help |
 | `-v`, `--version` | Show version |
 
-Platform notes: [Windows](docs/windows.md) | [Termux](docs/termux.md) | [tmux](docs/tmux.md)
+### File Arguments
 
----
+Prefix files with `@` to include in the message:
 
-## Philosophy
+```bash
+pi @prompt.md "Answer this"
+pi -p @screenshot.png "What's in this image?"
+pi @code.ts @test.ts "Review these files"
+```
+
+### Examples
+
+```bash
+# Interactive with initial prompt
+pi "List all .ts files in src/"
+
+# Non-interactive
+pi -p "Summarize this codebase"
+
+# Non-interactive with piped stdin
+cat README.md | pi -p "Summarize this text"
 
-Phi Code follows Pi's philosophy of **aggressive extensibility** while adding the features serious developers need out of the box:
+# Different model
+pi --provider openai --model gpt-4o "Help me refactor"
 
-- **Memory matters.** Context across sessions shouldn't require manual copy-paste.
-- **Sub-agents work.** The right agent for the right task, running in parallel.
-- **Routing saves money.** Don't use your most expensive model for `ls`.
-- **Setup should be easy.** `/phi-init` → pick provider → paste key → done.
-- **Provider-neutral.** Your choice of LLM. No vendor lock-in.
+# Model with provider prefix (no --provider needed)
+pi --model openai/gpt-4o "Help me refactor"
 
-Built on [Pi](https://github.com/badlogic/pi-mono) by [Mario Zechner](https://github.com/badlogic). Everything Phi adds is through Pi's extension system — 2 lines changed in core.
+# Model with thinking level shorthand
+pi --model sonnet:high "Solve this complex problem"
+
+# Limit model cycling
+pi --models "claude-*,gpt-4o"
+
+# Read-only mode
+pi --tools read,grep,find,ls -p "Review the code"
+
+# High thinking level
+pi --thinking high "Solve this complex problem"
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PI_CODING_AGENT_DIR` | Override config directory (default: `~/.pi/agent`) |
+| `PI_CODING_AGENT_SESSION_DIR` | Override session storage directory (overridden by `--session-dir`) |
+| `PI_PACKAGE_DIR` | Override package directory (useful for Nix/Guix where store paths tokenize poorly) |
+| `PI_OFFLINE` | Disable startup network operations, including update checks, package update checks, and install/update telemetry |
+| `PI_SKIP_VERSION_CHECK` | Skip the Pi version update check at startup. This prevents the `pi.dev` latest-version request |
+| `PI_TELEMETRY` | Override install/update telemetry. Use `1`/`true`/`yes` to enable or `0`/`false`/`no` to disable. This does not disable update checks |
+| `PI_CACHE_RETENTION` | Set to `long` for extended prompt cache (Anthropic: 1h, OpenAI: 24h) |
+| `VISUAL`, `EDITOR` | External editor for Ctrl+G |
 
 ---
 
-## Credits
+## Contributing & Development
 
-- **[Pi](https://github.com/badlogic/pi-mono)** by Mario Zechner — the foundation
-- **[sigma-memory](https://www.npmjs.com/package/sigma-memory)** — persistent memory system
-- **[sigma-agents](https://www.npmjs.com/package/sigma-agents)** — sub-agent routing
-- **[sigma-skills](https://www.npmjs.com/package/sigma-skills)** — skill scanning and loading
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines and [docs/development.md](docs/development.md) for setup, forking, and debugging.
 
 ---
 
 ## License
 
 MIT
+
+## See Also
+
+- [@earendil-works/pi-ai](https://www.npmjs.com/package/@earendil-works/pi-ai): Core LLM toolkit
+- [@earendil-works/pi-agent-core](https://www.npmjs.com/package/@earendil-works/pi-agent-core): Agent framework
+- [@earendil-works/pi-tui](https://www.npmjs.com/package/@earendil-works/pi-tui): Terminal UI components