monopi

monopi

One command to install and configure pi-coding-agent.

Like oh-my-zsh for pi.

npx @monopi/monopi

---

30-Second Start

npx @monopi/monopi       # install the default monopi bundle
pi                    # start coding

monopi installs the full bundle into pi in one command. See 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

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:

pi install https://github.com/<you>/monopi@<tag-or-commit>

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	Meta-installer for the default monopi bundle	npx @monopi/monopi
monopi	Unscoped npm alias for @monopi/monopi	npx monopi
@monopi/cli	Interactive TUI configurator	npx @monopi/cli
@monopi/core	Shared types, registries, icons, i18n, and path helpers	(library, not installed directly)
@monopi/db	Shared SQLite/Drizzle database for persistence-based extensions	(library, not installed directly)
@monopi/extension-worktree	Split extension package for worktree management	pi install npm:@monopi/extension-worktree
@monopi/background-tasks	Reactive background shell tasks with /bg, Ctrl+Shift+B, and bg_task	pi install npm:@monopi/background-tasks
@monopi/diagnostics	Prompt completion timing extension	pi install npm:@monopi/diagnostics
@monopi/subagents	Full-featured subagent delegation runtime	pi install npm:@monopi/subagents
@monopi/web-remote	/remote session sharing extension	pi install npm:@monopi/web-remote
@monopi/adaptive-routing	Optional adaptive + delegated routing	pi install npm:@monopi/adaptive-routing
@monopi/provider-catalog	Experimental OpenCode-backed provider catalog	pi install npm:@monopi/provider-catalog
@monopi/provider-cursor	Experimental Cursor OAuth provider	pi install npm:@monopi/provider-cursor
@monopi/provider-ollama	Experimental Ollama local + cloud provider	pi install npm:@monopi/provider-ollama
@monopi/skills	3 maintained skill packs	pi install npm:@monopi/skills
@monopi/agents	4 AGENTS.md templates	(used by CLI/templates)
@monopi/shared-qna	Shared Q&A TUI helpers	(library, not installed directly)
@monopi/web-client	Platform-agnostic remote session client library	pnpm add @monopi/web-client
@monopi/web-server	Embeddable remote session server	pnpm add @monopi/web-server
@monopi/analytics-extension	Analytics tracking extension with SQLite persistence and browser dashboard	pi install npm:@monopi/analytics-extension
@monopi/analytics-db	SQLite schema and Drizzle ORM client for analytics data	(library, not installed directly)
@monopi/analytics-dashboard	React dashboard for visualizing AI usage (private package)	(private, run pnpm dev in package)
@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 (every extension, runtime package, skill, theme, AGENTS template, and contributor-facing library), see docs/feature-catalog.md.

Installer Options

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 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.

pnpm mdt list
pnpm mdt update
pnpm mdt check

Convenience wrappers remain available too:

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. Emoji like ✅ ❌ 🚀 become plain text like [ok] [ERR] [>>].

Three ways to enable (in priority order):

1. Environment variable (highest priority)

export OH_PI_PLAIN_ICONS=1    # add to ~/.bashrc or ~/.zshrc

2. CLI flag (per session)

pi --plain-icons

3. settings.json (persistent, recommended)

Add "plainIcons": true to your global or project-local settings:

# 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

// ~/.pi/agent/settings.json
{
	"defaultProvider": "anthropic",
	"defaultModel": "claude-sonnet-4",
	"plainIcons": true,
	// ...
}

---

Extensions

Git Guard (git-guard), on by default

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), on by default

Replaces the default pi footer with a rich status bar showing real-time metrics: