open-multi-agent-kit 0.78.8 → 0.79.1

package/README.md

@@ -1,393 +1,667 @@
 <p align="center">
-  <img src="readmeasset/omk-control.webp" alt="OMK//CONTROL Night City Ops Console for routing agents, evidence gates, telemetry, MCP scope, and operator control" width="100%" />
+  <a href="https://pi.dev">
+    <img alt="pi logo" src="https://pi.dev/logo-auto.svg" width="128">
+  </a>
 </p>
-
-<h1 align="center">OMK</h1>
-
 <p align="center">
-  <strong>OMK//CONTROL — provider-neutral multi-agent control plane for coding workflows.</strong>
+  <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">
-  Models execute. OMK routes, verifies, measures, and controls.
+  <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>
 
-<p align="center">
-  <a href="https://www.npmjs.com/package/open-multi-agent-kit"><img alt="npm version" src="https://img.shields.io/npm/v/open-multi-agent-kit?color=00D6FF"></a>
-  <a href="https://www.npmjs.com/package/open-multi-agent-kit"><img alt="npm package" src="https://img.shields.io/badge/package-open--multi--agent--kit-FF47B2"></a>
-  <a href="docs/versioning.md"><img alt="runtime contract" src="https://img.shields.io/badge/contract-v1.2_pre--1.0-9D4EDD"></a>
-  <a href="https://github.com/dmae97/open-multi-agent-kit/blob/main/proof/PROOF_INDEX.md"><img alt="proof check" src="https://img.shields.io/badge/proof--check-source-00FFC2"></a>
-  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-blue.svg"></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).
 
-<p align="center">
-  <a href="#install">Install</a> ·
-  <a href="#quick-start">Quick start</a> ·
-  <a href="#who-is-this-for">Who is this for?</a> ·
-  <a href="#current-runtime-algorithm">Runtime algorithm</a> ·
-  <a href="docs/getting-started.md">Docs</a> ·
-  <a href="readmeasset/ASSET_INDEX.md">Visual assets</a>
-</p>
+---
+
+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.
+
+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.
+
+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.
+
+## 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.
 
