Use Pi 0.99.1 or newer and Node.js 22.19.0 or newer. Upgrade Pi before installing this OpenPI version. Install the public Pi package:
pi install npm:@tt-a1i/openpiTo inspect the current source before loading it, install directly from GitHub instead:
pi install git:github.com/openpi-dev/openpiPi installs the package dependencies automatically. Restart Pi or run /reload after installation.
The file-search extension registers fd and rg as model tools, and git-read registers git_show, git_diff, and git_log (read-only git inspection). They stay outside an ordinary parent turn until the user explicitly asks to use fd/rg/git history, or structured file search, or the model loads the search group through openpi_load_tools. Entering or restoring Plan Mode is a runtime-safety exception: it loads search for that Session so diff investigation can use the structured Git boundary. The gateway is shown after an explicit OpenPI-capability request, or remains visible when the user opts into adaptive discovery; children receive these tools only when active in the parent and permitted by their role allowlist. No setup is normally needed: at startup fd/rg silently use a system-installed binary (fd/fdfind and rg) when available, or an existing binary in the agent's private managed bin directory (~/.pi/agent/bin). Only when neither exists does it download an official release binary (macOS/Linux, arm64/x64, over HTTPS) into that directory — a persistent cache that survives package updates — and show a one-time notification. If your platform is unsupported, install fd and rg with your package manager and restart Pi. The git tools require a system git.
While Plan Mode is active, raw Bash git diff, git show, and git whatchanged are refused, as are diff-generating git log options such as -p, --stat, --name-only, and -L. Use git_log to find commits and git_diff / git_show to inspect changes; the latter commands always pass --no-ext-diff --no-textconv --no-color, so repository-configured diff.external and textconv drivers are not executed. This guarantee is scoped to the Git diff-driver boundary rather than every possible hostile Git configuration; the remaining allowlisted Git investigation commands still run inside Pi's existing project Trust boundary.
Add the included theme to ~/.pi/agent/settings.json while keeping your existing settings:
{
"theme": "github-dark-default"
}Pi will load the extensions and theme the next time it starts. OpenPI's Background, Subagent, and Workflow Skill files remain in the package, but ordinary turns do not advertise them in the system prompt; the matching path is disclosed only after explicit capability intent or after the model loads that group through the opt-in adaptive gateway.
The terminal theme above remains Pi-owned. OpenPI Web has separate package-owned appearance preferences: system, light, dark, mist, rose, and pine themes; chat width from 820-2000px; chat font size from 12-24px; and whether thinking blocks start expanded. system, 820px, 14px, and collapsed are the defaults. Web controls save these presentation values directly through the shared validated configuration writer and apply the saved response without a model turn or chat message. They remain available during running turns and Plan mode. /openpi-setup can also change the same values using natural language; both paths share my-pi-setup.json, locking, validation, unknown-field preservation, and atomic persistence.
The optional OpenPI Browser Bridge is installed and permissioned through Chrome/Edge 145+, not Pi setup. Once installed, it activates by default when the local OpenPI browser tool is open: actual address/title updates, native navigation and ordinary popup links in internal tabs. It removes X-Frame-Options only for external subframes in connected OpenPI tabs and preserves CSP. It cannot guarantee compatibility with every site, cross-origin history or login popup. Disabling the extension restores plain iframe browsing; there is no additional persisted OpenPI preference.
Exit Plan mode before starting /openpi-setup, including from Web settings. The command checks the current Session branch before starting a setup turn, and queued requests are checked again before delivery. Web disables package configuration controls during planning and offers the existing Plan exit action once the Session is idle; exiting does not start a model turn or authorize implementation. Settings reports the latest setup episode from persisted tool receipts, including unchanged saves, failures, cancellation, and an unconfirmed save. A completed turn or an assistant's claim alone is not proof that configuration was saved.
Web appearance controls directly save only their presentation fields; their success status is based on the completed write. Other package-owned settings forms submit requests through /openpi-setup. Role/model choices, concurrency, skill and plugin configuration requests remain visible in that episode, including required confirmation and its final apply/closure receipt. A setup submission message is not proof of persistence. Pi-owned model definitions and credentials have separate direct forms backed by Pi's models.json and native login API; secrets never enter the setup prompt.
Web shows the original setup command and its results, including failed or unapplied requests, rather than hiding the configuration episode. Appearance controls wait for the current run to settle before accepting another change. Chat-width and font-size reset buttons request the existing defaults through the same setup entry point. The model tree selects the editable Pi definition and retains unsaved drafts within the same Session; narrow screens use a labeled settings-section selector.
In the TUI, setup requests default to [OpenPi] <command> and the original user request (including the my-pi-setup alias); long or multiline requests wrap naturally. Pi's app.tools.expand action (Ctrl+O by default) shows the complete original prompt through native rendering. Expansion is host-owned: hosts without a custom-message disclosure-click API do not offer a click toggle. Legacy or invalid command/request metadata falls back to Pi's full native display. This is presentation only: Session content, model input, setup authority, and receipts are unchanged. Web keeps its existing command/request projection; RPC/JSON and HTML exports retain the full prompt rather than the TUI summary. See Issue #654.
Each delivered setup request explicitly announces its new episode. Success and closure messages apply only to their completed episode; a later /openpi-setup request can activate the writer again without reusing the prior episode's authority.
The compact footer preset resolves to plain style with the default single-row layout; it is not a separate stored style. Applying it to the default footer does not change its appearance. Successful setup receipts distinguish saving the document from changing effective settings and list only fields that actually changed. Keeping defaults without invoking the writer does not create a file.
Explicit field assignments retain their meaning: footerStyle="compact" is invalid; the allowed styles are plain, powerline, and powerline-mono. Setup should explain the legal choices and wait for a valid choice instead of silently applying a preset or default. Requesting the compact preset is valid and resets both style and layout. Tool writes reject invalid footer styles and presets; stored invalid styles block writes rather than being repaired automatically.
The personal my-pi-setup.json document uses configVersion: 1. A missing file uses built-in defaults without creating a file. Unversioned documents migrate only on an explicit save. Malformed JSON, read errors, unsupported versions, and invalid known fields block writes and are reported by /openpi-setup; rendering uses safe defaults while the file remains intact. Repair the file, or explicitly remove it to reset. Unknown fields are warned about and preserved; changes that would remove unknown fields are rejected. Diagnostics show field paths, not raw values or post-edit command contents.
On Session start or extension reload with a UI available, OpenPI issues one brief notification if configuration loading has errors or warnings, directing the user to /openpi-setup for full diagnostics. Errors explicitly report the safe-default fallback and blocked writes; legacy documents and unknown fields produce a warning. Missing or valid current-version files stay quiet. This check does not start a model turn, expose the writer, or modify the file. Non-UI callers can obtain diagnostics through the existing setup command.
Setup saves under the existing cross-process lock and waits for current-session configuration consumers to apply. An apply failure restores the previous document and reapplies its configuration, provided the file still matches this write. Concurrent external changes are preserved; an incomplete recovery is reported as an error. This is not an atomic update of all running Pi processes or a crash-recovery journal. No additional setup command, preview UI, or statusline package is required.
Use the single canonical package-owned command. /my-pi-setup remains a compatibility alias. With no arguments, the current model explains the configurable areas and uses ask_user: first run initializes them; later runs explain the saved state and ask whether to keep it, change one area, or review everything. With arguments, it treats the rest as a targeted natural-language request. Persist still goes through the typed configure_my_pi_setup tool. The writer stays hidden while a busy Session queues the setup request, becomes active only when that exact request is delivered to the model, and is hidden again afterward. One successful apply completes the episode. If the run settles without a successful apply, OpenPI appends a visible, durable closure receipt to the Session and later model context; it says that the writer is hidden and re-entry requires /openpi-setup <request>. OpenPI also verifies that the active writer belongs to the package source before announcing an active setup episode; duplicate or mismatched sources fail closed without injecting the setup request. A later configuration change starts a new episode with /openpi-setup <request> rather than reusing the hidden tool:
/openpi-setup
/openpi-setup 让模型在合适时自主发现并采用 OpenPI 能力
/openpi-setup 只在我明确要求时加载 OpenPI 能力
/openpi-setup 开启下一步预测，使用 seal/deepseek-v4-flash，关闭推理
/openpi-setup 关闭下一步预测
/openpi-setup workflow 同时跑 16 个 agent，总任务最多 256 个
/openpi-setup 当前 Pi Session 的 Workflow、Direct 和 BTW 最多同时运行 6 个 child
/openpi-setup Web theme follows the system
/openpi-setup use dark theme in OpenPI Web
/openpi-setup use the mist theme with 960px chat width
/openpi-setup use 16px chat text and expand thinking by default
/openpi-setup 显示大标题
/openpi-setup 切换 Footer 为 powerline
/openpi-setup 用 mono powerline Footer
/openpi-setup Footer 用 compact
/openpi-setup Footer 两行：cwd flex model / context cost flex git
/openpi-setup Footer 只显示 model、thinking、context、cache 和 git
/openpi-setup 关闭自定义状态栏
/openpi-setup 编辑后自动跑 npm run format
/openpi-setup 关闭 post-edit 命令
/openpi-setup 给 explorer 指定当前 Registry 中可用的模型
/openpi-setup 清除 explorer 的模型，让它继承父模型
Capability discovery defaults to explicit, preserving the zero-resident OpenPI tool surface until the user asks for a capability. The case-insensitive English words subagent and workflow are reserved authorization words: entering either word is sufficient to load its capability group, and the interactive editor shows it in Claude Code-style lavender before submission, with a darker purple fallback for light themes. This makes discussion that contains either English word an intentional opt-in tradeoff; conditional and negated clauses remain inert, while Chinese capability names still require a recognized action request. adaptive is an explicit opt-in that keeps only openpi_load_tools visible and allows the model to load a useful group on its own; because this can start Subagents, Workflows, or background processes, normal permission and configured concurrency/call limits still apply. Changing the setting updates the current Session immediately, while already loaded groups remain stable for that Session. Accepted Suggestion text is classified only after it becomes real editor input. The visual feedback and runtime activation share one fail-closed intent classifier. Next-action suggestions default to off. Run /openpi-setup to explicitly choose an available model and reasoning level. After a fully settled main-agent run, one suggestion may appear as dim inline text on the first row of an empty editor; reserved cells at the row end keep CJK IME preedit from overwriting it. Right accepts it into the editor without submitting, while any other editor input dismisses it. Suggestions are ephemeral and never enter session history or model context. Workflows default to 8 concurrent agents and 128 total agent calls per run; configurable hard maxima are 64 and 1024. A separate child_execution_limit is off by default. When explicitly set to 1-64, it is a FIFO cap on active child executions shared only by Workflow, Direct Subagent, and BTW within one top-level Pi Session; their existing Workflow 8/local call limits, Direct pool 4, and BTW pool 2 remain in force. A dormant child, parent Session, Background Terminal, model request, token, cost, and provider quota do not consume this limit. /subagents shows the shared limit, held/queued counts, origin counts, and generic blocking reason without exposing task text. Reducing the configured limit below live held slots is rejected and rolled back; cancellation and shutdown reject queued attempts but do not claim an active child has stopped before its actual terminal lifecycle settles. The large decorative header defaults off and the custom dashboard footer defaults on with a one-line plain layout (model context |flex| git pr cwd; thinking, cache, cost, and throughput remain opt-in metrics). Footer presets are powerline, powerline-mono, and compact; style can also be set independently to plain, powerline, or powerline-mono. Custom layouts use a 2D footerLines array with at most one flex per row for left/right alignment. Nerd Font affects powerline separator glyphs () and adds Codex-style outline icons to compact read, terminal, edit, search, and directory activity rows; all accompanying text remains readable without it. Footer metrics use one Codicon outline family ( model, context, and directory) plus ⎇ for the branch. A Nerd Font containing Codicons renders them as designed; without one, the text labels remain readable even if an icon falls back to an empty box. Footer changes apply immediately in the active TUI session. Subagent results default to a compact status summary; full mode remains available as a per-user setting, and app.tools.expand (Ctrl+O by default) reveals the available child report. Ordinary read, grep, find, and ls operations render as one-line semantic activity summaries. Bash and Write/Edit default to the same activity-row projection, showing the target, running/success/failure state, and useful line or diff counts without replaying stdout or previews. Select full independently for Bash or Write/Edit to keep Pi's native rendering expanded. app.tools.expand temporarily restores the native arguments, output, errors, diff, timing, images, truncation notices, and full-output metadata; it never changes Session history or model context. An optional post-edit command is off by default: set one (for example npm run format, maximum 500 characters) and it runs once in the background after each interactive-TUI turn with successful Write/Edit operations, with failures reported as a notification. It deliberately does not guess whether arbitrary Bash commands changed files. Built-in Agent roles explorer, implementer, reviewer, and advisor are shared by subagent_spawn.agent_type and Workflow agent(..., { agent_type }); all inherit the parent model and currently active child-eligible tools by default. Explicit custom role tools lists narrow that surface; omitted lists inherit it. Built-in investigator roles suggest read-only work but do not impose a read-only tool boundary outside Plan Mode. Existing role files are preserved, so an old global explorer.md allowlist continues to exclude Bash/network tools until deliberately edited. /openpi-setup may assign a currently available Registry model to any subset; clearing one returns it to inheritance and omitted roles stay unchanged. Model precedence is explicit call > selected role-file model > setup assignment > parent inheritance; effort is explicit call > selected role > parent. A trusted project .pi/agents/<role>.md overrides global ~/.pi/agent/agents/<role>.md, which overrides the complete built-in role definition; overrides are diagnosed. Role-model changes apply to the next spawn or Workflow agent call without reload. Configuration is stored privately at ~/.pi/agent/my-pi-setup.json.
OpenPI Web appearance defaults to the system theme, 820px chat width, 14px chat font size, and collapsed thinking blocks. light, dark, mist, rose, and pine are explicit theme choices. The browser consumes every appearance value from each authoritative snapshot without writing a competing local preference.
Web General settings directly save the existing ui.subagentResultDisplay, ui.bashToolDisplay, and ui.fileMutationDisplay choices (compact by default, or full) through the shared appearance writer. They also control the Web result disclosures and their enclosing execution groups. Footer controls save ui.customFooter / ui.footerStyle for the Pi terminal footer. Discovery, workflow limits, suggestions, and post-edit controls submit natural-language requests through the canonical /openpi-setup episode; only a native configuration receipt confirms a change.
Direct Web footer saves update the configuration for Pi's command-line interface. A separate already-running Pi interface refreshes its footer at the next session start or native setup apply; a Web settings event does not itself reconfigure another live Pi session.
On Windows, OpenPI enables Pi's clearOnShrink compatibility behavior for
the regular TUI so shrinking slash-command autocomplete lists do not leave
stale rows on screen. Fullscreen TUI keeps its configured behavior. The
native PI_CLEAR_ON_SHRINK=0 setting remains an explicit opt-out.
Legacy footerItems is accepted and migrated at the input boundary, but new setup writes persist only canonical footerLines. Configurations written by this version are not guaranteed to retain their Footer layout when read by an older OpenPI version.
Web pinned conversations have a separate collapsible section above Workspaces. Use the row pin to pin/unpin; the conversation menu does not duplicate this action. Manual order supports dragging and Move up / Move down. The section menu saves ui.webPinnedSort: manual (default) or updated (recently updated), through the same validated writer as appearance preferences. /openpi-setup can change the same choice. Up to 100 exact Session identities and their manual order are stored in the Web session directory’s workspace metadata. Archive hides pins; restoring reveals their saved positions.
Web sidebar width defaults to 280px (220–420px); tool pane width defaults to 520px (360–720px). Dragging or keyboard resizing saves ui.webSidebarWidth / ui.webAuxiliaryWidth through the shared appearance writer. Reload restores the preferred widths; a small viewport clamps only their visible sizes. /openpi-setup exposes the same choices as ui_web_sidebar_width and ui_web_auxiliary_width.
Web model configuration can query an explicitly supplied provider connection, search its model catalog and add up to 100 selected models in one revision-checked native models.json write. Existing model metadata and credentials are preserved. Discovery uses Pi credentials only for the matching saved endpoint, or an optional temporary key that is not persisted. Catalog queries are bounded to ten seconds, 1 MiB and 500 models, reject redirects, and never send prompts. New models inherit the form's context/output and reasoning defaults; verify these in advanced parameters. Manual configuration remains available when the catalog is unsupported. No additional OpenPI preference is introduced.
Use a finite, foreground command such as npm run format, not a watcher, server, or detached background writer. Post-edit remains off by default and runs only in the interactive TUI, once per settled turn with successful native Write/Edit operations. Bash is not inspected for file changes.
The next Agent start (including a background completion's parent wake-up) waits for outstanding commands to finish, and all tool calls in this Session also join them before executing. This includes read-only and custom tools: a tool-name allowlist cannot reliably identify every workspace reader. Tools that do not access files wait too; only successful native Write/Edit results schedule post-edit. Nonzero exits and interrupted commands produce bounded, sanitized notifications; neither triggers an automatic repair loop or a test-acceptance gate. A command that does not exit can keep the next turn waiting: there is no automatic timeout that silently releases this boundary. Canceling the waiting Agent releases its wait without permitting its tool call or forgetting the still-running command; session teardown can then request command cancellation.
Each queued run captures its command and working directory at settlement. Configuration changes affect future runs; disabling post-edit discards queued runs but lets the active command finish. Session start/shutdown discards queued work and requests cancellation, without treating an abort request as process completion. Results from the old session do not notify the new one.
This coordinates one extension instance's foreground commands with its Agent. It does not lock the workspace against other Sessions, Subagents, external editors, user shell commands, or detached descendants. Pi's command cancellation does not guarantee termination of an entire process tree; keep all command writes in the foreground and inspect interrupted work before relying on its files.
pi-intercom is an independently maintained Pi package for communication between top-level Sessions. OpenPI does not detect, recommend, install, configure, migrate, or remove it. If you need that capability, review its repository and install it through Pi's native package command:
pi install npm:pi-intercomOpenPI Direct Subagents and Workflow children use their native parent/child result channels instead. To preserve process-level identity isolation, their Resource Loader excludes pi-intercom extensions and Skills installed from npm, Git, or local package sources without excluding ordinary project resources that merely share the same directory name.
/goal, /goal <objective>, /goal edit, /goal pause, /goal resume, and /goal clear implement a branch-scoped persistent objective with the current OpenAI Codex Goal semantics. /goal <objective> starts immediately with no second success-condition prompt or admission judge; the objective can contain up to 4000 characters. /goal shows status, objective, elapsed time, consumed tokens, optional token budget, and status-specific command hints. Replacing unfinished work requires Replace current goal confirmation, while a complete goal is replaced silently. Editing preserves usage and the optional budget; it reactivates complete or budget-limited goals only when the preserved budget is not already exhausted.
Model callers use get_goal, create_goal, and update_goal. create_goal is only for an explicitly requested persistent autonomous goal and fails while an unfinished goal exists. update_goal can only mark complete after a strict requirement-by-requirement evidence audit, or blocked after the same genuine blocker repeats for at least three consecutive Goal Turns. User/system operations own pause, resume, clear, usage limits, and budget limits.
There are no normal user-facing Turn, no-progress, or wall-clock caps; a hidden 1000-continuation circuit breaker exists only to stop runaway automation. An optional token_budget must only be positive. Goal non-cached Assistant input-plus-output Token and elapsed-time usage are persisted; crossing the budget marks budget_limited and queues one wrap-up Turn. Active goals continue after reload/resume. Fork and tree navigation defer inherited active continuation until the first explicit user input; paused, blocked, and usage-limited goals remain stopped and can prompt for Resume. A v1 active/waiting goal migrates once to paused. Assistant aborts pause an active goal and Assistant errors block it. Print/json automation is inert. Footer text mirrors Codex (Pursuing goal (…), resume hints, Goal unmet, Goal achieved) without showing the objective or legacy Turn counts. An achieved Footer remains visible until the next explicit interactive/RPC input, then a branch-persisted acknowledgement hides only the Footer while /goal retains the completed record.
Session Tasks remain advisory multi-item work intent and do not determine Goal completion. They are scoped to the current request batch: once every item is done or dropped, the batch closes and the next tasks_add starts again at T1. The model marks a tracked item in_progress before starting it, records done, blocked, or dropped immediately after that item reaches a real outcome, and reconciles touched items before its final answer. Every add/update result returns the complete bounded current snapshot so the next item is explicit and the panel refreshes on each persisted transition. Commit, test, and authorization signals are only task-scoped evidence candidates; OpenPI never infers completion or mutates a task from those signals. Active items persist in a polished Claude Code-style panel above the editor; Ctrl+Shift+T or /tasks hide|show|toggle controls visibility, while /tasks opens the full list. No /openpi-setup setting or secondary judge model is required.
/sessionssearches and previews project sessions before switching./tasksinspects branch-scoped advisory work items./goal ...controls the persistent autonomous session objective./context-pivot <next phase>deliberately compacts a long current session into a next-phase brief. It requires at least 30,000 context tokens and is rejected below that; use/sessionsto browse or switch sessions, or install the optionalpi-intercompackage for communication between top-level sessions./cron every <5m> <prompt>,/cron in <30s> <prompt>,/cron list, and/cron remove <id>schedule a prompt for this session. Jobs are in-memory and session-scoped (cleared on shutdown), fire only while the session is idle, and use a duration grammar (30s/5m/2h, minimum 30s) rather than crontab fields, because the scheduler polls about every 30 seconds. Jobs due in the same poll are delivered as one triggered turn while retaining each job's id and recurrence metadata; if that atomic delivery fails, every due job remains pending for retry./plan [objective]explores read-only before changing anything and automatically loads thesearchcapability for the current Session. While armed it blocksedit,write, mutating Bash, raw Git diff-rendering commands,subagent_send,workflow, andbg_start; read/grep/find/ls/fd/rg,git_log/git_diff/git_show, and verified non-diff Git/GitHub Bash commands stay available. It permitssubagent_spawn, but the harness narrows every newly spawned planning child to investigation-only tools; agent types can narrow that list further, never widen it. The model must submit the complete plan through parent-onlyplan_ready; the write gate stays closed until/planprepares an editable implementation prompt for the current or a fresh Session./plan offcancels.