Pi 1.0: Codemode, Native MCP & Durable Execution for AI Agents

Earendil released Pi 1.0 on October 1, 2026, marking a milestone for the terminal-based agent harness. The release consolidates features from v0.99.0 (September 29) and earlier versions into a stable baseline, while launching Pi Durable as a separate experimental framework for long-running, multi-session agents.

Version Composition

Pi 1.0 spans three temporal layers:

Pre-1.0 : Anthropic cache warming (since v0.87.0) to reduce cache maintenance cost in long sessions.

v0.99.0 : Introduced Codemode, native MCP, tool_search, virtual models, Jev classifier, and new system theme — establishing tool orchestration, discovery, and model routing mechanisms.

v1.0.0 : Default full-screen TUI, Codemode prompt reduction (~40% smaller, from ~5,300 to ~3,300 tokens), image generation entry point, and MCP OAuth hardening.

Concurrent package : Pi Durable for persistence, multi-session concurrency, and crash recovery.

Codemode: JavaScript Orchestration in a QuickJS Sandbox

Codemode lets the model generate JavaScript that runs inside a QuickJS sandbox (no Node APIs, filesystem, network, or timers). All external access goes through registered tools and models interfaces. Scripts can call tools serially or in parallel, filter/sort/aggregate results, and only the final script output enters the main model context.

Resource limits (documented):

VM memory cap: 256 MB

Default output cap: 10,000 tokens

Text/base64 image size thresholds cause script failure if exceeded

Total text(), image(), and console calls capped at 100,000

Tool calls produce real side effects; script failure does not roll back completed calls. Codemode provides controlled execution boundaries, not transactions.

Why code orchestration? Traditional function calling loops accumulate intermediate results and model round-trips. Codemode moves loops, concurrency, and data wrangling into the script. Example: one script spawns four workers, fetches comments for a batch of issues, calls a classifier model, and aggregates results.