-`OMK` (`omk`) turns a coding goal into a bounded, evidence-gated agent run.
+For the full explanation, see [this post on X](https://x.com/badlogicgames/status/2037811643774652911).
 
-Use OMK when one coding agent is not enough: route Codex, OpenCode, Kimi, DeepSeek, Qwen, OpenRouter, and local runtimes through one evidence-gated control loop.
+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`.
 
-## Who is this for?
+You can also watch [this video](https://x.com/badlogicgames/status/2041151967695634619), where I show how I publish my `pi-mono` sessions.
 
-- Developers running multiple coding agents from the terminal.
-- Teams that need MCP-scoped agent execution instead of unrestricted tool access.
-- Agent builders who want routing, fallback, evidence gates, telemetry, and replay.
+I regularly publish my own `pi-mono` work sessions here:
 
-> Current package source target: `open-multi-agent-kit@0.78.8`.
-> Public package name: `open-multi-agent-kit` (`@omk/cli` is not the active npm package).
-> Runtime contract family: `v1.2` (contract family, not a stable npm `1.x` release).
-> Release channel: `pre-1.0`.
-> See [versioning](docs/versioning.md) and [provider maturity](docs/provider-maturity.md).
+- [badlogicgames/pi-mono on Hugging Face](https://huggingface.co/datasets/badlogicgames/pi-mono)
 
-## Quickstart (3 minutes)
+## Table of Contents
 
-A beginner reads this, runs four commands, and reaches an initialized OMK chat/doctor flow.
+- [Quick Start](#quick-start)
+- [Providers & Models](#providers--models)
+- [Interactive Mode](#interactive-mode)
+  - [Editor](#editor)
+  - [Commands](#commands)
+  - [Keyboard Shortcuts](#keyboard-shortcuts)
+  - [Message Queue](#message-queue)
+- [Sessions](#sessions)
+  - [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)
+- [CLI Reference](#cli-reference)
+
+---
+
+## Quick Start
 
 ```bash
-npm i -g open-multi-agent-kit
-omk init
-omk doctor
-omk chat
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent
 ```
 
-## Examples for agent tooling lists
+`--ignore-scripts` disables dependency lifecycle scripts during install. Pi does not require install scripts for normal npm installs.
 
-- [Codex MCP evidence run](https://github.com/dmae97/open-multi-agent-kit/tree/main/examples/codex-mcp-evidence-run): project-scoped MCP setup plus evidence-gated DAG dry run.
-- [Provider fallback](https://github.com/dmae97/open-multi-agent-kit/tree/main/examples/provider-fallback): `--provider auto` routing with parallel worker planning.
+Installer alternative:
 
-## Current release reality
+```bash
+curl -fsSL https://pi.dev/install.sh | sh
+```
 
-- The public npm line is `open-multi-agent-kit@0.78.x`. The source target is `open-multi-agent-kit@0.78.8`;
-  treat npm `latest` as release-truthful only after the tagged release workflow and registry verification both pass.
-- The `v1.2` label in docs is a runtime contract family for the source tree, not a claim that
-  an npm `1.2.x` stable release exists.
-- Provider support is intentionally uneven: Kimi remains the most mature authority path;
-  Codex/OpenCode/CommandCode depend on local CLIs; MiMo/DeepSeek/Qwen/OpenRouter/local LLM
-  lanes are scoped by the provider-maturity contract.
-- Safety and evidence claims apply to the exact adapter, command, and verification gate that
-  produced them.
-- Regression Proof Matrix is a release-defense coverage gate, not a stable-release claim.
-  Stable promotion still requires full tests, live provider maturity data, and a minimal verified demo pass.
+Authenticate with an API key:
 
-## Why OMK
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+pi
+```
 
-Most coding agents optimize for a single prompt/result loop. OMK wraps agent execution with a control-plane algorithm:
+Or use your existing subscription:
 
-- compile the user goal into a DAG coordinator turn;
-- inject only scoped MCP servers, skills, hooks, memory, and tools;
-- classify task intent and route to compatible runtime adapters;
-- execute with timeout, approval, sandbox, and fallback metadata;
-- require evidence before completion claims;
-- preserve run artifacts for replay, inspection, and audit.
+```bash
+pi
+/login  # Then select provider
+```
 
-## OMK//CONTROL visual console
+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).
+
+**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)
+
+---
+
+## Providers & Models
+
+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
+- Ant Ling
+- OpenAI
+- Azure OpenAI
+- DeepSeek
+- NVIDIA NIM
+- Google Gemini
+- Google Vertex
+- Amazon Bedrock
+- Mistral
+- Groq
+- Cerebras
+- Cloudflare AI Gateway
+- Cloudflare Workers AI
+- xAI
+- OpenRouter
+- Vercel AI Gateway
+- ZAI
+- ZAI Coding Plan (China)
+- 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)
 
-The GitHub visual set presents OMK as a Night City Ops Console: route status, DAG lanes, provider fallback, scoped MCP, evidence gates, replayable run telemetry, and publish-time assertions. Assets are provenance-covered in [`readmeasset/ASSET_PROVENANCE.md`](readmeasset/ASSET_PROVENANCE.md).
+See [docs/providers.md](docs/providers.md) for detailed setup instructions.
 
-<p align="center">
-  <img src="readmeasset/omk_tui.png" alt="OMK//CONTROL terminal dashboard — live DAG lanes, provider routing, MCP health, evidence gates, and telemetry in Night City Ops Console style" width="100%" />
-</p>
+**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).
 
-| Operator TUI                                                                                                                                                                                            | Runtime flow                                                                                                                                                                                                                            |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <img src="readmeasset/omk-tui-0.78.0.webp" alt="OMK//CONTROL TUI for OMK 0.78.0 showing Codex App OAuth routing, GPT Image 2 asset lane, DAG lanes, scoped MCP, and evidence gates" /> | <img src="readmeasset/omk-runtime-flow-0.78.0.webp" alt="OMK 0.78.0 runtime flow diagram: user goal, intent classifier, DAG compiler, runtime router, parallel workers, evidence bundle, verify gate, and merge replay inspect loop" /> |
+---
 
-| Install lane                                                                     | Provider router                                                                       | Evidence gate                                                                     |
-| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| <img src="readmeasset/omk-install-card.png" alt="OMK install quickstart card" /> | <img src="readmeasset/omk-provider-router-card.png" alt="OMK provider router card" /> | <img src="readmeasset/omk-evidence-gate-card.png" alt="OMK evidence gate card" /> |
+## Interactive Mode
 
