Skip to content

Architecture Decision Records ​

ADRs record decisions that should not silently change.

The Chinese ADR entry follows the same decision map and points to these records. Decision IDs, status, and the English record remain the source of truth for both locales.

Format ​

Each ADR includes:

  • Status
  • Context
  • Decision
  • Consequences
  • Alternatives (optional)

Index ​

IDTitleStatus
trusted-extension-operation-ownershipTrusted extension operation ownershipImplemented candidate
scheduled-desktop-automationsDesktop automation schedulingAccepted for implementation
subagent-model-fallbackOrdered subagent model fallbackAccepted for implementation
subagent-model-opt-inSeparate Subagent Model Opt-In from Definition PinsAccepted for implementation
0001Use Electron as the desktop shellAccepted
0002Use the pi Agent Harness as the kernelAccepted
0003Hybrid runtime — Rust host core + Node pi agent sidecarSuperseded in part
0004No remote Gateway in the MVPAccepted
0005User-installable plugin systemAccepted
0006Postpone the plugin marketplace; build the local plugin runtime firstAccepted
0007Plugin distribution package format uses .piplug (zip)Accepted
0008Plugin runtime targets isolation in a separate processAccepted (Target)
0009English-first globalizationAccepted
0010Use Rust as backend host coreAccepted
0011Freeze host RPC, storage ownership, and mode defaultsAccepted
0012Universal provider/model coverage via pi-ai + OpenAI-compatible extensibilityAccepted
0013Consolidate settings navigation into four destinationsSuperseded in part by 0026
0014Adopt host-owned storage schema v2Accepted
0015Make settings content responsive to window widthAccepted
0016Organize the sidebar around retained multi-project tabsAccepted
0017Remove composer workspace context railAccepted
0018Carry thinking mode through the complete session pipelineAccepted
0019Work panel subsystems (embedded browser, git review, file browsing)Superseded in part by 0108
0020Configuration provider studioAccepted
0021Platform application chromeSuperseded in part by 0025
0022Application Update DeliveryAccepted
0023Independent Conversation Session ForkAccepted
0024Composer Slash Commands and @ File ReferencesAccepted
0025Keep Application Menus out of Windows/Linux WindowsAccepted
0026Move the Projects Index into Settings as an ArchiveSuperseded in part by 0036
0027Make pi-ai authoritative for model metadataAccepted
0028Scope work-panel runtime contexts to conversationsAccepted
0029Separate native-window and work-panel resize ownershipSuperseded in part by 0032
0030Turn-boundary context checkpoint compactionAccepted
0031Keep composer prompt rows free of brand iconsAccepted
0032Reserve native width for the docked work panelAccepted (amended by 0033 and 0122)
0033Internal-dock work panel (no native window expansion)Superseded by 0122
0034Merge the command palette into global searchAccepted
0035Surface the OS locale through the preload bridgeAccepted
0036Split Settings into AI and Shortcuts destinationsAccepted
0037Resolve project instructions in Electron mainAccepted
0038Bridge plugin-declared MCP servers in Electron mainAccepted
0039Activate plugin skills and ship plugin authoring as a first-party devkitAccepted (skill delivery revised by D174)
0040Resident plugin services and the inter-plugin message busAccepted
0041Bound host runtime resources and decouple message persistenceAccepted
0042Message-scoped inline review cardsSuperseded by 0043
0043Message-owned review snapshots and guarded rollbackAccepted
0044Session-bound project instruction preflightAccepted
0045Bash tool inherits the user's login-shell PATHAccepted (amended D600 / issue #571)
0046Categorized process log filesAccepted
0047Context usage inspector with exact and estimated token sourcesAccepted
0048Lazy per-turn tool activationAccepted
0049Recover automatic context compaction failures with a retained tailAccepted (preflight guard amended by ADR 0282)
0050Bounded provider stream recovery and diagnosticsAccepted
0051Isolate host RPC stdio from the Tokio blocking poolAccepted
0052Plan operating state and approval boundarySuperseded by 0053
0053Plan checkpoint artifact, approval, and execution epochAccepted for implementation
0054Selectable command shell catalog and execution identityAccepted for implementation
0055Agent-only mode; Chat becomes an internal read-only profileSuperseded by 0052 / 0053
0056User-owned MCP servers and skills, with a shared activation scopeAccepted
0057Permission-gated external paths and portable native searchAccepted for implementation
0058Extensions Page Density and Theme-Readable Button SurfacesAccepted
0059Persist Composer Clipboard Files in Session ScratchAccepted (amended 2026-09-14 for #138: prefer editable clipboard text over generated image copies)
0060Archive the Regenerate Branch Under the RPC LockAccepted
0061Imperceptible background context compactionAccepted (amends 0030 / 0049; clauses 2/4/6/7/8 amended by 0064)
0062Bounded Subagents Behind a Task ToolAccepted for implementation (maxTurns clause withdrawn by 0253)
0063A Managed Surface for Global Subagent DefinitionsAccepted for implementation (maxTurns field withdrawn by 0253)
0064Codex-parity context compactionAccepted (amends 0061 / 0030)
0065Smooth shell layout and stream feedbackAccepted for implementation
0066Empty home direct bottom composerAccepted for implementation (amends D111)
0067ChatGPT-inspired empty-home starter guidanceSuperseded by D206
0068Add a keyboard entry point for the work panelAccepted for implementation
0069Make native-tool path mistakes recoverableAccepted for implementation
0070Separate Composer File-Reference Display from Prompt SerializationAccepted for implementation
0071Adopt an Apple-Inspired Global Corner HierarchyAccepted for implementation
0072Add a global plugin launcherAccepted for implementation
0073Stage next-turn composer configuration and preserve stopped throughputAccepted for implementation
0074Native notification permission for pluginsAccepted
0075Manual reload for development-plugin permission ceilingsAccepted
0076Capture the Windows-reserved plugin launcher chord in host-coreAccepted
0077Add an interactive multi-question asktoolAccepted for implementation
0078Cross-platform tray-resident minimizeAccepted for implementation (amended by 0117, 0123, and tray-session-shortcuts)
0079Use VitePress for the bilingual documentation siteAccepted
0080Prewarm the global plugin launcher after bootAccepted
0081Host-owned cross-platform plugin panel chromeAccepted
0082Localized and page-adaptive plugin panel chromeAccepted
0083Custom global UI fontSuperseded in part by 0298
0084Defer new-task session creation until the first messageAccepted
0085Make the work panel shortcut a toggleAccepted (amends 0068)
0086Keep macOS on the regular activation policyAccepted
0087Replace textual Edit matching with a line-anchored, tag-verified contractAccepted for implementation (amends 0043 / 0069)
0088Plugin file access is declared per mode, and deletion is recoverableAccepted (continues 0008 D009)
0089Proactive Background Subagent DelegationAccepted for implementation
0090User-Configurable Close Behavior with Close-to-TrayAccepted for implementation
0091Route provider rate limits through bounded same-turn retryAccepted (amends 0050)
0092Use a plugin-owned surface with a host window-control capsuleAccepted
0093Keep a strict 46px plugin drag band with a minimal capsuleAccepted
0094Admit one desktop instance per data directoryAccepted
0095Sign in with a vendor account instead of pasting an API keyAccepted for implementation
0096Flatten the Settings directory and colocate marketplace source configurationAccepted
0097Place global defaults under the AI settings destinationAccepted
0098Treat every vendor OAuth account as an independent provider rowAccepted for implementation
0099Add titled visual clusters to the Settings directoryAccepted
0100Make builtin subagents inherit the parent permission modeAccepted
0101Model-aware image attachment transportAccepted
0102Publisher-owned plugin source with a Git-hosted artifact storeAccepted for implementation (supersedes 0006)
0103Compact context usage summaryAccepted (amends 0047)
0104Plugin-contributed work panel viewsAccepted
0105Ship Files as a bundled plugin; keep Review in the hostSuperseded by 0241
0106Keep only five core builtin commandsAccepted
0107Make current-session task notification suppression atomicAccepted
0108Remove the built-in interactive terminalAccepted
0109Open Files entries with the OS-associated applicationAccepted
0110Version the plugin panel chrome spacing contractAccepted
0111Reveal Files in the OS File ManagerAccepted
0112Agent Capability Management Roots and Settings IAAccepted
0113Persist the New Task empty slot immediately and deduplicate it by message countAccepted
0114Persist Provider Model Bindings and Thinking ConfigurationAccepted
0115Keep plugin clipboard history host-owned and in memoryAccepted (amended 2026-08-21)
0116Add OpenCode Go as a Fixed Provider PresetAccepted (amended: session routing headers)
0117Preserve the Windows taskbar entry for native minimizeAccepted
0118Keep queued prompts renderer-owned and stop runs at turn boundariesAccepted
0119Event-Driven Subagent TimeoutsAccepted for implementation (killing policy amended by 0166; maxTurns clauses withdrawn by 0253)
0120Bounded Session History WindowsAccepted
0121Keep Composer prompt enhancement one-shot and main-ownedAccepted (D447; issue #14 / #562)
0122Reserve native width while the work panel is visibleSuperseded by 0151
0123Use native taskbar minimize for Windows/Linux window controlsAccepted
0124Bind Temporary Sessions to Their Own Scratch WorkspaceAccepted
0125Renderer Ships Derived Brand Marks and Minified OutputAccepted
0126Agent Capability Pages Are One Workbench That Can AuthorAccepted (maxTurns clause withdrawn by 0253)
0127Transcript Layout Index and Identity-Based TruncationAccepted
0128Share one bounded budget for transient provider failuresAccepted
0129The Subagent Idle Watchdog Bounds Silence, Not SlownessAmended by 0166 (watchdogs no longer kill)
0130Bounded Mounted Transcript WindowAccepted
0131Spill Large Composer Text Pastes into Session ScratchAccepted
0132Attribute cross-display window moves to the userAccepted
0133Use models.dev as the primary model catalog with pi-ai fallbackSuperseded by 0134
0134Use models.dev as the sole model metadata source with a local snapshotAccepted
0135Retry unchanged edited promptsAccepted
0136Preserve the active task boundary across context compactionAccepted
0137Retained Session PanesAccepted (amends 0130 clauses 4/5)
0138Subagent Peer MessagingSuperseded by 0147
0140Fold the Three Peer Tools Into One Peer ToolSuperseded by 0147
0141Make Expanded Sidebar Width User-ResizableAccepted
0142Allow non-loopback HTTP MCP endpoints with explicit risk disclosureAccepted
0143Make Session Titles User-RenamableAccepted
0144Allow User-Configured Thinking-Level OverridesAccepted
0145Publish Native macOS Intel ArtifactsAccepted (amended by D353 / 0191)
0146Assign outer and inner work-panel resize ownership by boundarySuperseded by 0151
0147A2A Protocol Stack for Subagent CoordinationSuperseded by 0165
0148Explicitly disable application keyboard shortcutsAccepted
0149Calm transcript running-status motionAccepted
0150Inline SVG empty-home agent markSuperseded by 0152
0151Keep the work panel inside the fixed application windowAccepted
0152Eight-frame empty-home mascot GIFAccepted
0153Checkpoint the streaming reply beside the transcriptAccepted
0154Reveal the New Task empty destination before host IOAccepted
0155Add Zhipu / Z.AI Named Endpoint PresetsAccepted
0156Simplify the Add-Provider Common PathAccepted
0157Main-owned GitHub issue feedbackAccepted
0158Keep approval cards focused and remember the selected modeAccepted
0159Generated plugin settings and plugin-local shortcutsAccepted
0160Shipped locale registry and searchable language pickerAccepted (amended by 0182)
0161Searchable theme picker matching languageAccepted
0162Cross-session A2A addressingSuperseded by 0165
0163Transcript File References Render as Previewable ChipsAccepted
0164Parent agents collaborate across conversationsSuperseded by 0165
0165Withdraw the A2A / Peer coordination stackAccepted (supersedes 0147 / 0162 / 0164)
0166Parent-judged subagent lifetimeAccepted (amends 0089 / 0119 / 0129; fatal-error path amended by 0189; maxTurns backstop withdrawn by 0253)
0167Agent-chosen Bash timeoutAccepted (amends 0054 / D190 / D273)
0168Main-owned http(s)/mailto allowlist for openExternalAccepted (amends 0109)
0169Classified file preview and live workspace events for plugin viewsAccepted (amends 0104 / 0105 / 0109 / 0111)
0170Ship the work-panel browser as a bundled plugin over public CDPAccepted (amends 0019 / 0104 / 0105)
0171Host-owned completed-turn token historyAccepted (amended by 0173)
0172Contained in-chat image displayAccepted (amends fs/read workspace-only clause)
0173Plugin-owned token usage dashboardAccepted (amends 0171)
0174Host-owned plugin completions and session contextAccepted (amends D019)
0175Explain quiet active turns with live agent activity statusAccepted
0176Per-provider User-Agent overrideAccepted (amends 0095 / 0156; header map superseded by 0178)
0177User-configurable outbound proxyAccepted
0178Per-provider custom HTTP headersAccepted (amends 0176 / 0095 / 0156)
0179Import model configuration from local agent storesAccepted
0180Custom global UI type scaleAccepted
0181Main-owned picker capabilitiesAccepted
0182Traditional Chinese shell localeAccepted (amends 0160)
0183P0 international shell localesAccepted (amends 0160 / 0182)
0184Dock the context usage inspector in the composer toolbarAccepted (amends 0047 / 0103)
0185Korean shell localeAccepted (amends 0160 / 0183)
0186Summarize First-Turn Session Titles with a Main-Owned One-ShotAccepted
0187Focus-Aware Native Task NotificationsAccepted (amends 0107 / D117)
0188Preserve distinct credentials during model configuration importAccepted (amends 0179 / D342)
0189Parent fatal error aborts leftover delegatesAccepted (amends 0166 / D328)
0190Host-gated large-file and dropped-file accessAccepted
0191Label Both macOS Release ArchitecturesAccepted (amends 0145 / D353)
0192Alias a configured model and make model ids copyableAccepted (amends D266)
0193Last-request occupancy in the context inspectorAccepted (amends 0047 / 0103 / 0184)
0194Optional subagent thinking overrideAccepted for implementation
0195Viewport-fixed work panel toggleAccepted (amends 0068 / 0085)
0196Show provider retry causes in the active-turn statusAccepted (amends 0175)
0197Publish a Windows Portable PackageAccepted (amends 0022 / D126 / D603)
0198Name every quiet interval on the live activity rowAccepted (amends 0175 / 0186)
0200Host-owned plugin session import and ownership APIAccepted
0201Explicit plugin project ids and host-owned session refreshAccepted
0202Expose effective subagent thinking metadataAccepted
0203Local MCP control plane for desktop operationsAccepted (amended by D372)
0204Explicit unsigned macOS first-launch helperAccepted
0205Remote Agent Control uses a dedicated Host boundaryAccepted for implementation (post-MVP; amended by D374, D375, and D385)
0206Extend provider retries and show bounded progressAccepted
0207Allow three same-path mutation recovery failuresAccepted (amends 0087 / D186)
0208Plugin desktop control requires native user consentAccepted
0209PowerShell 7 as a selectable Windows command shellAccepted (amends 0054 / D190; issue #151 / PR #191)
0210Subagent output-token capAccepted (extends 0062 / 0063; maxTurns clauses withdrawn by 0253; issue #171 / PR #193)
0211Plan-safe plugin actions for read-only inspectionAccepted (amends 0052 / 0053 / 0170; D384)
0212Remove diagnostic timing log streamsAccepted (amends 0046 / D183)
0213Persist the Host-owned turn queue in host-coreAccepted
0214Trusted extensions run in the Agent sidecarAccepted (v1 implemented; amended by D388 / ADR 0215)
0215Agent extensions are a plugin contributionAccepted (implemented)
0216Truncate regenerates under the RPC lockAccepted (amends 0060 / 0127; issue #211)
0217Host stdout sender must not outlive serveAccepted (amends 0216; issue #211)
0218Effective image-input overrides across Composer and transportAccepted (amends 0101 / D243)
0219User-invoked Skills in the composer slash menuAccepted (amends D123 / D174 / ADR 0024 / ADR 0039)
0220Keep Windows work-panel chrome single-purposeAccepted (amends D154 / D357 / ADR 0195)
0221Render canonical thinking-level values without translationAccepted (amends D369 / ADR 0202)
0222Native file and folder drops in the ComposerAccepted (amends ADR 0101 / D397)
message-quotes-and-side-chatsMessage quotes and renderer-owned side chatsSuperseded by 0268
response-annotationsResponse annotations as prompt attachmentsSuperseded by 0268
floating-annotation-indexFloating annotation index and source locationsSuperseded by 0268
0223Context Usage Display PreferenceAccepted (amends 0184)
0224Right panel tab strip and data-driven add menuAccepted (issue #229)
0225Restore deferred tools from effective session contextAccepted (issue #225)
0226Reserve chat width for composer controlsAccepted
0227Project group manual orderingAccepted (amended by 0228)
0228Long-press the project title to reorderAccepted (amended by 0229)
0229Press-and-move project title reorderAccepted (amends 0228)
0230Skill ships with the Agent core tool setAccepted (amends D174 / ADR 0048 / ADR 0219; issue #204)
0231Ideographic comma opens the composer slash menuAccepted (amends D123 / D139 / ADR 0024; issue #65)
0232Keep macOS DMG opening guidance text-onlyAccepted (amended by 0296; amends D371 / ADR 0204)
0233Renderer-owned multi-folder project creationAccepted (amends ADR 0011 / ADR 0016)
0234Keep project memory host-owned and path-scopedAccepted
0235Preserve domain facades and enforce architecture budgetsAccepted
0236Restore archived projects when session import adds a bound sessionAccepted
0237Keep Session Orchestration in an Official PluginAccepted
0238Prioritize MainChat in the three-column shellAccepted (amends ADR 0226)
0239Host-owned session collaboration messagesAccepted (amends ADR 0237 / 0165 / 0213; amended by D446)
0240Independent session discovery and navigable collaboration projectionsAccepted (amends ADR 0239)
0241Ship the file view as a vendored, updatable pluginAccepted (supersedes ADR 0105; issue #304)
0242Delta-only coalesced streaming updatesAccepted (amends 0127 / 0130 / 0149 / 0153; issue #299)
0243Skill market public-HTTPS catalog fetchAccepted (amends 0009; issue #287 / PR #290)
0244Bound dependency installation for imported extensionsAccepted
0245Harden the MCP market public-network boundaryAccepted
0246Opt-in subagent inheritance of the parent tool catalogAccepted (amends 0062; issue #215 / PR #319)
0247Git clone accepts only syntactically public hostsAccepted (amends home git clone; D416)
0248Package theme assets and contributed window backgroundsAccepted (issue #335)
0249ChatGPT-style logical project groupsAccepted (amends ADR 0233 / ADR 0234 / ADR 0016)
0261Plugin Appearance ExtensionsAccepted for implementation
0251Deleting a project removes its owned sessionsAccepted
global-sidebar-pinsShow pinned conversations in a global sidebar sectionAccepted (amends ADR 0016; issue #306)
0250Structured, bounded, and redacted process logsAccepted for implementation
0262Chat file references complete in main and open in the file viewAccepted (amends ADR 0163 / ADR 0241)
0263Expose a project's folder roots and complete references across themAccepted (amends ADR 0262; ADR 0249 §5)
0264Host-mediated file actions follow the folder a view is browsingAccepted (amends ADR 0263; ADR 0249 §5)
active-turn-steeringBind Composer steering to the active durable turnAccepted (active-turn-steering; issue #164)
0252Host turn-end event for pluginsAccepted (D422)
0253Remove the subagent turn limitAccepted (supersedes the maxTurns clauses of 0062 / 0063 / 0119 / 0126 / 0166 / 0210)
0254Continue native Pi sessions in their canonical JSONLAccepted (amends baseline D007; D421)
0257Host-mediated real-time capabilities for pluginsAccepted for implementation
0258Trusted extension custom agentsAccepted for implementation (D426; issue #401)
0259Plugin-declared providers are Host-owned rowsAccepted for implementation (D427)
0255Theme assets are absolute pathsAccepted
0256Preserve DeepSeek reasoning across context compactionAccepted
0260Plugin runtime theme APIs and sidebar image tokenAccepted for implementation
0265Priority block and row actions for the Host-owned turn queueAccepted for implementation (D429; amends ADR 0213 / 0118)
session-content-searchDiscover sessions by indexed message textAccepted
transcript-reading-ownershipShare renderer history and search viewsAccepted
0266Plugin fs roots follow the calling sessionAccepted (D093)
tray-session-shortcutsBounded session navigation in the native trayAccepted (amends ADR 0078; issue #293)
0267Plugin labels follow the app languageAccepted (amends 0160; ADR 0182)
0270Builtin subagents can be switched offAccepted for implementation (amends ADR 0063; ADR 0112)
0271Rebuild the shared provider transport after repeated unanswered failuresAccepted for implementation (issue #234)
0269Move capability documents between the global and project levelsAccepted for implementation (amends ADR 0112)
0268Remove quotes, annotations, and side chatsAccepted (supersedes message-quotes-and-side-chats / response-annotations / floating-annotation-index)
0272Judge a public-network address on the route the request will dialAccepted for implementation (amends ADR 0243; issue #419 / PR #473)
0273Git checkout as a Create project sourceAccepted for implementation (amends ADR 0233; ADR 0247)
0274A development plugin is reviewed before it is loadedAccepted for implementation (amends ADR 0005)
0275A floating widget placement for plugin panelsAccepted for implementation (amends ADR 0093 §4; ADR 0092 / ADR 0110)
0276Official plugin channel and backup channelsAccepted for implementation (amends ADR 0102; D442)
0277Draggable chat content widthAccepted (D439)
0278Canonical application ID net.aiuo.pi-desktopAccepted (D443; amends D141 / D371 / ADR 0204; issue #524)
0279Resumable subagent delegationsAccepted for implementation (amends ADR 0062; ADR 0089; issue #513)
0280Plugin-owned UI localizes from the host localeAccepted (amends ADR 0267; ADR 0159)
0281Host speech capabilityAccepted for implementation (amends ADR 0257)
0282Retry and right-size the compaction summary before retained-tail recoveryAccepted (amends ADR 0049; issue #543)
0283Remote MCP server OAuth 2.1 authenticationAccepted
0284Headless runtime boundary in packages/host-runtimeAccepted for implementation (D447; ADR 0205 R2 prerequisite)
0285RACP-WS transport in packages/racpAccepted for implementation (D448; ADR 0205 R2)
0286Remote-host desktop kernelAccepted for implementation (D449; ADR 0205 R2)
0287Host-rendered plugin scenic Settings surfacesAccepted for implementation
0288Package-local theme assets remain availableAccepted for implementation (amends ADR 0255)
0289Signed macOS GitHub Releases and in-app update deliveryAccepted (D450; amends ADR 0022 / 0145 / 0191 / 0204 / D078)
0290Restore resizable sidebar width with collapse-below-thresholdAccepted (D459; amends ADR 0141 / ADR 0238)
0291Remove the speech settings UIAccepted (amends ADR 0281)
0292SSH bootstrap for remote hostsAccepted for implementation (D453; ADR 0205 R2b, extends ADR 0286)
0293SSH password authentication for the remote-host bootstrapAccepted (D454; amends ADR 0292)
0294Project archive is a list + inspector workbenchAccepted (D455; amends D267 / D168)
0295Session thinking-parameter omissionAccepted (D456; amends ADR 0194 / ADR 0144 / ADR 0221)
0296Signed macOS DMG is a two-icon installAccepted (D457; amends ADR 0232 / ADR 0204)
0297Provider-hosted web search as an adapter capabilityAccepted
0298The app ships no fontsAccepted (D598; amends ADR 0083 / D232)
0299Subagent context budget and delegate compactionAccepted for implementation (amends ADR 0064; extends ADR 0062 / ADR 0279)
0300Host-owned encrypted portable configuration syncAccepted for implementation
0301Explicit append-only WebDAV compatibility modeAccepted for implementation
0302A failed compaction keeps the recent window, and an oversized summary is chunkedAccepted for implementation (issue #827; amends ADR 0049 / ADR 0282)
0303A skill package carries resources far above the document capAccepted for implementation (amends ADR 0300)
0304Trust the network endpoints the user enters themselvesAccepted for implementation (amends ADR 0243 / 0245 / 0247; follows ADR 0142 / 0257 / 0300)
0305Keep scheduled-task execution settings task-ownedAccepted for implementation (amends scheduled-desktop-automations)
turn-process-and-thinking-displayTurn process and thinking presentationAccepted
provider-display-orderProvider display orderAccepted
registry-header-variable-spellingRemote header variables accept the registry's {name} spellingProposed
provider-system-certificatesDesktop sidecar uses OS-trusted certificatesAccepted
image-generation-capabilityImage generation as a configured Agent capabilityAccepted

Local-first · Model-agnostic · Plugin-powered. AIUO.NET