Official demo uses Linear MCP with Jev (TypeSafe's classifier) to process 167 open issues. Jev receives structured state and classification criteria via models.classify(), returning category, probability, and confidence — no explanatory text.

Prompt Reduction & Error Recovery (v1.0.0)

Default config (default tools, Codemode, GPT-5.6) cut single-request prompt from ~5,300 to ~3,300 tokens (~40% reduction) via:

Codemode description lists only script globals

Full models API loaded on demand

Tool descriptions keep only call signature and return structure

Runtime errors now include model-facing fix hints: typoed tool names suggest similar names; models.classify() and models.generateImages() parameter errors return expected structure; unknown models prompt to query available models first.

Migration: old scripts using typeof tools.name must change to "name" in tools.

MCP Moves to Core

Pi previously supported MCP via extensions. Earendil made it a built-in extension for three reasons:

MCP improved after a year of evolution.

Combined with Codemode, tools can be composed and filtered like shell pipelines.

Pi wants to shape MCP server/usage patterns for small harnesses.

Tool metadata remains an engineering concern; extensions can add metadata via supplementary interfaces. The decision reflects protocol maturity, Codemode composability, and ecosystem participation.

MCP Return Structure & Composability

Earendil's main reservation: some MCP servers target harnesses that dump all tools into context and return text to save server tokens. Text results suit direct model consumption but hinder reliable field filtering, joins, and batch processing in scripts.

Pi advocates MCP closer to OpenAPI with intelligent tool discovery: tools should return structured data with accurate names, descriptions, and docs for model discovery. This is Earendil's design stance, not the MCP spec.

Tool Exposure & Discovery

v0.99.0 defined five exposure modes for extension tools: direct: Declared to model immediately; also callable by other tools model-only: Declared to model only; cannot be nested by Codemode codemode: Not declared to model; callable by Codemode scripts deferred: Initially hidden; loaded for next model call after tool_search discovery hidden: Registered but inaccessible

MCP servers use four modes (no model-only), defaulting to codemode: codemode: Not in model's tool declaration nor inlined in Codemode description; scripts discover via searchTools(), describeTool(), describeNamespace(), or ALL_TOOLS. deferred: Loaded by tool_search. direct: Declared to model and allowed for Codemode. hidden: Server/tool stays inaccessible. toolExposure overrides server-level settings per tool name or wildcard. Example: queries direct, regular tools codemode, deletions hidden.

With default codemode exposure, Pi auto-activates Codemode. Without MCP, enable via config:

{
  "defaultTools": ["+codemode"]
}

Or launch with pi --tools +codemode. deferred exposure auto-activates tool_search.

MCP Config & OAuth (v1.0.0 Fixes)

Transport/config/cli from v0.99.0: stdio and Streamable HTTP. User servers in ~/.pi/agent/mcp.json, project servers in .pi/mcp.json (read after trust). Extensions can call pi.registerMcpServer(). Management via /mcp and CLI: pi mcp add|remove|list|login|logout.

v1.0.0 OAuth fixes:

Credentials isolated by server name + URL (same URL, different accounts).

Validate RFC 9207 iss in auth response; reject mismatched issuer.

New oauth.authServerMetadataUrl to override broken/missing discovery.

Step-up login preserves existing scopes.

Fix login failures from empty-string or null optional fields.

Old URL-only credentials migrate to first server using that URL; verify account associations after upgrade.

Model & Session Capabilities

Deferred Tool Loading

When tool count is high, Pi withholds full schemas until tool_search finds matches, then loads for next model call. v1.0.0 fixed a resume/reload bug: MCP tools loaded via tool_search could be lost due to server reconnect order; now restored before next model request.

Mid-Session System Prompt & Tool Changes

Pi stores initial system prompt and tool set in session log, appending changes before next model request. For providers lacking native support, Pi sends full session checkpoint (may invalidate prompt cache). Extensions can adjust system prompt, active tools, model, or reasoning level mid-session while keeping recoverable history.

Virtual Models

Extensions register virtual models via pi.registerVirtualModel(), selecting actual model and reasoning level per request. Example: Claude Opus plans, GPT implements, Jev decides phase transitions. Footer shows routed physical model; /session tallies cost per physical model. Routing logic lives in the extension.

Image Generation

v0.99.0 added image generation to ModelRuntime. v1.0.0 exposes models.generateImages() to Codemode. Scripts call image models with current session credentials, attach results via image() to output; usage counted in session cost.

Anthropic Cache Warming

Not new in 1.0.0. v0.87.0 fixed idle prompt-cache warming. Pi 1.0 release notes list cache warming for Anthropic models as a 1.0 capability but provide no new benchmarks.

Terminal UI Updates

Default Full-Screen TUI

Pi 1.0 uses full-screen TUI based on terminal alternate buffer; Pi manages scrolling/redraw. Exiting loses native scrollback. Revert via config "tuiMode": "regular" or pi --tui-mode regular.

New Theme & Fixes

v0.99.0 introduced system theme reading terminal foreground/background/ANSI palette and regenerating on light/dark switch. v1.0.0 adds: quietStartup: "header" shows only version and key hints

Fix Apple Terminal startup flag gap

Fix full-screen selection and search highlight color bleed

Fix oversaturated muted palettes

Fix slash-command completion when input starts with whitespace

Reduce heap memory for long model replies in session log to ~1/5 previous

Pi Durable: Persistent, Multi-Session, Recoverable Agents

Separate experimental package ( @earendil-works/pi-durable + pi-ai + chord). Models model requests, tool calls, compression as tasks; persists session state.

Storage & Recovery

Built-in memory, SQLite, JSONL backends. SQLite/JSONL run without Node APIs (adapters for Bun, Cloudflare Durable Objects). Each task writes checkpoint before advancing. On restart, new harness opens same storage and resumes unfinished work:

Interrupted model requests resent; saved partial response marked aborted. replay: "safe" tools re-executed.

Other tools not auto-replayed; model receives interruption result. requestId (Pi Durable) / operationId (Cloudflare PiHarness) deduplicate retries. External side effects still need tool-level idempotency.

Multi-Session & Context Compression

One harness runs multiple concurrent sessions. New sessions fork from a point in another session's history, inheriting prior context. Each session stores own model, reasoning level, extensions, tool set, extra instructions, working directory. Review agents can use cheaper models, read-only tools, separate code checkouts.

When context nears model limit, Pi Durable runs background compression task, writes summary at next turn boundary; original messages remain in storage.

Cloudflare PiHarness

Runs Pi Durable in Durable Objects. Lifecycle capability provides SQLite, persistent task queue, wakeups. Object evicted mid-execution → alarm restarts object → Pi resumes from checkpoint.

Current Cloudflare limitations:

No tool-call approval/permission step.

Event stream cannot resume from cursor; must refetch snapshot.

Single alarm invocation max 15 minutes; long model streams may truncate.

Background task completion detected with up to 30-second heartbeat delay.

Cannot delete sessions.

Thus Pi Durable sessions can have different tool sets, but framework lacks approval layer. Sensitive writes (deploy, payments) need control in tool implementation or host app.

Install & Upgrade

macOS/Linux: curl -fsSL https://pi.dev/install.sh | sh Windows: powershell -c "irm https://pi.dev/install.ps1 | iex" Pi Durable:

npm install @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord

Upgrade checklist:

Set tuiMode: "regular" if native scrollback needed.

Change typeof tools.name → "name" in tools in Codemode scripts.

Always pass both --provider and --model; 1.0.0 errors if model omitted.

Verify migrated MCP credentials map to correct accounts.

Test resume, /reload, MCP reconnect, tool interruption workflows.

Treat Pi Durable + Cloudflare PiHarness as experimental dependencies.

Evaluation Checklist for Adoption

Pi 1.0 focuses on tool orchestration and discovery. Validate against real workloads:

Tool count > dozens: compare direct, deferred, codemode prompt overhead and discovery accuracy.

MCP returns structured data: verify Codemode filtering/aggregation logic.

Local/small models: test script generation and tool selection reliability.

Sensitive writes: check hidden, tool annotations, host permission controls.

Session recovery dependency: test /reload, process exit, MCP reconnect, tool interruption.

Pi Durable: verify non-replayable tool recovery paths and external idempotency.

Pi 1.0 does not bundle all agent capabilities into one framework. It hardens the tool layer for terminal coding agents while delegating persistence, multi-session, and fault tolerance to Pi Durable.