-<p align="center">
-  <img src="readmeasset/omk-core-loop.svg" alt="OMK core loop: goal to DAG plan to evidence to verify to replay" width="100%" />
-</p>
+<p align="center"><img src="docs/images/interactive-mode.png" alt="Interactive Mode" width="600"></p>
 
-| Control surfaces | Release assertions |
-| ---------------- | ------------------ |
-| <img src="readmeasset/omk-control-surfaces.svg" alt="OMK control surfaces: CLI, provider router, MCP scope, evidence gate, replay ledger, and package audit" /> | <img src="readmeasset/omk-release-assertions.svg" alt="OMK release assertions: package name, CLI bins, release gates, package-safe exclusions, and registry verification" /> |
+The interface from top to bottom:
 
-## Install
+- **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
 
-Requires Node.js `>=20` and npm `>=10`. The [3-minute route](#quickstart-3-minutes) uses the global install; these are the alternatives:
+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.
 
-Project/local install:
+### Editor
 
-```bash
-npm i open-multi-agent-kit
-npx omk --help
-```
+| 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 |
 
-No install:
+Standard editing keybindings for delete word, undo, etc. See [docs/keybindings.md](docs/keybindings.md).
 
-```bash
-npx -p open-multi-agent-kit omk doctor
-```
+### Commands
+
+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`.
+
+| 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:**
+
+| 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 |
+
+### 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
 
-## Quick start
+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.
 
-The [3-minute route](#quickstart-3-minutes) is the canonical path. Beyond it, add provider auth and orchestration:
+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
+
+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.
+
+### Management
+
+Sessions auto-save to `~/.pi/agent/sessions/` organized by working directory.
 
 ```bash
-omk codex auth --choice plus-pro # optional; requires official Codex app/CLI login
-omk chat --provider auto --mode agent
-omk orchestrate "ship feature" --workers 4 --dry-run
+pi -c                  # Continue most recent session
+pi -r                  # Browse and select from past sessions
+pi --no-session        # Ephemeral mode (don't save)
+pi --name "my task"    # Set session display name at startup
+pi --session <path|id> # Use specific session file or ID
+pi --fork <path|id>    # Fork specific session file or ID into a new session
 ```
 
-## Current runtime algorithm
+Use `/session` in interactive mode to see the current session ID before reusing it with `--session <id>` or `--fork <id>`.
 
-The canonical algorithm definitions live in [Native Root Runtime Algorithms](docs/native-root-runtime-algorithms.md). README summary:
+### Branching
 
-### 1. Native root turn execution
+**`/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.
 
-```text
-Read user input
-  → dispatch slash commands locally
-  → build scoped MCP/skills/hooks capability injection
-  → build prompt envelope
-  → materialize a DAG coordinator node
-  → run selected runtime with timeout/abort handling
-  → stream output, sync TODOs, attach evidence
-```
+<p align="center"><img src="docs/images/tree-view.png" alt="Tree View" width="600"></p>
 
-This is the interactive root loop used by `omk chat`. It treats shell exits, slash commands, prompt envelopes, TODO sync, and recent output as controlled runtime state instead of loose chat text.
+- 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
 
-### 2. Native root turn node construction
+**`/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.
 
-```text
-User prompt
-  → infer risk: read | write | shell | merge
-  → normalize scoped capabilities
-  → choose provider-neutral routing policy
-  → attach approval/sandbox metadata
-  → produce coordinator DAG node
-```
+**`/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.
 
-Read-only turns stay read-only. Write, shell, and merge turns get explicit capability metadata. DeepSeek-style advisory lanes are kept read/review when the risk is not safe for write authority.
+**`--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.
 
-### 3. Runtime-backed task runner
+### Compaction
 
-```text
-DAG node
-  → run state
-  → context capsule
-  → provider-neutral AgentTask
-  → RuntimeRouter.execute(task)
-  → TaskResult with selected runtime + fallback chain
-```
+Long sessions can exhaust context windows. Compaction summarizes older messages while keeping recent ones.
 
-OMK converts DAG context into an adapter-neutral task so Codex, MiMo, Kimi API/print lanes, DeepSeek, Qwen, OpenRouter, local adapters, or future runtimes can participate through the same contract when configured. That contract does not imply equal write/merge authority for every adapter.
+**Manual:** `/compact` or `/compact <custom instructions>`
 
-### 4. Intent-aware runtime routing and fallback
+**Automatic:** Enabled by default. Triggers on context overflow (recovers and retries) or when approaching the limit (proactive). Configure via `/settings` or `settings.json`.
 
-```text
-Classify intent
-  → filter compatible runtimes
-  → score by quality, evidence pass rate, and recent failures
-  → execute best runtime
-  → fallback in ranked order when a runtime fails
-  → record selected runtime, intent, scores, and fallback chain
-```
+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.
 
-Provider routing is evidence-aware, not just provider-name matching. Failed or low-evidence lanes are penalized; compatible healthy lanes can take over.
+---
 
-### 5. Secure worker transport and scoped environment
+## Settings
 
-```text
-Worker prompt
-  → stdin transport where supported, not process argv
-  → scoped agent file when needed
-  → sanitized child environment
-  → OMK_RUN_ID / OMK_NODE_ID / OMK_NODE_ROLE metadata
-```
+Use `/settings` to modify common options, or edit JSON files directly:
+
+| Location | Scope |
+|----------|-------|
+| `~/.pi/agent/settings.json` | Global (all projects) |
+| `.pi/settings.json` | Project (overrides global) |
+
+See [docs/settings.md](docs/settings.md) for all options.
+
+### 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`. This setting also controls optional provider attribution headers for OpenRouter, Cloudflare, and direct NVIDIA NIM requests. 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.
+
+---
+
+## Context Files
 
-Kimi worker prompts use stdin with `--input-format text` where that adapter path applies. All worker environment claims are scoped to the exact adapter and evidence gates; private prompt envelopes and run artifacts remain trusted local data.
+Pi loads `AGENTS.md` (or `CLAUDE.md`) at startup from:
+- `~/.pi/agent/AGENTS.md` (global)
+- Parent directories (walking up from cwd)
+- Current directory
 
-## Core loop
+Use for project instructions, conventions, common commands. All matching files are concatenated.
 
-```text
-Goal → DAG plan → parallel lanes → evidence bundle → verify gate → merge / replay / inspect
+Disable context file loading with `--no-context-files` (or `-nc`).
+
+### 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`.
+
+---
+
+## Customization
+
+### Prompt Templates
+
+Reusable prompts as Markdown files. Type `/name` to expand.
+
+```markdown
+<!-- ~/.pi/agent/prompts/review.md -->
+Review this code for bugs, security issues, and performance problems.
+Focus on: {{focus}}
 ```
 
-## Goal lifecycle
+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).
 
