--- slug: "rosetears-aili-pi" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/Rosetears520/aili-pi@main/README.md" repo: "https://github.com/Rosetears520/aili-pi" source_file: "README.md" branch: "main" --- # AILI for Pi `@rosetears/aili-pi` is a Pi Package that adds ROSE delivery routing, five workflow prompts, a pinned AILI skill snapshot, native Pi integrations, and diagnostics to the official `pi` CLI. It does not replace or fork Pi. ## Requirements - Linux - Node.js 22.19.0 or newer - Pi 0.81.1 or newer with the Package and Extension APIs used by this release macOS and native Windows are not supported by this bootstrap and fail before installation mutation. ## Install Run the repository bootstrap: ```sh ./install.sh ``` If Pi is absent, the script downloads only `https://pi.dev/install.sh` over HTTPS and executes it with your user authority. The upstream “latest installer” is trusted through ordinary TLS because no accepted checksum/signature mechanism is currently available. Review that boundary before use in a sensitive environment. The script preserves an existing compatible Pi by default. To request Pi's own self-update first: ```sh ./install.sh --update-pi ``` Equivalent package lifecycle commands: ```sh pi install npm:@rosetears/aili-pi@latest pi list pi update npm:@rosetears/aili-pi pi remove npm:@rosetears/aili-pi ``` During a Pi-managed npm install or update, the package replaces only existing same-name directories in `~/.agents/skills/` with its pinned AILI skill snapshot. It does not create package-only skills, alter differently named skills, retain backups, or load its embedded AILI snapshot as a second Pi skill source. The package remains installed for its Extensions, prompts, theme, and bundled `librarian` skill. Removal is destructive for this Package. It does not remove Pi and must not be presented as rollback when replacing a pre-existing AILI installation. ### Explicit global resources The package does not write global AILI resources during extension load. After reviewing the target, explicitly run: ```text /aili-install-global-resources ``` That command creates or updates only the AILI marker block in `~/.pi/agent/APPEND_SYSTEM.md` and installs the 19 packaged profiles at `~/.pi/agent/agents/aili/`. The marker block is a Pi-native governance derivation of the pinned `aili-workflows` global AGENTS template: it retains instruction precedence, untrusted-content handling, approval/evidence/verification discipline, bounded delegation, project-rule precedence, and user-language output, while excluding OpenCode-only control planes. It preserves unrelated prompt content, rejects malformed markers or an unowned profile collision, and reports stale profiles without pruning them. ## Rose Cyberdeck The package supplies the dark `rose-cyberdeck` theme plus three additional Pi Extensions: a Rose header, Rose Shimmer + four-row Rose Code Rain working surface, and Zentui footer/editor surface. Select it through Pi's `/settings` theme selector or set `"theme": "rose-cyberdeck"` in `~/.pi/agent/settings.json`. The visual extensions are adapted from `pi-sakura-cyberdeck` at revision `165a1f8011a12a58a6409b56b8a6c0416cd9b589` under MIT; see `THIRD_PARTY_NOTICES.md` and `notices/pi-sakura-cyberdeck-NOTICE.txt`. Rose Code Rain uses the original sparse, fixed-column waterfall geometry: `density` selects even-cell tracks, at most 96 tracks span ultra-wide terminals, and each track falls vertically with a randomized tail and gap. The default 12 FPS cadence and 8–16 rows/second fall speed sit between the released and dense-preview profiles. `/rose-matrix status`, `/rose-matrix fps <8-18>`, `/rose-matrix density <0.45-0.95>`, and `/rose-matrix appearance ` change active preferences. `/sakura-matrix` remains a deprecated compatibility alias. Header, rain, frames, footer, and editor use the Rose six-color system: Blue, Ice, Cyan, Violet, Rose, and Soft Rose. ### Migrating from Rem/Sakura names Replace an exact legacy `rem-cyberdeck` theme token with `rose-cyberdeck` through `/settings` or `~/.pi/agent/settings.json`; when using a `light/dark` pair, replace only the legacy side. Existing `sakura-cyberdeck-matrix.json` and `rem-cyberdeck-zentui.json` configuration files are read compatibly and retained. Legacy product names below appear only for migration or upstream attribution. Zentui enables its experimental fixed-bottom editor by default when the installed Pi TUI exposes the required private layout capabilities. If capability detection or installation fails, it keeps Pi's native editor and emits a warning. The feature uses the terminal alternate screen; its default mouse scrolling can interfere with terminal text selection and tmux scrollback. Use Zentui's `/zentui` settings to disable the fixed editor or mouse scrolling. Zentui hides `pi-cache-stats` by default so the one canonical Codex weekly quota remains visible; explicitly re-enabled cache stats follow quota in the bounded footer. ## Commands and modes - `/ideate`, `/define`, `/build`, `/ship`: the four AILI delivery modes. - `/local-review`: a standalone local audit, not a fifth lifecycle mode. - `/aili-doctor` or `/aili-doctor --json`: human or machine-readable health evidence. - `/aili-compact [context|stats|sweep|manual|compress|decompress|recompress|cache|prompt|on|off|restore-all|doctor]`: AILI Compact context controls and diagnostics; `cache panel on|off` toggles its bounded footer widget, and `prompt reload` explicitly refreshes an opted-in prompt snapshot. - `/perm`: the revision-bound `pi-permission-modes@2.2.0` adaptation controls `Default`, `Plan`, `Build`, and `YOLO`. - `Alt+M`: upstream mode-cycle shortcut. - `/aili-install-global-resources`: explicit installation/update of marker-owned global ROSE and AILI-role resources. ### AILI Compact AILI Compact is a provider-time context projection: Pi Session JSONL/tree remains append-only source truth, while bounded v2 transactions control only the provider copy. Its exact model surface is six tools: `aili_compact`, `aili_decompress`, `aili_prune`, `aili_search_context`, `aili_compact_status`, and read-only `aili_context_recap`. Status returns an epoch/branch-scoped `catalogId`, paged `mNNNNNN` message references, active `bNNNNNN` block references, candidates, recap previews, and bounded policy reasons. Mutators must be the sole tool call and echo the current catalog. `aili_compact` supports bounded range and message batches, rejects stale/split/overlapping/protected or non-beneficial selections, and inserts deterministic recap call/result pairs while removing hidden source and stale compact protocol from the provider projection. Decompression is all-or-nothing for 1..16 current-epoch blocks and returns at most 2,000 UTF-8 bytes of exact preview; pruning applies only to complete consumed tool-result atoms. Search remains current-branch, including query-only archived source. `/aili-compact context [offset] [limit]` defaults to 0/32 with limit 64; `stats` is distinct; `sweep [limit]` defaults to 8 and bounds 1..16; direct `decompress`/`recompress` accept 1..16 block refs. `manual on|off` controls only semantic-compression mode and is independent of `autoCooling`. `compress [focus]` appends one replayable trigger and starts one visible user turn permitting at most one compact attempt; busy or invalid requests append and request nothing. Hard protection covers AILI/incomplete/binary/current-turn/recent-user atoms, secret paths, configured tools/globs, balanced protect tags, and uncertain metadata. Automatic work groups consumed candidates, journals dedupe/purge-error decisions, emits adaptive reference-discovery guidance, and leaves subagent results raw unless default-off public lineage/completion gating is explicitly enabled and proven. Generational/nested GC is provider-free; unsafe major GC always leaves Pi emergency recovery available, and each completed Pi compaction starts a new summary-plus-tail epoch. The cache surface has two bounded sections. **Current Session cache statistics** replay assistant `usage` from Pi's current `SessionManager.getBranch()` once on session start/reload or explicit tree navigation, then update in O(1) from each finalized assistant `message_end`; they survive restart through Pi JSONL without polling the filesystem or rescanning the branch on each provider request/widget draw. They show current-branch input, output, cache-read/write totals and `cacheRead/(input+cacheRead+cacheWrite)` hit rate. **AILI repeated-request stability diagnostics** remain separate: cache identity hashes provider, model, session, branch source, epoch, projection, guidance, and sorted active tool schemas/prompts. Only matching warm requests with numeric `cacheRead` and `cacheWrite` enter its last-20 window, which requires five eligible samples; cold, state-change, zero-token, and unavailable telemetry are counted separately. `/aili-compact cache` keeps the bounded two-section detail view. The below-editor widget is enabled by default, renders the detailed current Session statistics as a left-aligned column and AILI stability as a right-aligned column, and remains user-toggleable with `cache panel on|off`; live terminal-resize behavior remains host-unverified on Pi 0.81.1. Custom prompts are **opt-in**, not a cache optimization. With `experimental.customPrompts: true`, only six fixed slots are read from global `~/.pi/agent/aili-compact-prompts/` and project `.pi/aili-compact-prompts/`: `system.md`, `compress-range.md`, `compress-message.md`, `context-limit-nudge.md`, `turn-nudge.md`, and `iteration-nudge.md`. Project overrides global per slot; each file is limited to 4 KiB and the immutable snapshot to 8 KiB. Slot text is bounded guidance and cannot override schemas, protocol, source fidelity, privacy, or safety. It is never written to JSONL, diagnostics, tools, or widgets; AILI never creates or mutates these files. `/aili-compact prompt reload` explicitly refreshes the snapshot and starts a cache-input state transition. Healthy manual Pi compaction is redirected to AILI controls; unhealthy projection or unsafe overflow falls through to Pi recovery. Local serializer evidence covers installed OpenAI Completions/Responses, Anthropic, and Gemini adapters, but real-provider summary quality/cache performance, later third-party context-handler order, and Pi internal request order remain Unverified. `opencode-acp@1.12.6` is recorded as an AGPL-3.0-or-later behavior reference only; AILI Compact is independently implemented for Pi and distributes no ACP source, prompt, schema, fixture, or asset. The `pi-permission-modes@2.2.0` baseline owns mode persistence, prompts, and sandbox behavior. AILI carries one hash-locked matcher adaptation so `*` and `?` also match line terminators; this prevents multiline Bash/heredoc text from falling through YOLO's `"*": "allow"` rule while retaining custom ask/deny and fail-closed fallback behavior across every pattern-map surface. A Linux disposable fixture verified the stock Build profile through installed Bubblewrap, while an incompatible Git-worktree fixture visibly fell back to confirmation. This is not an isolation guarantee. `YOLO` remains an unrestricted, unsandboxed mode and must be treated accordingly. ## Native integrations and side effects - `pi-web-access@0.13.0` provides its complete upstream web-search, content-fetch, curator, clone/PDF/video, and bundled-skill surface. Its provider fallback, network traffic, config/credential paths, clone cache, temporary curator service, downloads, and optional browser-cookie access are upstream behavior; inspect its tool requests and configuration before use. - `pi-quota-status@0.3.0` is enabled by default. It may maintain `~/.pi/agent/pi-quota-status/state.json`; `/quota config` creates its configuration template. Zentui displays exactly one weekly value as `codex `, preferring explicit `Wk` data and treating the dependency's current `5h`-labeled primary value only as a compatibility fallback when weekly is absent. - `pi-permission-modes@2.2.0` provides the permission UI and sandbox degradation behavior above through AILI's exact-source adaptation. The only semantic source change is line-terminator-safe shared glob matching; `upstream/pi-permission-modes.lock.json` records the baseline and adapted hashes. AILI does not retain `/aili-mode` or `Ctrl+Shift+Alt+A` as competing controls. - AILI owns the public `task`/`hub` persistent Agent framework. `task` creates parent-scoped official Pi child sessions using 19 specialized `aili.*` selectors or `general`; top-level work is async by default, supports bounded batch scheduling, and returns stable Agent/job/turn IDs plus `agent://` and `history://` references. `hub` provides list/send/wait/inbox/output/history/jobs/cancel/model operations, park/revive, durable delivery, and owner/descendant scoping. No `subagent` compatibility alias or run/attempt backend selector remains. See [`docs/persistent-agents.md`](https://github.com/Rosetears520/aili-pi/blob/HEAD/docs/persistent-agents.md). - `pi-cache-optimizer@2.6.18` provides `/cache-optimizer`, provider cache diagnostics, cache statistics, and prompt-cache optimization. It may maintain `~/.pi/agent/pi-cache-optimizer-stats.json`; `/cache-optimizer fix` is interactive and is the only command that may propose editing `models.json`. - `pi-markdown-preview@0.10.1` provides `/preview`, `/preview-browser`, `/preview-pdf`, `/preview-clear-cache`, and the `preview_export` tool. Terminal/browser previews require a Chromium executable; PDF export additionally requires Pandoc and a LaTeX engine. - `@narumitw/pi-lsp@0.25.0` provides language-agnostic `lsp_diagnostics`, `lsp_fix`, and `/lsp`. It supports routes for C/C++, Python, CSS/SCSS, JavaScript/TypeScript, Go, Rust, Java, Kotlin, Bash, YAML, Terraform, and other languages. It does not download language servers; install the required commands separately and configure project routes in `.pi/pi-lsp.json` or user routes in `~/.pi/agent/pi-lsp.json`. These three community extensions are initialized by the single AILI Extension entry and remain upstream-owned code. AILI does not load `pi-lens` alongside `@narumitw/pi-lsp`, because both provide overlapping LSP tools. ## Optional capability packs The core package does not install optional providers automatically. - `web-research`: public web retrieval and source verification. - `browser-qa`: browser-rendered inspection. - `artifact-runtime`: durable artifacts and format transformations. - `project-memory`: project-local durable memory after a separate project contract. When unavailable, runtime and doctor output use explicit `SKIP`/`WARN` results and must not claim the work ran. Enable guidance and side effects are recorded in `manifests/capabilities.json`. ## Security boundary AILI applies a non-removable in-process child guard before tool approval. It denies credential, authentication, and private-key paths/material; intersects parent-active tools with role/call ceilings; and routes each `ask` decision back to the parent UI. In sandbox-required modes, child Bash reuses the initialized `pi-permission-modes` SandboxManager through a child-cwd-specific Bash definition; if that executor is unavailable or the child is in an incompatible Git worktree, Bash fails closed rather than running unsandboxed. Parent task acceptance is not blanket child authorization. The guard does not make arbitrary trusted extension code safe, and neither AILI nor Pi claims a universal OS sandbox. Inspect exact approval targets and do not put credentials in task text. Use `hub jobs`, `hub wait`, `hub output`, and `hub history` to inspect durable asynchronous work. At most 32 top-level turns run concurrently; nested work is synchronous and depth-bounded. Persistent Agents are a benefit-based way to improve execution efficiency and preserve parent context, while the main agent retains decisions, integration, and final verification. Direct parent work remains valid when delegation has no clear net benefit; no Agent call is required to unlock mutation. Provider/model behavior still depends on the configured Pi environment. ## Provenance and reproducibility - `upstream/aili-workflows.lock.json` pins the exact canonical 64-skill/471-file snapshot. - `upstream/opencode-global-agents.lock.json` pins the global AGENTS source revision/hash and documents its Pi-native derivation. - `upstream/pi-permission-modes.lock.json` pins the exact upstream and adapted permission runtime files and semantic diff. - `manifests/skill-compatibility.json` records one compatibility state per skill. - `manifests/roles.json` records 19 generated specialized profiles plus the AILI-owned `general` profile. - `manifests/provenance.json`, `manifests/sbom.json`, and `THIRD_PARTY_NOTICES.md` record adapted/reference sources and the exact npm lock inventory. Verify generated artifacts with: ```sh npm run validate:generated npm run validate:provenance npm run validate:release ``` ## Troubleshooting - **Unsupported Pi version/API:** update Pi explicitly, then rerun the bootstrap. The script fails before AILI mutation when preflight cannot prove compatibility. - **Package install failure:** keep the reported Pi/AILI states distinct. Retry the printed `pi install` command after fixing the cause; do not automatically remove a pre-existing package. - **Doctor is non-pass:** inspect the exact `ERROR`, `WARN`, `SKIP`, or `UNVERIFIED` component. Missing optional packs are not core execution success. - **Permission shortcut does nothing:** use `/perm`; terminal multiplexers may consume `Alt+M`. - **YOLO still asks for multiline Bash:** confirm the loaded Package contains the adapted permission runtime with `npm run verify:permission-modes`; do not work around it by granting every distinct script for the session. - **Persistent task says the parent Session is not durable:** start/save a normal Pi session first; Agents require a parent JSONL so their sidecar can be scoped exactly. - **Child Bash is denied in a sandbox-required mode:** inspect `/sandbox` for dependency/platform readiness. AILI deliberately denies instead of running unsandboxed when the parent SandboxManager is unavailable or when an isolated Git worktree uses a `.git` file that Bubblewrap cannot bind safely. - **Global resources are non-pass:** run `/aili-install-global-resources` only after reviewing the exact `~/.pi/agent/` targets. A malformed marker or an unowned role collision intentionally leaves files unchanged. - **Offline use:** the installed Package embeds the pinned skills and does not fetch `aili-workflows` at runtime. Its Pi-managed npm lifecycle synchronizes only pre-existing same-name global skills from that embedded fixed snapshot. First-time Pi/package installation still requires the relevant package sources. See `THIRD_PARTY_NOTICES.md` for source and license details. No official endorsement by the Pi maintainers is claimed.