monopi logo # ๐Ÿœ monopi **One command to supercharge [pi-coding-agent](https://github.com/badlogic/pi-mono).** Like oh-my-zsh for pi. [![CI](https://github.com/ifiokjr/monopi/actions/workflows/ci.yml/badge.svg)](https://github.com/ifiokjr/monopi/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/ifiokjr/monopi/graph/badge.svg?branch=main)](https://codecov.io/gh/ifiokjr/monopi) [![license](https://img.shields.io/github/license/ifiokjr/monopi)](./LICENSE) [![node](https://img.shields.io/node/v/@monopi/monopi)](https://nodejs.org) ```bash npx @monopi/monopi ```
--- ## 30-Second Start ```bash npx @monopi/monopi # install the default monopi bundle pi # start coding ``` monopi installs the full bundle into pi in one command. See [Installer Options](#installer-options) for project-scoped installs and version pinning. ## Start Here Use this reading path depending on what you are trying to do: - **I just want to use monopi** โ†’ start in the root `README.md`, then jump into `docs/feature-catalog.md` for package-by-package detail - **I want to try the latest local changes** โ†’ run `pnpm install`, `pnpm pi:local`, restart `pi`, then exercise the feature in a real session - **I want to contribute** โ†’ read `CONTRIBUTING.md`, then the package README for the area you are changing - **I want to understand ownership** โ†’ use `docs/feature-catalog.md` to see which package owns which runtime feature, content pack, or library surface ### Architecture at a glance ```text monopi repo โ”œโ”€โ”€ installer โ”‚ โ””โ”€โ”€ @monopi/monopi โ”œโ”€โ”€ default runtime packages โ”‚ โ”œโ”€โ”€ extensions โ”‚ โ”œโ”€โ”€ background-tasks โ”‚ โ”œโ”€โ”€ diagnostics โ”‚ โ”œโ”€โ”€ subagents โ”‚ โ””โ”€โ”€ web-remote โ”œโ”€โ”€ content packs โ”‚ โ”œโ”€โ”€ themes โ”‚ โ”œโ”€โ”€ skills โ”‚ โ””โ”€โ”€ agents โ”œโ”€โ”€ opt-in extras โ”‚ โ”œโ”€โ”€ adaptive-routing โ”‚ โ”œโ”€โ”€ provider-catalog โ”‚ โ”œโ”€โ”€ provider-cursor โ”‚ โ”œโ”€โ”€ provider-ollama โ”‚ โ”œโ”€โ”€ analytics-extension โ”‚ โ”œโ”€โ”€ pi-remote-tailscale โ”‚ โ”œโ”€โ”€ pi-bash-live-view โ”‚ โ””โ”€โ”€ pi-pretty โ””โ”€โ”€ contributor libraries โ”œโ”€โ”€ core โ”œโ”€โ”€ cli โ”œโ”€โ”€ shared-qna โ”œโ”€โ”€ web-client โ”œโ”€โ”€ web-server โ”œโ”€โ”€ db โ”œโ”€โ”€ analytics-db โ”œโ”€โ”€ analytics-dashboard โ””โ”€โ”€ docs ``` ### Fork-based Git install If you keep a personal fork with custom monopi changes, you can also install the repo root directly as a pi package: ```bash pi install https://github.com//monopi@ ``` That git-install path is meant for personal fork distribution across machines. It aggregates the repo's shareable runtime packages directly from the clone so you do not have to mirror local workspace paths. Published npm installs remain the better default for stable releases. ## Packages This is a monorepo. Install everything at once with `npx @monopi/monopi`, or pick individual packages. | Package | Role | Install | | ----------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------- | | [`@monopi/monopi`](./packages/monopi__monopi) | Meta-installer for the default monopi bundle | `npx @monopi/monopi` | | [`@monopi/cli`](./packages/monopi__cli) | Interactive TUI configurator | `npx @monopi/cli` | | [`@monopi/core`](./packages/monopi__core) | Shared types, registries, icons, i18n, and path helpers | (library, not installed directly) | | [`@monopi/db`](./packages/monopi__db) | Shared SQLite/Drizzle database for persistence-based extensions | (library, not installed directly) | | [`@monopi/extension-worktree`](./packages/monopi__extension-worktree) | Split extension package for worktree management | `pi install npm:@monopi/extension-worktree` | | [`@monopi/background-tasks`](./packages/monopi__background-tasks) | Reactive background shell tasks with `/bg`, `Ctrl+Shift+B`, and `bg_task` | `pi install npm:@monopi/background-tasks` | | [`@monopi/diagnostics`](./packages/monopi__diagnostics) | Prompt completion timing extension | `pi install npm:@monopi/diagnostics` | | [`@monopi/subagents`](./packages/monopi__subagents) | Full-featured subagent delegation runtime | `pi install npm:@monopi/subagents` | | [`@monopi/web-remote`](./packages/monopi__web-remote) | `/remote` session sharing extension | `pi install npm:@monopi/web-remote` | | [`@monopi/adaptive-routing`](./packages/monopi__adaptive-routing) | Optional adaptive + delegated routing | `pi install npm:@monopi/adaptive-routing` | | [`@monopi/provider-catalog`](./packages/monopi__provider-catalog) | Experimental OpenCode-backed provider catalog | `pi install npm:@monopi/provider-catalog` | | [`@monopi/provider-cursor`](./packages/monopi__provider-cursor) | Experimental Cursor OAuth provider | `pi install npm:@monopi/provider-cursor` | | [`@monopi/provider-ollama`](./packages/monopi__provider-ollama) | Experimental Ollama local + cloud provider | `pi install npm:@monopi/provider-ollama` | | [`@monopi/skills`](./packages/monopi__skills) | 3 maintained skill packs | `pi install npm:@monopi/skills` | | [`@monopi/agents`](./packages/monopi__agents) | 5 AGENTS.md templates | (used by CLI/templates) | | [`@monopi/shared-qna`](./packages/monopi__shared-qna) | Shared Q&A TUI helpers | (library, not installed directly) | | [`@monopi/web-client`](./packages/monopi__web-client) | Platform-agnostic remote session client library | `pnpm add @monopi/web-client` | | [`@monopi/web-server`](./packages/monopi__web-server) | Embeddable remote session server | `pnpm add @monopi/web-server` | | [`@monopi/analytics-extension`](./packages/monopi__analytics-extension) | Analytics tracking extension with SQLite persistence and browser dashboard | `pi install npm:@monopi/analytics-extension` | | [`@monopi/analytics-db`](./packages/monopi__analytics-db) | SQLite schema and Drizzle ORM client for analytics data | (library, not installed directly) | | [`@monopi/analytics-dashboard`](./packages/monopi__analytics-dashboard) | React dashboard for visualizing AI usage (private package) | (private, run `pnpm dev` in package) | | [`@monopi/docs`](./packages/monopi__docs) | Documentation site for monopi (private package) | (private, run `pnpm dev` in package) | `@monopi/adaptive-routing`, `@monopi/provider-catalog`, `@monopi/provider-cursor`, `@monopi/provider-ollama`, and `@monopi/analytics-extension` stay opt-in for now and are **not** installed by `npx @monopi/monopi`. They are intentionally shipped as separate optional packages. ### Full Feature Catalog For a package-by-package inventory of everything in the repo โ€” including every extension, runtime package, skill, theme, AGENTS template, and contributor-facing library โ€” see [docs/feature-catalog.md](./docs/feature-catalog.md). ### Installer Options ```bash npx @monopi/monopi # install latest versions (global) npx @monopi/monopi --version 0.2.13 # pin to a specific version npx @monopi/monopi --local # install to project .pi/settings.json npx @monopi/monopi --remove # uninstall all monopi packages from pi ``` ### Compatibility Policy monopi tracks upstream pi fairly closely and currently treats **pi `0.56.1` or newer** as the minimum supported runtime baseline for packages that integrate directly with the pi SDK. Policy: - new monopi releases target the current pi runtime family first - compatibility with older pi builds is best-effort unless explicitly documented otherwise - peer dependency ranges on pi-facing packages express the minimum supported baseline more clearly - higher-risk runtime integrations should gain smoke coverage before broadening compatibility claims - CI smoke-checks both the minimum supported baseline (`0.56.1`) and a pinned current upstream runtime (`0.64.0`) ### Documentation reuse with MDT This repo uses [MDT](https://github.com/ifiokjr/mdt) to keep selected markdown sections and exported TypeScript API docs synchronized from shared provider blocks under `docs/mdt/`. Use MDT through `pnpm mdt ...`, not a globally installed `mdt` binary. This keeps documentation reuse commands pinned to the repo's declared `@ifi/mdt` version and makes local runs, CI, and agent instructions consistent. ```bash pnpm mdt list pnpm mdt update pnpm mdt check ``` Convenience wrappers remain available too: ```bash pnpm docs:list pnpm docs:update pnpm docs:check ``` CI runs `pnpm mdt check` so provider and consumer blocks stay in sync with the repo-pinned MDT version. --- ## Configuration ### Plain Icons (disable emoji) If emoji icons render poorly in your terminal (wrong font, garbled glyphs, misaligned widths), you can switch to ASCII-safe fallbacks. All emoji like ๐Ÿœ โœ… โŒ ๐Ÿš€ become plain text like `[ant]` `[ok]` `[ERR]` `[>>]`. Three ways to enable (in priority order): **1. Environment variable** (highest priority) ```bash export OH_PI_PLAIN_ICONS=1 # add to ~/.bashrc or ~/.zshrc ``` **2. CLI flag** (per session) ```bash pi --plain-icons ``` **3. settings.json** (persistent, recommended) Add `"plainIcons": true` to your global or project-local settings: ```bash # Global โ€” applies to all projects echo ' "plainIcons": true' >> ~/.pi/agent/settings.json # Or project-local โ€” applies only to this repo echo ' "plainIcons": true' >> .pi/settings.json ``` ```jsonc // ~/.pi/agent/settings.json { "defaultProvider": "anthropic", "defaultModel": "claude-sonnet-4", "plainIcons": true, // ... } ``` --- ## Extensions ### ๐Ÿ“ฆ Git Guard (`git-guard`) โ€” **default: on** Prevents accidental code loss by auto-creating stash checkpoints before the agent makes changes. Warns when the repo is dirty (uncommitted changes) and notifies when operations complete. **How it works:** On `session_start`, checks `git status`. If dirty, creates `git stash` with a timestamped name. On `tool_result` for write/edit operations, tracks changed files. ### ๐Ÿ“Š Custom Footer (`custom-footer`) โ€” **default: on** Replaces the default pi footer with a rich status bar showing real-time metrics: ``` โ—† claude-sonnet-4 | 12.3k/8.1k $0.42 62% | โฑ3m12s | โŒ‚ projects/monopi | โŽ‡ main ``` **Shows:** Model name with thinking-level indicator, input/output tokens, accumulated cost, context window %, elapsed time, working directory, git branch, and repo/worktree context when available. **How it works:** Uses `ctx.ui.setFooter()` with a component that reads `ctx.sessionManager.getBranch()` for token/cost data and `footerData.getGitBranch()` for git info. Auto-refreshes every 30s. ### โฑ Diagnostics (`diagnostics`) โ€” **default: on** Adds prompt-level completion diagnostics so you can see when a prompt started, when it finished, how long it took, and how each assistant turn progressed. **Surfaces:** - widget below the editor showing the active prompt or the last completed prompt - session log entry after each prompt finishes with human-readable start/end timestamps - expanded per-turn timing details for prompts that needed multiple assistant turns - `Ctrl+Shift+D` shortcut and `/diagnostics [status|toggle|on|off]` **How it works:** Reuses the same timestamp/duration formatting as `tool-metadata`, tracks `before_agent_start`, `turn_end`, and `agent_end`, then emits a custom diagnostic message when the agent goes idle for that prompt. ### ๐Ÿงพ Tool Metadata (`tool-metadata`) โ€” **default: on** Enriches tool results with execution metadata so pi can show when a tool started, when it finished, how long it took, and roughly how much text went in or out. **Adds:** start/end timestamps, duration, approximate input/output sizing, and a context snapshot at completion. It also sanitizes oversized tool output/details payloads so the TUI stays stable even when tools return huge text blobs. **How it works:** Hooks tool calls/results centrally and appends structured metadata to tool result `details`, which other features like diagnostics can reuse for consistent timing displays. ### โšก Compact Header (`compact-header`) โ€” **default: on** Replaces the verbose default startup header with a dense one-liner showing model, provider, thinking level, and extension count. ### โŒจ๏ธ External Editor (`external-editor`) โ€” **default: on** Adds a discoverable `/external-editor` command and a `Ctrl+Shift+E` shortcut for opening the current draft in `$VISUAL` or `$EDITOR`, then syncing the saved text back into pi. **Commands:** `/external-editor` | `/external-editor status` **Notes:** This complements pi's built-in `app.editor.external` binding (`Ctrl+G` by default). Users who want a different primary key can still remap that binding in `keybindings.json`. ### ๐ŸŒฒ Worktree (`worktree`) โ€” **default: on** Adds centralized git worktree awareness for monopi. It detects whether the current checkout is the main repo or a linked worktree, shows when the current worktree is pi-owned, and tracks owner + purpose metadata for pi-created worktrees. **Commands:** `/worktree` | `/worktree status` | `/worktree list` | `/worktree open [branch|path]` | `/worktree create [purpose]` | `/worktree cleanup ` **Behavior:** pi-owned worktrees are created under shared pi storage, namespaced by the canonical repo root. Cleanup focuses on pi-owned worktrees only and leaves external/manual worktrees alone unless you explicitly intervene. ### ๐Ÿ“… Scheduler (`scheduler`) โ€” **default: on** Adds first-class reminders, recurring follow-ups, and future check-ins to pi. **Commands:** `/remind in 45m ` | `/loop 5m ` | `/loop cron '*/5 * * * *' ` | `/schedule` | `/schedule tui` | `/schedule list` | `/schedule enable ` | `/schedule disable ` | `/schedule delete ` | `/schedule clear` | `/schedule clear-other` | `/schedule adopt ` | `/schedule release ` | `/schedule clear-foreign` **Tool:** `schedule_prompt` **Behavior:** tasks run only while pi is active and idle, persist under shared pi storage, default to instance scope, and can opt into workspace scope for shared CI/build/deploy monitors. Use `continueUntilComplete` when a follow-up should keep retrying until a success marker appears. ### ๐Ÿ’ฌ BTW / QQ (`btw`) โ€” **default: on** Creates a side-conversation widget above the editor so you can ask follow-up questions, think in parallel, or park a tangent without interrupting the main thread. **Commands:** `/btw` | `/btw new` | `/btw clear` | `/btw inject` | `/btw summarize` and the alias set `/qq`, `/qq new`, `/qq clear`, `/qq inject`, `/qq summarize` **Behavior:** keep a lightweight parallel thread, then either inject the full exchange into the main agent or inject a generated summary instead. ### โณ Background Tasks (`@monopi/background-tasks`) โ€” **default: on** Manages explicit background tasks for long-lived commands like dev servers, PR watchers, and log followers. Ordinary `bash` commands stay in the foreground so their output remains visible in the current pi session. **How it works:** Use `bg_task` or `/bg` when you want a command to keep running after the tool returns. Background tasks write output to `/tmp/monopi-bg-*.log`, can wake pi up on new output, and can be inspected or stopped later with `bg_status`, `bg_task`, or the `/bg` dashboard. ``` Agent: bg_task spawn "npm run dev" โ†’ Started bg-1 (pid 12345) in the background. Log: /tmp/monopi-bg-bg-1-1709654321.log โณ Pi can notify you when new output arrives or when the task exits. ``` **Commands:** `bg_status list` | `bg_status log --pid 12345` | `bg_status stop --pid 12345` ### ๐Ÿงญ Adaptive Routing (`adaptive-routing`) โ€” **optional package** Adaptive routing now ships as its own package so users can opt into routing behavior explicitly: ```bash pi install npm:@monopi/adaptive-routing ``` It adds `/route` controls, local routing telemetry, and delegated startup categories that subagents can use for provider assignment when no explicit model override is set. ### ๐Ÿ’ฐ Usage Tracker (`usage-tracker`) โ€” **default: off** The usage-tracker extension is a CodexBar-inspired provider quota and cost monitor for pi. It shows provider-level rate limits for Anthropic, OpenAI, and Google using pi-managed auth, while also tracking per-model token usage and session costs locally. Usage-tracker persists rolling 30-day cost history and the last known provider rate-limit snapshot under the pi agent directory. That lets the widget and dashboard survive restarts and keep showing recent subscription windows when a live provider probe is temporarily rate-limited or unavailable. **Widget** (always visible above editor): ``` Claude [โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘] 67% โ†ปin 3d 2h โ”‚ ๐Ÿ’ฐ$0.42 โ”‚ 12.3k/8.1k ``` **`/usage` overlay** (`Ctrl+Shift+U`): ``` โ•ญโ”€ Usage Dashboard โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ โ–ธ Claude Rate Limits Weekly (all) [โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘] 67% left (33% used) โ€” resets in 3d 2h Pace: On pace | Expected 31% used | Lasts until reset Session [โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘] 82% left (18% used) โ€” resets in 2h 5m Most constrained: Weekly (all) (67% left) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ Session โ”‚ 23m12s โ”‚ 14 turns โ”‚ $0.42 Tokens โ”‚ 45.2k in โ”‚ 18.7k out โ”‚ 63.9k total Avg โ”‚ 4.6k tok/turn โ”‚ $0.030/turn Cache โ”‚ 12.4k read โ”‚ 1.8k write โ”‚ 27% read/input Per-Model Breakdown โ—† claude-sonnet-4 (anthropic) [โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ] $0.38 โ”‚ 12 turns โ”‚ 40.1k in / 16.2k out โ”‚ 90% of cost avg 4.7k tok/turn โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ ``` Key usage-tracker surfaces: - widget above the editor for at-a-glance quotas and session totals - `/usage` for the full dashboard overlay - `Ctrl+Shift+U` as a shortcut for the same overlay - `/usage-toggle` to show or hide the widget - `/usage-refresh` to force fresh provider probes - `usage_report` so the agent can answer quota and spend questions directly ### ๐Ÿ›ก๏ธ Watchdog + Safe Mode (`watchdog`) โ€” **default: on** Continuously samples runtime health so heavy sessions stay usable. **Commands:** `/watchdog` | `/watchdog status` | `/watchdog startup` | `/watchdog overlay` | `/watchdog dashboard` | `/watchdog config` | `/watchdog reset` | `/watchdog on` | `/watchdog off` | `/watchdog sample` | `/watchdog blame` | `/safe-mode [on|off|status]` **Behavior:** tracks CPU, memory, and event-loop lag; records recent samples and alerts; and can escalate into safe mode when repeated alerts suggest sustained UI churn. The optional config file lives at `~/.pi/agent/extensions/watchdog/config.json`. --- ## Setup Modes | Mode | Steps | For | | ------------- | ----- | --------------------------------- | | ๐Ÿš€ **Quick** | 3 | Pick provider โ†’ enter key โ†’ done | | ๐Ÿ“ฆ **Preset** | 2 | Choose a role profile โ†’ enter key | | ๐ŸŽ›๏ธ **Custom** | 6 | Pick everything yourself | ### Presets | | Theme | Thinking | Includes | | ------------- | ----------- | -------- | -------------------------------------- | | โšซ Full Power | monopi Dark | high | Recommended extensions | | ๐Ÿ”ด Clean | Default | off | No extensions, just core | | ๐Ÿš€ Subagents | monopi Dark | medium | Subagent chains and parallel execution | ### Providers Anthropic ยท OpenAI ยท Google Gemini ยท Groq ยท OpenRouter ยท xAI ยท Mistral --- ## Skills | Skill | What it does | | -------------- | ----------------------------------------------------- | | `btw` (`/qq`) | Run side conversations without interrupting main work | | `debug-helper` | Error analysis, log interpretation, and profiling | | `nushell` | Nushell syntax reference for shell commands | ## Themes | Theme | Description | | ------------------- | ---------------------------- | | ๐ŸŒ™ monopi Dark | Cyan + purple, high contrast | | ๐ŸŒ™ Cyberpunk | Neon magenta + electric cyan | | ๐ŸŒ™ Nord | Arctic blue palette | | ๐ŸŒ™ Catppuccin Mocha | Pastel on dark | | ๐ŸŒ™ Tokyo Night | Blue + purple twilight | | ๐ŸŒ™ Gruvbox Dark | Warm retro tones | --- ## Development ### Prerequisites - Node.js โ‰ฅ 20 - pnpm โ‰ฅ 10 - MonoChange CLI (`pnpm mc:*` scripts) for releases ### Setup ```bash git clone https://github.com/ifiokjr/monopi.git cd monopi pnpm install ``` Most runtime packages in this repo ship raw TypeScript and can be loaded directly by pi. A smaller set of contributor-facing packages (`core`, `cli`, `db`, `web-client`, `web-server`) emit `dist/` output, so build those when you are working on them directly. See [CONTRIBUTING.md](./CONTRIBUTING.md) for contributor workflow, changeset requirements, and PR guidelines. ### Commands ```bash pnpm build # Build every workspace package that exposes a build script pnpm typecheck # Type check with tsgo (fast) pnpm test # Run all tests pnpm test:coverage # Run tests with repo-wide coverage reporting pnpm test:patch-coverage # Enforce 100% patch coverage from coverage/lcov.info pnpm lint # oxlint + oxfmt check pnpm security:check # Dependency allowlist + vulnerability audits pnpm lint:fix # Auto-fix lint issues pnpm format # Format all files ``` ### Coverage policy - Overall/project coverage is currently enforced at **60%**. - Patch coverage for new PR changes is enforced at **100%**. - The local contributor loop for coverage-sensitive work is: ```bash pnpm test:coverage pnpm test:patch-coverage ``` That keeps the repo-wide floor honest while still requiring new code paths in a PR to be fully covered. CI uses the same `pnpm test:patch-coverage` command on pull requests, so local results and CI results stay aligned. ### Running locally & local development The `pnpm pi:local` workflow points a real pi install at this checkout instead of the published npm packages. It is the normal local development loop for testing unpublished monopi changes in a real interactive pi session. #### Quick start ```bash pnpm install pnpm pi:local pi ``` That is the normal developer loop for monopi feature work. #### What `pnpm pi:local` does `pnpm pi:local` runs the repo-local source switcher in `local` mode. It: - rewrites only the managed monopi package sources in your pi settings - points those package sources at the workspace packages in this checkout - preserves package-specific config objects already present in `settings.json` - refreshes package manifest paths so newly added extensions/skills/themes are picked up - runs `pi install` for newly added managed packages and `pi update` for packages you already had configured - manages the default installer set and the opt-in experimental packages used for local feature development - lets you validate unpublished changes from a branch, worktree, or detached checkout before release Managed local switching covers these packages: - `@monopi/extension-worktree` - `@monopi/background-tasks` - `@monopi/diagnostics` - `@monopi/subagents` - `@monopi/web-remote` - `@monopi/skills` - `@monopi/adaptive-routing` - `@monopi/provider-catalog` - `@monopi/provider-cursor` - `@monopi/provider-ollama` - `@monopi/analytics-extension` #### Common commands ```bash pnpm pi:local # point pi at this checkout pnpm pi:published # switch back to published npm packages pnpm pi:switch local -- --path /tmp/monopi-branch pnpm pi:switch remote -- --version 0.4.4 pnpm pi:switch local -- --pi-local # write into the current project's .pi/settings.json pnpm pi:switch status # show the current managed package sources ``` #### Typical local workflow 1. `pnpm install` 2. `pnpm pi:local` 3. Fully restart `pi` 4. Exercise the feature in a real pi session 5. Make changes in this repo 6. Restart `pi` again when the package source or loaded modules need a clean reload 7. Switch back with `pnpm pi:published` when you want the published packages again #### Important restart note After switching package sources, fully restart `pi`. Do not rely on `/reload` for source switches, because it can keep previously loaded package modules alive. #### When to re-run installs or builds If you recently pulled, rebased, or switched branches in the checkout you pointed `pi` at, run `pnpm install --frozen-lockfile` there before restarting `pi`. Local source mode loads workspace files directly, so stale `node_modules` can surface missing internal `@monopi/*` package errors. If you are changing one of the compiled contributor packages (`@monopi/core`, `@monopi/cli`, `@monopi/web-client`, or `@monopi/web-server`), also run the relevant build command or `pnpm build` so their emitted `dist/` output stays current. ### Changesets **Every change must include a changeset.** This is enforced in CI. ```bash pnpm change ``` This creates a file in `.changeset/` describing the change. Because this repo uses MonoChange with a lockstep `default` group, changeset frontmatter must use **only** `default` as the key: ```md --- default: patch --- ``` Do not use package names like `@monopi/monopi` or `@monopi/extension-worktree` in changeset frontmatter here โ€” MonoChange validates changesets against the configured `default` release group. Choose the change type: - **`major`** โ€” Breaking changes - **`minor`** โ€” New features - **`patch`** โ€” Bug fixes ### Releasing Releases are done locally in two steps: ```bash # 1. Release: bump versions, update CHANGELOG.md, tag, push ./scripts/release.sh # 2. Publish: build and push all packages to npm pnpm publish ``` The release script runs all CI/security checks (lint, security, typecheck, test, build) before calling `pnpm release`. Use `--dry-run` to preview without making changes. ### Project Structure ``` monopi/ โ”œโ”€โ”€ packages/ โ”‚ โ”œโ”€โ”€ monopi__core/ Shared types, registries, icons, i18n, and path helpers (compiled) โ”‚ โ”œโ”€โ”€ monopi__cli/ Interactive TUI configurator (compiled) โ”‚ โ”œโ”€โ”€ monopi__extension-*/ Split pi extension packages โ”‚ โ”œโ”€โ”€ monopi__background-tasks/ Reactive background shell task package (raw .ts) โ”‚ โ”œโ”€โ”€ monopi__diagnostics/ Prompt completion timing extension (raw .ts) โ”‚ โ”œโ”€โ”€ monopi__subagents/ Subagent orchestration package (raw .ts) โ”‚ โ”œโ”€โ”€ monopi__adaptive-routing/ Optional adaptive/delegated routing package (raw .ts) โ”‚ โ”œโ”€โ”€ monopi__provider-catalog/ Provider catalog package (raw .ts) โ”‚ โ”œโ”€โ”€ monopi__provider-cursor/ Cursor OAuth provider package (raw .ts) โ”‚ โ”œโ”€โ”€ monopi__provider-ollama/ Ollama local + cloud provider package (raw .ts) โ”‚ โ”œโ”€โ”€ monopi__web-remote/ `/remote` session sharing extension (raw .ts) โ”‚ โ”œโ”€โ”€ monopi__web-client/ Remote session client library (compiled) โ”‚ โ”œโ”€โ”€ monopi__web-server/ Remote session server library (compiled) โ”‚ โ”œโ”€โ”€ monopi__shared-qna/ Shared Q&A TUI helper library (raw .ts) โ”‚ โ”œโ”€โ”€ monopi__analytics-db/ SQLite schema and Drizzle ORM client for analytics data โ”‚ โ”œโ”€โ”€ monopi__analytics-dashboard/ React dashboard for visualizing AI usage (private app) โ”‚ โ”œโ”€โ”€ monopi__analytics-extension/ Analytics tracking extension for pi (raw .ts) โ”‚ โ”œโ”€โ”€ monopi__docs/ Documentation site for monopi (private app) โ”‚ โ”œโ”€โ”€ monopi__skills/ Curated skill directories โ”‚ โ”œโ”€โ”€ monopi__agents/ AGENTS.md templates โ”‚ โ””โ”€โ”€ monopi__monopi/ Installer CLI (npx @monopi/monopi) โ”œโ”€โ”€ docs/ Full documentation โ”œโ”€โ”€ benchmarks/ Performance benchmarks โ”œโ”€โ”€ .changeset/ Pending MonoChange changesets โ”œโ”€โ”€ CHANGELOG.md Release history โ”œโ”€โ”€ monochange.toml Release automation config โ””โ”€โ”€ .oxlintrc.json + .oxfmtrc.json Linter + formatter config ``` ## License MIT