-`omk goal` turns a raw goal into a planned, evidence-gated run. The **OMK Deep Interview** is an uncertainty reducer that clarifies the goal before planning, so the DAG is compiled from a structured spec instead of a vague prompt.
+### Skills
 
-Recommended flow:
+On-demand capability packages following the [Agent Skills standard](https://agentskills.io). Invoke via `/skill:name` or let the agent load them automatically.
 
-```bash
-omk goal interview "<raw goal>" --depth deep --write-spec
-omk goal plan <goal-id>
-omk goal run <goal-id> --provider auto --approval-policy interactive
-omk goal verify <goal-id>
+```markdown
+<!-- ~/.pi/agent/skills/my-skill/SKILL.md -->
+# My Skill
+Use this skill when the user asks about X.
+
+## Steps
+1. Do this
+2. Then that
 ```
 
-### `omk goal interview [input]`
+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).
+
+### Extensions
 
-Runs a deterministic deep interview that scores goal ambiguity (`0..1`), ranks targeted questions, assimilates answers into a structured spec delta, computes a completeness score, and (with `--write-spec`) creates or updates a `GoalSpec`. Question ranking is deterministic:
+<p align="center"><img src="docs/images/doom-extension.png" alt="Doom Extension" width="600"></p>
 
-```text
-score = informationGain*0.35 + riskReduction*0.25 + dagImpact*0.20 + evidenceImpact*0.15 - userCost*0.05
+TypeScript modules that extend pi with custom tools, commands, keyboard shortcuts, event handlers, and UI components.
+
+```typescript
+export default function (pi: ExtensionAPI) {
+  pi.registerTool({ name: "deploy", ... });
+  pi.registerCommand("stats", { ... });
+  pi.on("tool_call", async (event, ctx) => { ... });
+}
 ```
 
-| Option                     | Purpose                                                         |
-| -------------------------- | -------------------------------------------------------------- |
-| `--goal-id <id>`           | Target an existing goal.                                       |
-| `--mode <create\|refine>`  | Create a new spec or refine an existing one.                   |
-| `--depth <light\|standard\|deep>` | Interview depth; omit to auto-select by ambiguity.      |
-| `--max-questions <n>`      | Cap the number of ranked questions.                           |
-| `--answers <file>`         | Supply answers non-interactively.                             |
-| `--write-spec`             | Persist the spec delta into a `GoalSpec`.                     |
-| `--json`                   | Emit the `omk.interview.v1` JSON contract.                    |
+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()`.
+
+**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
 
-### `omk goal refine <goal-id>`
+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/).
 
-Applies the latest interview spec delta to a goal and optionally replans.
+### Themes
 
-| Option                  | Purpose                                          |
-| ----------------------- | ------------------------------------------------ |
-| `--from-interview <id>` | Source interview session (default: latest).      |
-| `--plan`                | Replan the goal after applying the delta.         |
-| `--json`                | Emit machine-readable output.                     |
+Built-in: `dark`, `light`. Themes hot-reload: modify the active theme file and pi immediately applies changes.
 
-Answers file format (`--answers answers.json`):
+Place in `~/.pi/agent/themes/`, `.pi/themes/`, or a [pi package](#pi-packages) to share with others. See [docs/themes.md](docs/themes.md).
+
+### Pi Packages
+
+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
+```
+
+Packages install to `~/.pi/agent/git/` (git) or `~/.pi/agent/npm/` (npm). Use `-l` for project-local installs (`.pi/git/`, `.pi/npm/`). Git `@ref` values are pinned tags or commits; pinned packages are skipped by `pi update`, so use `pi install git:host/user/repo@new-ref` to move an existing package to a new ref. 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
 {
-  "answers": [
-    { "questionId": "q-success-criteria", "answer": "..." }
-  ]
+  "name": "my-pi-package",
+  "keywords": ["pi-package"],
+  "pi": {
+    "extensions": ["./extensions"],
+    "skills": ["./skills"],
+    "prompts": ["./prompts"],
+    "themes": ["./themes"]
+  }
 }
 ```
 
-Session artifacts (`interview.json`, `spec-delta.json`, `questions.md`, `answers.jsonl`, `interview-report.md`) are written under `.omk/goals/<goalId>/interviews/<sessionId>/`, or `.omk/interviews/<sessionId>/` before `--write-spec`.
+Without a `pi` manifest, pi auto-discovers from conventional directories (`extensions/`, `skills/`, `prompts/`, `themes/`).
+
+See [docs/packages.md](docs/packages.md).
 
-## What OMK controls
+---
 
-| Surface            | What OMK does                                                                                           |
-| ------------------ | ------------------------------------------------------------------------------------------------------- |
-| DAG orchestration  | Plans, routes, executes, merges, replays, and inspects agent work.                                      |
-| Evidence gates     | Requires command output, diff, artifact, metric, or review proof before “done”.                         |
-| Provider routing   | Selects compatible runtimes with intent, capability, evidence, and fallback metadata.                   |
-| MCP scope          | Keeps project MCP, skills, hooks, and graph memory scoped instead of importing global secrets silently. |
-| Worktree isolation | Keeps parallel lanes bounded, reviewable, and recoverable.                                              |
-| Operator telemetry | Exposes route, status, blockers, TODOs, run health, and evidence state through CLI/HUD/TUI surfaces.    |
-| Security boundary  | Sanitizes child env, protects secrets, and makes workspace-write routes explicit.                       |
+## Programmatic Usage
 
-## Provider lanes
+### SDK
 
-OMK is provider-neutral, but providers are not equally mature or equally authorized:
+```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?");
+```
 
-- **Kimi API / print lanes**: most mature authority path and compatibility fallback when configured.
-- **MiMo**: default/read-review-thinking path when configured; direct workspace-write authority is not claimed for the API runtime.
-- **Codex app / CLI OAuth lanes**: compatibility path through the official Codex CLI/app login; local CLI availability and policy decide what can run.
-- **OpenCode / CommandCode CLI lanes**: compatibility paths when the local CLI and auth are present.
-- **DeepSeek, Qwen, OpenRouter, local LLM adapters**: advisory/read/review/QA/research lanes unless a tested contract grants more authority.
-- **GPT Image 2 asset lane**: visual asset workflow only when explicitly selected and separately configured.
+For advanced multi-session runtime replacement, use `createAgentSessionRuntime()` and `AgentSessionRuntime`.
 
-See [provider maturity](docs/provider-maturity.md) before treating any non-Kimi lane as an authority/write/merge path.
+See [docs/sdk.md](docs/sdk.md) and [examples/sdk/](examples/sdk/).
 
-## Codex app / OAuth first
+### RPC Mode
 
-For Codex lanes, OMK delegates auth to the official Codex app/CLI and never reads or prints `~/.codex/auth.json` tokens.
+For non-Node.js integrations, use RPC mode over stdin/stdout:
 
 ```bash
-codex login
-omk codex auth --choice plus-pro --run
-omk provider doctor codex --soft
+pi --mode rpc
 ```
 
-Codex/ChatGPT OAuth is for Codex CLI sessions. `omk image generate/edit --model gpt-image-2` remains an OpenAI Images API call and requires a separate OpenAI Platform project API key. See [Codex OAuth setup](docs/codex-oauth-setup.md) and [OpenAI image keys](docs/openai-platform-image-keys.md).
+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.
 
-## CLI and package contract
+See [docs/rpc.md](docs/rpc.md) for the protocol.
 
-The npm package is intentionally package-safe:
+---
 
-| Contract          | Value                                                                                                                                                                                                                          |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Package           | [`open-multi-agent-kit`](https://www.npmjs.com/package/open-multi-agent-kit)                                                                                                                                                   |
-| Version           | `0.78.8`                                                                                                                                                                                                                       |
-| Runtime contract family | `v1.2`                                                                                                                                                                                                                         |
-| Bins              | `omk`, `omk-project-mcp`, `omk-acp`, `omk-mcp-host`                                                                                                                                                                            |
-| Packaged docs     | `README.md`, `docs/`, `SECURITY.md`, `ROADMAP.md`, `MATURITY.md`, `DESIGN.md`                                                                                                                                                  |
-| Packaged branding | Canonical hero/social/TUI/runtime images plus the curated derivative gallery documented in [`readmeasset/ASSET_INDEX.md`](readmeasset/ASSET_INDEX.md) and [`readmeasset/ASSET_PROVENANCE.md`](readmeasset/ASSET_PROVENANCE.md) |
-| Release assertions | README and package audit assert package name/version, required CLI bins, package-safe file set, local-state exclusions, proof metadata, and registry-verification wording. |
-| Excluded          | source-only tests, scripts, local state, logs, secrets, private runtime directories                                                                                                                                            |
+## Philosophy
 
-Release checks:
+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.
+
+**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/)
+
+**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.
+
+**No plan mode.** Write plans to files, or build it with [extensions](#extensions), or install a package.
+
+**No built-in to-dos.** They confuse models. Use a TODO.md file, or build your own with [extensions](#extensions).
+
+**No background bash.** Use tmux. Full observability, direct interaction.
+
+Read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/) for the full rationale.
+
+---
+
+## CLI Reference
 
 ```bash
-npm run version:check
-npm run proof:check
-npm run pack:dry
-npm run audit:package
+pi [options] [@files...] [messages...]
 ```
 
-What those checks assert before publish:
+### Package Commands
+
+```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
+```
 
-- `package.json` and `package-lock.json` agree on `open-multi-agent-kit` and the current package version.
-- The npm tarball exposes `omk`, `omk-project-mcp`, `omk-acp`, and `omk-mcp-host` from `dist/` with executable shebangs.
-- README/docs/changelog/release-truthfulness proof metadata mention the same package version and keep `v1.2` scoped to runtime contracts.
-- The packaged file set includes docs, templates, and provenance-covered README assets while excluding source, tests, local `.omk`/`.kimi` state, logs, tarballs, and secret-shaped files.
-- Published-version claims remain conditional until the tagged workflow and npm registry verification both pass.
+### Modes
 
-## Contract versions
+| 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 |
 
-Machine-readable contracts currently include:
+In print mode, pi also reads piped stdin and merges it into the initial prompt:
 
-- `omk.contract.v1`
-- `omk.evidence.v1`
-- `omk.decision.v1`
-- `omk.run-manifest.v1`
-- `omk.provider.v1`
-- `omk.version.v1`
-- `omk.proof-bundle.v1`
+```bash
+cat README.md | pi -p "Summarize this text"
+```
 
-Schemas live in the source-tree `schemas/` directory and are checked with:
+### Model Options
+
+| 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 |
+
+### Session Options
+
+| 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) |
+| `--name <name>`, `-n <name>` | Set session display name at startup |
+
+### Tool Options
+
+| Option | Description |
+|--------|-------------|
+| `--tools <list>`, `-t <list>` | Allowlist specific tool names across built-in, extension, and custom tools |
+| `--exclude-tools <list>`, `-xt <list>` | Disable 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 |
+
+Available built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`
+
+### 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 |
+|--------|-------------|
+| `--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 |
+
+### File Arguments
+
+Prefix files with `@` to include in the message:
 
 ```bash
-npm run schema:check
+pi @prompt.md "Answer this"
+pi -p @screenshot.png "What's in this image?"
+pi @code.ts @test.ts "Review these files"
 ```
 
-## Known implementation caveats
+### 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"
 
-The runtime algorithms are the current contract target, with adapter-specific hardening still tracked in docs and tests:
+# Named one-shot session
+pi --name "release audit" -p "Audit this repository"
 
-- `/provider` is restart-only in the native root loop.
-- `/model` is UX debt until live mutation or restart-only behavior is enforced consistently.
-- Approval and sandbox metadata are preserved in task contracts; enforcement depends on the adapter path.
-- Provider health probes do not yet uniformly separate binary/API presence, auth, model support, and quota state across every adapter.
-- Safety claims are scoped to exact adapter, command, evidence, and package-audit results.
+# Different model
+pi --provider openai --model gpt-4o "Help me refactor"
 
-## Brand system
+# Model with provider prefix (no --provider needed)
+pi --model openai/gpt-4o "Help me refactor"
 
-Public copy stays OMK-owned: **OMK//CONTROL**, **NEON GRID ONLINE**, route/evidence/loop/control language, and the **Night City Ops Console** palette. The README/NPM hero, social preview, TUI mock, runtime-flow diagram, and derivative gallery are package-safe brand assets with provenance in [`readmeasset/ASSET_PROVENANCE.md`](readmeasset/ASSET_PROVENANCE.md).
+# Model with thinking level shorthand
+pi --model sonnet:high "Solve this complex problem"
 
-## Docs
+# Limit model cycling
+pi --models "claude-*,gpt-4o"
 
-- [Getting started](docs/getting-started.md)
-- [Runtime versioning](docs/versioning.md)
-- [Provider maturity](docs/provider-maturity.md)
-- [Native root runtime algorithms](docs/native-root-runtime-algorithms.md)
-- [Codex OAuth setup](docs/codex-oauth-setup.md)
-- [Ouroboros integration](docs/integrations/ouroboros.md)
-- [Security policy](SECURITY.md)
+# Read-only mode
+pi --tools read,grep,find,ls -p "Review the code"
 
-## Security
+# Disable one extension or built-in tool while keeping the rest available
+pi --exclude-tools ask_question
 
-Safe by default: child env is sanitized, ambient secrets are dropped, and workspace-write routes require approval. OS-level sandboxing is planned, not claimed; see [SECURITY.md](SECURITY.md).
+# 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 and provider attribution headers. 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 |
 
-Safety checks run as pure TypeScript (no native/Rust build step). The former Rust `omk-safety` probe was retired; see [docs/adr/0001-no-native-rust-lane.md](docs/adr/0001-no-native-rust-lane.md).
+---
 
-## Links
+## Contributing & Development
 
-- GitHub: <https://github.com/dmae97/open-multi-agent-kit>
-- NPM: <https://www.npmjs.com/package/open-multi-agent-kit>
-- Releases: <https://github.com/dmae97/open-multi-agent-kit/releases>
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines and [docs/development.md](docs/development.md) for setup, forking, and debugging.
+
+---
 
 ## License
 
-[MIT](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