\n\nJensen Code 3.0.0 is a durable distributed autonomous agent runtime foundation. It retains the interactive coding harness while adding authoritative Missions, restart-safe execution, Scheduler/Assignment/Worker coordination, remote execution, capability routing, modern MCP, shared inference, logical subagents, durable orchestration, verification/completion authority, Governance/Budgets, and Jensen-owned process stewardship.\n\nThe persistent daemon/control plane, trusted remote clients, mobile and device capabilities, voice/STT/TTS, and ambient-assistant services are planned for later Jensen 3.x phases; they are not included in this release.\n\nJensen can be extended 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.\n\nPi ships with a canonical policy-bound subagent registry and Cavecrew runtime. The `subagent` extension resolves roles, models, tools, budgets, context packets, and output schemas through that registry; Cavecrew runs read-only investigators, a bounded planner, a transactional builder, and a read-only reviewer. User and workspace Markdown prompts cannot broaden runtime policy.\n\nPi 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.\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Providers & Models](#providers--models)\n- [Interactive Mode](#interactive-mode)\n - [Editor](#editor)\n - [Commands](#commands)\n - [Keyboard Shortcuts](#keyboard-shortcuts)\n - [Message Queue](#message-queue)\n- [Sessions](#sessions)\n - [Branching](#branching)\n - [Compaction](#compaction)\n- [Settings](#settings)\n- [Context Files](#context-files)\n- [Web Research](#web-research)\n- [Customization](#customization)\n - [Prompt Templates](#prompt-templates)\n - [Skills](#skills)\n - [Extensions](#extensions)\n - [Themes](#themes)\n - [Pi Packages](#pi-packages)\n- [Programmatic Usage](#programmatic-usage)\n- [Philosophy](#philosophy)\n- [CLI Reference](#cli-reference)\n\n---\n\n## Quick Start\n\nInstall or upgrade the public CLI with:\n\n```bash\nnpm install -g @apholdings/jensen-code@3.0.0\n```\n\nJensen 3.0.0 keeps the default user configuration under `~/.pi/agent` for\ncompatibility with existing sessions and provider settings. Mission,\norchestration, assignment, and Governance stores use their configured durable\nlocations; do not copy or edit those stores while a Jensen process owns them.\n\nAuthenticate with an API key:\n\n```bash\nexport ANTHROPIC_API_KEY=sk-ant-...\npi\n```\n\nOr use your existing subscription:\n\n```bash\npi\n/login # Then select provider\n```\n\nThen 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).\n\n**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)\n\n---\n\n## Providers & Models\n\nFor 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).\n\n**Subscriptions:**\n- Anthropic Claude Pro/Max\n- OpenAI ChatGPT Plus/Pro (Codex)\n- GitHub Copilot\n- Google Gemini CLI\n- Google Antigravity\n\n**API keys:**\n- Anthropic\n- OpenAI\n- Azure OpenAI\n- Google Gemini\n- Google Vertex\n- Amazon Bedrock\n- Mistral\n- Groq\n- Cerebras\n- xAI\n- OpenRouter\n- Vercel AI Gateway\n- ZAI\n- OpenCode Zen\n- OpenCode Go\n- Hugging Face\n- Kimi For Coding\n- MiniMax\n\nSee [docs/providers.md](docs/providers.md) for detailed setup instructions.\n\n**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).\n\n---\n\n## Interactive Mode\n\n
\n\nThe interface from top to bottom:\n\n- **Startup header** - Shows shortcuts (`/hotkeys` for all), loaded `JENSEN.md` context files, prompt templates, skills, and extensions\n- **Messages** - Your messages, assistant responses, tool calls and results, notifications, errors, and extension UI\n- **Editor** - Where you type; border color indicates thinking level\n- **Footer** - Working directory, session name, total token/cache usage, cost, context usage, current model\n\nThe 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.\n\n### Editor\n\n| Feature | How |\n|---------|-----|\n| File reference | Type `@` to fuzzy-search project files |\n| Path completion | Tab to complete paths |\n| Multi-line | Shift+Enter (or Ctrl+Enter on Windows Terminal) |\n| Images | Ctrl+V to paste (Alt+V on Windows), or drag onto terminal |\n| Bash commands | `!command` runs and sends output to LLM, `!!command` runs without sending |\n\nStandard editing keybindings for delete word, undo, etc. See [docs/keybindings.md](docs/keybindings.md).\n\n### Commands\n\nType `/` 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`.\n\n| Command | Description |\n|---------|-------------|\n| `/login`, `/logout` | OAuth authentication |\n| `/model` | Switch models |\n| `/scoped-models` | Enable/disable models for Ctrl+P cycling |\n| `/settings` | Thinking level, theme, message delivery, transport |\n| `/resume` | Pick from previous sessions |\n| `/new` | Start a new session |\n| `/name ` | Set session display name |\n| `/session` | Show session info (path, tokens, cost) |\n| `/tree` | Jump to any point in the session and continue from there |\n| `/fork` | Create a new session from the current branch |\n| `/compact [prompt]` | Manually compact context, optional custom instructions |\n| `/copy` | Copy last assistant message to clipboard |\n| `/export [file]` | Export session to HTML file |\n| `/share` | Upload as private GitHub gist with shareable HTML link |\n| `/reload` | Reload extensions, skills, prompts, context files (themes hot-reload automatically) |\n| `/hotkeys` | Show all keyboard shortcuts |\n| `/changelog` | Display version history |\n| `/quit`, `/exit` | Quit pi |\n\n### Keyboard Shortcuts\n\nSee `/hotkeys` for the full list. Customize via `~/.pi/agent/keybindings.json`. See [docs/keybindings.md](docs/keybindings.md).\n\n**Commonly used:**\n\n| Key | Action |\n|-----|--------|\n| Ctrl+C | Clear editor |\n| Ctrl+C twice | Quit |\n| Escape | Cancel/abort |\n| Escape twice | Open `/tree` |\n| Ctrl+L | Open model selector |\n| Ctrl+P / Shift+Ctrl+P | Cycle scoped models forward/backward |\n| Shift+Tab | Cycle thinking level |\n| Ctrl+O | Collapse/expand tool output |\n| Ctrl+T | Collapse/expand thinking blocks |\n\n### Message Queue\n\nSubmit messages while the agent is working:\n\n- **Enter** queues a *steering* message, delivered after current tool execution (interrupts remaining tools)\n- **Alt+Enter** queues a *follow-up* message, delivered only after the agent finishes all work\n- **Escape** aborts and restores queued messages to editor\n- **Alt+Up** retrieves queued messages back to editor\n\nOn 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.\n\nConfigure 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.\n\n---\n\n## Sessions\n\nSessions 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.md](docs/session.md) for file format.\n\n### Management\n\nSessions auto-save to `~/.pi/agent/sessions/` organized by working directory.\n\n```bash\npi -c # Continue most recent session\npi -r # Browse and select from past sessions\npi --no-session # Ephemeral mode (don't save)\npi --session # Use specific session file or ID\njensen resume # Continue a persisted session by exact session ID\n```\n\n`jensen resume ` resolves a persisted session by its exact ID and\ncontinues it in place: conversation history, model/thinking configuration, and\nworking directory are restored, and new activity is written under the same\nsession ID. You can obtain a session ID from `/session` in the TUI or from the\n`--resume` session picker.\n\n### Branching\n\n**`/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.\n\n
\n\n- Search by typing, fold/unfold and jump between branches with Ctrl+←/Ctrl+→ or Alt+←/Alt+→, page with ←/→\n- Filter modes (Ctrl+O): default → no-tools → user-only → labeled-only → all\n- Press `l` to label entries as bookmarks\n\n**`/fork`** - Create a new session file from the current branch. Opens a selector, copies history up to the selected point, and places that message in the editor for modification.\n\n### Compaction\n\nLong sessions can exhaust context windows. Compaction summarizes older messages while keeping recent ones.\n\n**Manual:** `/compact` or `/compact `\n\n**Automatic:** Enabled by default. Triggers on context overflow (recovers and retries) or when approaching the limit (proactive). Configure via `/settings` or `settings.json`.\n\nCompaction is lossy for the active model context. The full history remains in the JSONL file; use `/tree` to revisit. Deterministic checkpoint metadata records the continuation boundary and addressable SHA-256 references for summarized tool evidence, while complete results remain in the durable session tree. Customize compaction behavior via [extensions](#extensions). See [docs/compaction.md](docs/compaction.md) for internals.\n\n---\n\n## Settings\n\nUse `/settings` to modify common options, or edit JSON files directly:\n\n| Location | Scope |\n|----------|-------|\n| `~/.pi/agent/settings.json` | Global (all projects) |\n| `.pi/settings.json` | Project (overrides global) |\n\nSee [docs/settings.md](docs/settings.md) for all options.\n\n---\n\n## Context Files\n\nPi loads instruction files at startup from the global config directory and each directory from the filesystem root down to `cwd`. At each level it uses the first matching file in this order:\n- `JENSEN.md` (preferred)\n- `AGENTS.md` (legacy fallback)\n- `CLAUDE.md`\n\nUse these files for project instructions, conventions, and common commands.\n\n### System Prompt\n\nReplace the default system prompt with `.pi/SYSTEM.md` (project) or `~/.pi/agent/SYSTEM.md` (global). Append without replacing via `APPEND_SYSTEM.md`.\n\n### Cache-Stable Context\n\nJensen automatically keeps system contracts, repository instructions, skill contracts, and canonical tool definitions in a deterministic stable prefix. Date, cwd, Git branch/worktrees, local documentation paths, user requests, execution state, and tool results are sent in the dynamic suffix. There is no configuration switch; custom system prompts remain compatible, and provider/model changes invalidate cache-continuity assumptions without changing session correctness.\n\nJSON mode emits a metadata-only `context_cache` event after each provider response. RPC `get_session_stats` returns the latest diagnostics in `contextCache`. These include SHA-256 fingerprints, stable/dynamic byte counts, provider, model, change reasons, continuity, and cache token telemetry when the provider reports it. They never include prompt text, API keys, authorization headers, or hidden reasoning.\n\nTelemetry capability varies. Anthropic, OpenAI-compatible APIs including DeepSeek, OpenAI Responses, Google/Gemini CLI/Vertex, and Bedrock are normalized when their response includes cache fields. Other providers and endpoints report cache values as unknown rather than fabricated zero. Cache state never replaces the JSONL session tree, compaction checkpoint, or long-horizon execution state.\n\n---\n\n## Web Research\n\nJensen provides separate read-only `web_search`, `web_fetch`, and `deep_research` tools. `web_search` targets a private local SearXNG instance and falls back to DuckDuckGo Lite on operational failure. Neither path requires a paid search API or external account. `web_fetch` securely retrieves one public URL with DNS-pinned SSRF protection, redirect revalidation, bounded decompression, deterministic HTML-to-Markdown extraction, JSON/XML/text support, page-addressable PDF extraction, and optional isolated Playwright rendering. `deep_research` runs a bounded multi-query workflow and returns durable evidence IDs, passage coordinates, hashes, contradiction notices, and machine-readable citations.\n\nThese tools are off by default. Enable them with `--tools web_search,web_fetch,deep_research,web_research_status` or add those names to `tools.defaultActiveToolNames`. Full pages remain in durable session tool-result details; normal model context receives bounded excerpts and evidence references. All page text and search metadata are structurally marked as untrusted data and cannot relax network policy or authorize tool use.\n\nThe default SearXNG endpoint is `http://127.0.0.1:18888`. See [docs/web-research.md](docs/web-research.md) for deployment, configuration, security boundaries, diagnostics, citations, browser installation, privacy, and troubleshooting.\n\n---\n\n## Customization\n\n### Prompt Templates\n\nReusable prompts as Markdown files. Type `/name` to expand.\n\n```markdown\n\nReview this code for bugs, security issues, and performance problems.\nFocus on: {{focus}}\n```\n\nPlace 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).\n\n### Skills\n\nOn-demand capability packages following the [Agent Skills standard](https://agentskills.io). Invoke via `/skill:name` or let the agent load them automatically.\n\n```markdown\n\n# My Skill\nUse this skill when the user asks about X.\n\n## Steps\n1. Do this\n2. Then that\n```\n\nPlace 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).\n\n### Extensions\n\n
\n\nTypeScript modules that extend pi with custom tools, commands, keyboard shortcuts, event handlers, and UI components.\n\n```typescript\nexport default function (pi: ExtensionAPI) {\n pi.registerTool({ name: \"deploy\", ... });\n pi.registerCommand(\"stats\", { ... });\n pi.on(\"tool_call\", async (event, ctx) => { ... });\n}\n```\n\n**What's possible:**\n- Custom tools (or replace built-in tools entirely)\n- Sub-agents and plan mode\n- Custom compaction and summarization\n- Permission gates and path protection\n- Custom editors and UI components\n- Status lines, headers, footers\n- Git checkpointing and auto-commit\n- SSH and sandbox execution\n- MCP server integration\n- Make pi look like Claude Code\n- Games while waiting (yes, Doom runs)\n- ...anything you can dream up\n\nPlace 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/).\n\n### Canonical subagents and Cavecrew\n\nJensen ships one policy-bound subagent registry. Inspect it with `jensen agents list`, `jensen agents inspect `, `jensen agents resolve `, `jensen agents validate`, `jensen agents models`, or `jensen agents aliases`. Skill dependencies can be checked with `jensen skills validate` and `jensen skills dependencies `; use `jensen doctor subagents` and `jensen doctor skills` through the same diagnostics surface when available.\n\nThe built-in roles are `scout`, `cavecrew-investigator`, `planner`, `cavecrew-builder`, `worker`, `cavecrew-reviewer`, `reviewer`, `librarian`, `security`, and `pentester`. Analytical/read-only roles use OpenRouter `deepseek/deepseek-v4-flash-latest`; `worker` and `cavecrew-builder` use OpenRouter `openai/gpt-5.6-luna`. The `~` profile marker is stripped before a provider request and model resolution is recorded. Unknown names fail with a typed error; Jensen never silently substitutes an agent.\n\n`cavecrew-investigator` and `cavecrew-reviewer` are read-only. `cavecrew-builder` is a restricted worker specialization limited to a bounded one- or two-file transactional change, with checkpoint, lease, focused validation, and rollback. Child permissions cannot exceed the parent, and fallback requires explicit policy and approval. User/workspace definitions may shadow packaged resources, but precedence is reported and cannot broaden the canonical policy.\n\n### Workspace Intelligence (1.7.0)\n\nJensen adds durable, local-first workspace indexing and hybrid lexical/symbolic/\nsemantic retrieval over the current workspace. See `docs/workspace-intelligence.md`.\n\n- CLI: `jensen index` (status/build/refresh/rebuild/verify/generations/inspect/\n files/symbols/stats/prune), `jensen search` (lexical|symbol|semantic|hybrid|path),\n `jensen retrieval plan|explain`, and `jensen doctor index|embeddings|retrieval`.\n- Tools: `workspace_search`, `workspace_search_lexical`, `workspace_search_semantic`,\n `workspace_search_symbols`, `workspace_retrieval_status` (read-only), and\n `workspace_index_refresh`.\n- Backend: built-in `node:sqlite` (no new dependency). Embeddings are local by\n default (deterministic fixture); remote embedding is opt-in policy-only.\n- Privacy: source is never uploaded by default; secret-sensitive files are\n excluded; the index is disposable/rebuildable and never an execution authority.\n- Requires Node.js `>=22.5.0`.\n\n### Themes\n\nBuilt-in: `dark`, `light`. Themes hot-reload: modify the active theme file and pi immediately applies changes.\n\nPlace in `~/.pi/agent/themes/`, `.pi/themes/`, or a [pi package](#pi-packages) to share with others. See [docs/themes.md](docs/themes.md).\n\n### Pi Packages\n\nBundle 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).\n\n> **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.\n\n```bash\npi install npm:@foo/pi-tools\npi install npm:@foo/pi-tools@1.2.3 # pinned version\npi install git:github.com/user/repo\npi install git:github.com/user/repo@v1 # tag or commit\npi install git:git@github.com:user/repo\npi install git:git@github.com:user/repo@v1 # tag or commit\npi install https://github.com/user/repo\npi install https://github.com/user/repo@v1 # tag or commit\npi install ssh://git@github.com/user/repo\npi install ssh://git@github.com/user/repo@v1 # tag or commit\npi remove npm:@foo/pi-tools\npi list\npi update # skips pinned packages\npi config # enable/disable extensions, skills, prompts, themes\n```\n\nPackages install to `~/.pi/agent/git/` (git) or global npm. Use `-l` for project-local installs (`.pi/git/`, `.pi/npm/`).\n\nCreate a package by adding a `pi` key to `package.json`:\n\n```json\n{\n \"name\": \"my-pi-package\",\n \"keywords\": [\"pi-package\"],\n \"pi\": {\n \"extensions\": [\"./extensions\"],\n \"skills\": [\"./skills\"],\n \"prompts\": [\"./prompts\"],\n \"themes\": [\"./themes\"]\n }\n}\n```\n\nWithout a `pi` manifest, pi auto-discovers from conventional directories (`extensions/`, `skills/`, `prompts/`, `themes/`).\n\nSee [docs/packages.md](docs/packages.md).\n\n---\n\n## Programmatic Usage\n\n### SDK\n\n```typescript\nimport { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from \"@apholdings/jensen-code\";\n\nconst { session } = await createAgentSession({\n sessionManager: SessionManager.inMemory(),\n authStorage: AuthStorage.create(),\n modelRegistry: new ModelRegistry(authStorage),\n});\n\nawait session.prompt(\"What files are in the current directory?\");\n```\n\nSee [docs/sdk.md](docs/sdk.md) and [examples/sdk/](examples/sdk/).\n\n### RPC Mode\n\nFor non-Node.js integrations, use RPC mode over stdin/stdout:\n\n```bash\npi --mode rpc\n```\n\nRPC 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.\n\nSee [docs/rpc.md](docs/rpc.md) for the protocol.\n\n---\n\n## Philosophy\n\nPi 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.\n\nJensen 3.0.0 provides MCP, logical subagents, durable orchestration, explicit Missions, and governed completion through Jensen-owned runtime authorities. These are no longer extension-only concepts.\n\nThe interactive harness remains extensible and does not provide unrestricted permission popups or background process ownership. Use the documented Mission, Worker, Governance, and process-stewardship paths for durable execution and cleanup.\n\nRead the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/) for the full rationale.\n\n---\n\n## Reliable Agent Runtime\n\nJensen 3.0.0 includes the Reliability Kernel and the durable distributed runtime\naround it: the model proposes actions and completion, while Jensen owns state,\nexecution, evidence, validation, and completion. Durable Missions, the\nScheduler/Assignment/Worker path, remote execution, capability routing, MCP,\nShared Inference, orchestration, Governance/Budgets, restart/reconciliation,\nand Jensen-owned process stewardship are available in this release.\n\nThe model normalizes output into Jensen-owned actions, validates executable\nactions before execution, records observed evidence, runs deterministic\nverification, and enforces a Completion Gate so a model cannot self-certify\ncompletion.\n\n**The model proposes completion. Jensen verifies completion.**\n\n### Automatic activation\n\nIn Jensen 3.0.0 the Reliability Kernel is **automatic** for normal Jensen agent\nsessions. Opening Jensen normally means the kernel is active: real tool calls\nflow through reliability hooks, real tool outcomes become authoritative\nevidence, the Completion Gate controls live completion, and mission state\npersists with the session.\n\nAn assistant turn ending is **not** the same as a mission completing. When a\nmission is active, the model \"stopping\" is routed through the Completion Gate;\na premature \"done\" produces a structured `FINALIZATION_REJECTED` and gives the\nmodel a bounded chance to continue. `jensen resume ` restores the\nsame mission with its criterion and evidence state intact.\n\nSee [docs/reliable-agent-runtime.md](docs/reliable-agent-runtime.md) for the\narchitecture, authority model, lifecycle, and extension points.\n\n---\n\n## Jensen 3.0 runtime boundary\n\nJensen 3.0.0 is the distributed autonomous agent runtime foundation. It is\nnot a persistent daemon/control plane, mobile assistant, voice assistant,\nIoT platform, public Internet service, or complete cross-platform OS process\nsupervisor. Those capabilities are planned for later Jensen 3.x phases.\n\nThe 3.0 runtime keeps durable Mission state and session storage authoritative.\nExisting 2.x session/config formats remain readable where their persisted\nschema is supported. Incompatible or corrupted durable state fails closed;\nit is never silently converted into fake success. Review remote-execution,\nshared-inference, and Governance settings before enabling distributed work.\n\n## Automatic orchestration\n\n`jensen orchestrator preview ` asks the configured local Qwen planner for a bounded plan without persisting it. `jensen orchestrator start ` persists the plan and materializes ready child missions; `--proposal JSON` remains an explicit operator/debug override. Materialization creates durable child identities only. Child execution is owned by the configured child execution port, normally the Scheduler -> Assignment -> Worker path, and the port is the only scheduler enqueue authority. Parent completion is terminal only after required children pass their authoritative status/verification gates; all-optional plans complete once every optional child is terminal. Bounded parent drivers perform mandatory terminal cleanup through Scheduler and Assignment, without writing mission state themselves.\n\nThe Qwen planner path is wired and deterministic seams are covered by tests, but live Qwen inference remains deferred qualification: production readiness depends on the configured local model, registry, and deployment health rather than this planning contract alone.\n\n## Mission Governance\n\nGovernance is a deterministic policy, admission, and decision layer over missions and orchestration. It does not replace Orchestrator, Scheduler, Assignment, Worker, SharedInferenceScheduler, Capability Routing, Mission coordination, Verification, or the Completion Gate. Those authorities still perform their own actions.\n\nGovernance keeps independent accounting for logical-agent work, inference requests, tools, executor work, wall-clock, turns, retries, replans, fan-out/depth, cloud spend, and local inference pressure. Local Qwen (`llamacpp-qwen38-bucephalus/qwen3.8-27b`) has no invented monetary price; queue pressure and wall-clock remain observable separately. Paid inference with unknown pricing is `UNKNOWN`, not zero, and a paid hard-cap decision fails closed.\n\nPolicy precedence is operator hard caps, mission policy, orchestration/role policy, provider/model defaults, then Jensen defaults. A lower layer can reduce a hard cap but never raise it. Model escalation preserves mission/orchestration/node correlation and is selective: a critical child can move from local Qwen to the configured cloud model without changing Mission identity.\n\nDurable inspection is available without launching work:\n\n```bash\njensen governance policy\njensen governance status \n```\n\nThe durable ledger is locked and atomic across processes. Retry classes, escalation history, cloud accounting, and consumed limits survive restart. Empty result envelopes use a separately bounded result-only retry; resource/dependency waiting parks without consuming an inference lease or being classified as reasoning stagnation.\n\n## Subagents and Cavecrew\n\nInspect the canonical registry and skill dependency state with:\n\n```bash\njensen agents list\njensen agents resolve cavecrew-investigator\njensen agents validate\njensen skills validate\njensen skills migrate --preview\njensen cavecrew validate\n```\n\n`cavecrew-builder` is limited to two affected files and uses the existing workspace boundary, policy engine, exclusive lease, checkpoint, transaction, focused validation, and rollback lifecycle. Builder edits are serialized; analytical children are read-only and may run in deterministic parallel assignment order. Parent-side validation rejects invalid child structures before results enter orchestration state.\n\n## CLI Reference\n\n```bash\npi [options] [@files...] [messages...]\n```\n\n### Package Commands\n\n```bash\npi install [-l] # Install package, -l for project-local\npi remove [-l] # Remove package\npi update [source] # Update packages (skips pinned)\npi list # List installed packages\npi config # Enable/disable package resources\njensen agents list --json # Inspect the canonical subagent registry\njensen agents validate # Validate definitions and fallback references\njensen skills validate # Validate loaded skill dependencies before use\njensen routing status --json # Evidence-driven orchestration status\njensen routing decide --task \"...\" --json # Produce a routing decision (offline, deterministic)\njensen routing explain # Explain a past decision with provenance\njensen routing replay # Replay a decision with zero effects\njensen routing compare \njensen routing policy list|generate|validate|promote|rollback\njensen routing drift status\njensen doctor routing --json # Read-only routing subsystem diagnostics\njensen eval packs --json # List built-in and local evaluation packs\njensen eval validate --json # Validate scenario schemas and fixture references\njensen eval run core-runtime --mode fixture --json\njensen doctor eval --json # Read-only evaluation diagnostics\n```\n\n### Evaluation and release gates\n\nJensen's evaluation runtime treats scenarios, fixtures, candidate configuration, durable events, assertions, and result artifacts as versioned data. Use `jensen eval packs`, `jensen eval scenarios`, and `jensen eval validate` to inspect the built-in deterministic packs. `jensen eval run --mode offline|fixture|sandbox` runs bounded evaluation; `live` mode is disabled unless `JENSEN_EVAL_LIVE=1`, `--live`, an explicit provider configuration, and a positive cost budget are all supplied.\n\nDeterministic safety and task assertions outrank semantic judges and aggregate metrics. Candidate self-report cannot set a verdict, missing evidence is not a pass, and safety failures cannot be averaged away. Evaluation artifacts are content-addressed and include scenario, candidate, environment, evaluator, and evidence provenance. Baselines are created and promoted explicitly; they are never silently replaced. Repeated runs retain separate artifacts, and flaky results are explicit rather than clean passes. Ordinary CI uses deterministic fixture providers and no paid API.\n\n### Modes\n\n| Flag | Description |\n|------|-------------|\n| (default) | Interactive mode |\n| `-p`, `--print` | Print response and exit |\n| `--mode json` | Output all events as JSON lines (see [docs/json.md](docs/json.md)) |\n| `--mode rpc` | RPC mode for process integration (see [docs/rpc.md](docs/rpc.md)) |\n| `--export [out]` | Export session to HTML |\n\n### Model Options\n\n| Option | Description |\n|--------|-------------|\n| `--provider ` | Provider (anthropic, openai, google, etc.) |\n| `--model ` | Model pattern or ID (supports `provider/id` and optional `:`) |\n| `--api-key ` | API key (overrides env vars) |\n| `--thinking ` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |\n| `--models ` | Comma-separated patterns for Ctrl+P cycling |\n| `--list-models [search]` | List available models |\n\n### Session Options\n\n| Option | Description |\n|--------|-------------|\n| `resume ` | Continue a persisted session by exact session ID |\n| `-c`, `--continue` | Continue most recent session |\n| `-r`, `--resume` | Browse and select session |\n| `--session ` | Use specific session file or partial UUID |\n| `--session-dir ` | Custom session storage directory |\n| `--no-session` | Ephemeral mode (don't save) |\n\n### Tool Options\n\n| Option | Description |\n|--------|-------------|\n| `--tools ` | Enable specific built-in tools (default: `read,bash,edit,write`) |\n| `--no-tools` | Disable all built-in tools (extension tools still work) |\n\nAvailable built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, `web_search`, `web_fetch`, `deep_research`, `web_research_status`\n\n### Resource Options\n\n| Option | Description |\n|--------|-------------|\n| `-e`, `--extension ` | Load extension from path, npm, or git (repeatable) |\n| `--no-extensions` | Disable extension discovery |\n| `--skill ` | Load skill (repeatable) |\n| `--no-skills` | Disable skill discovery |\n| `--prompt-template ` | Load prompt template (repeatable) |\n| `--no-prompt-templates` | Disable prompt template discovery |\n| `--theme ` | Load theme (repeatable) |\n| `--no-themes` | Disable theme discovery |\n\nCombine `--no-*` with explicit flags to load exactly what you need, ignoring settings.json (e.g., `--no-extensions -e ./my-ext.ts`).\n\n### Other Options\n\n| Option | Description |\n|--------|-------------|\n| `--system-prompt ` | Replace default prompt (context files and skills still appended) |\n| `--append-system-prompt ` | Append to system prompt |\n| `--verbose` | Force verbose startup |\n| `-h`, `--help` | Show help |\n| `-v`, `--version` | Show version |\n\n### File Arguments\n\nPrefix files with `@` to include in the message:\n\n```bash\npi @prompt.md \"Answer this\"\npi -p @screenshot.png \"What's in this image?\"\npi @code.ts @test.ts \"Review these files\"\n```\n\n### Examples\n\n```bash\n# Interactive with initial prompt\npi \"List all .ts files in src/\"\n\n# Non-interactive\npi -p \"Summarize this codebase\"\n\n# Different model\npi --provider openai --model gpt-4o \"Help me refactor\"\n\n# Model with provider prefix (no --provider needed)\npi --model openai/gpt-4o \"Help me refactor\"\n\n# Model with thinking level shorthand\npi --model sonnet:high \"Solve this complex problem\"\n\n# Limit model cycling\npi --models \"claude-*,gpt-4o\"\n\n# Read-only mode\npi --tools read,grep,find,ls -p \"Review the code\"\n\n# High thinking level\npi --thinking high \"Solve this complex problem\"\n```\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `PI_CODING_AGENT_DIR` | Override config directory (default: `~/.pi/agent`) |\n| `PI_PACKAGE_DIR` | Override package directory (useful for Nix/Guix where store paths tokenize poorly) |\n| `PI_SKIP_VERSION_CHECK` | Skip version check at startup |\n| `PI_CACHE_RETENTION` | Set to `long` for extended prompt cache (Anthropic: 1h, OpenAI: 24h) |\n| `JENSEN_SEARXNG_URL` | Private SearXNG endpoint (default: `http://127.0.0.1:18888`) |\n| `JENSEN_WEB_SEARCH_PROVIDER` | `auto`, `searxng`, or `duckduckgo-lite` (default: `auto`) |\n| `JENSEN_PLAYWRIGHT_EXECUTABLE_PATH` | Optional Chromium executable for isolated rendered extraction |\n| `VISUAL`, `EDITOR` | External editor for Ctrl+G |\n\n---\n\n## Contributing & Development\n\nSee [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines and [docs/development.md](docs/development.md) for setup, forking, and debugging.\n\n---\n\n## License\n\nMIT\n\n## See Also\n\n- [@apholdings/jensen-ai](https://www.npmjs.com/package/@apholdings/jensen-ai): Core LLM toolkit\n- [@apholdings/jensen-pods-agent](https://www.npmjs.com/package/@apholdings/jensen-pods-agent): Agent framework\n- [@apholdings/jensen-tui](https://www.npmjs.com/package/@apholdings/jensen-tui): Terminal UI components\n","readmeFilename":"README.md"}
![\"pi](\"https://shittycodingagent.ai/logo.svg\"){kind=logo}
\n \n![\"Discord\"](\"https://img.shields.io/badge/discord-community-5865F2?style=flat-square&logo=discord&logoColor=white\"){kind=icon}
![\"npm\"](\"https://img.shields.io/npm/v/@apholdings/jensen-code?style=flat-square\")
![\"Build](\"https://img.shields.io/github/actions/workflow/status/apholdings/jensen-code/ci.yml?style=flat-square&branch=main\")
![\"Exy](\"docs/images/exy.png\")
![\"Interactive](\"docs/images/interactive-mode.png\")
![\"Tree](\"docs/images/tree-view.png\")
![\"Doom](\"docs/images/doom-extension.png\")