---
slug: "pi-unipi-core"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/Neuron-Mr-White/unipi@main/README.md"
repo: "https://github.com/Neuron-Mr-White/unipi"
source_file: "README.md"
branch: "main"
---
# Unipi

20 workspace packages that turn Pi into a full development workstation. Structured workflows, persistent memory, parallel agents, web research, notifications, context management, command autocomplete, and a live status bar — all wired together through a shared event system.

One command installs everything:
```bash
pi install npm:@pi-unipi/unipi
```

## What You Get

**[Workflow](https://github.com/Neuron-Mr-White/unipi/blob/HEAD/packages/workflow/README.md)** — 20 commands that take ideas to shipped code. Brainstorm, plan, execute in worktrees, review, consolidate. The agent follows skill files step by step.

**[Ralph](https://github.com/Neuron-Mr-White/unipi/blob/HEAD/packages/ralph/README.md)** — Long-running loops that persist across sessions. Start a task, iterate through checklist items, resume after crashes. Progress tracked, state saved.

**[Memory](https://github.com/Neuron-Mr-White/unipi/blob/HEAD/packages/memory/README.md)** — SQLite + vector search stores facts, preferences, and decisions. Project-scoped and global. The agent remembers what you told it last week.

**[Compactor](https://github.com/Neuron-Mr-White/unipi/blob/HEAD/packages/compactor/README.md)** — Zero-LLM context engine. 6-stage pipeline hits 95%+ token reduction at zero API cost. Session continuity, percentage auto-compaction, session recall, and sandbox execution.

**[CocoIndex](https://github.com/Neuron-Mr-White/unipi/blob/HEAD/packages/cocoindex/README.md)** — Project indexing and semantic code search backed by CocoIndex and LanceDB. Agent tools and slash commands for status, init, update, and search.

**[Subagents](https://github.com/Neuron-Mr-White/unipi/blob/HEAD/packages/subagents/README.md)** — Parallel execution with file locking. Spawn background agents to research, fix, or build while the main agent keeps going.

**[Web API](https://github.com/Neuron-Mr-White/unipi/blob/HEAD/packages/web-api/README.md)** — Web search, page reading, content summarization. Smart-fetch engine with browser-grade TLS fingerprinting — free, no API key. Paid providers as fallbacks.

**[MCP](https://github.com/Neuron-Mr-White/unipi/blob/HEAD/packages/mcp/README.md)** — Browse 7,800+ MCP servers, add them interactively. Tools from servers register automatically as Pi tools.

**[Notify](https://github.com/Neuron-Mr-White/unipi/blob/HEAD/packages/notify/README.md)** — Push notifications to native OS, Gotify, Telegram, or ntfy. Per-event platform routing plus native focus suppression so alerts can stay quiet while Pi is already focused.

**[Footer](https://github.com/Neuron-Mr-White/unipi/blob/HEAD/packages/footer/README.md)** — Persistent status bar showing live stats from every package. Responsive layout, presets, per-segment toggling, and terminal-aware color fallback.

**[BTW](https://github.com/Neuron-Mr-White/unipi/blob/HEAD/packages/btw/README.md)** — Side conversations that run in parallel. Ask questions without interrupting the main agent.

**[Ask User](https://github.com/Neuron-Mr-White/unipi/blob/HEAD/packages/ask-user/README.md)** — Structured input for decision gates. Single-select, multi-select, freeform. The agent asks instead of guessing.

**[Milestone](https://github.com/Neuron-Mr-White/unipi/blob/HEAD/packages/milestone/README.md)** — Track project goals across workflow cycles. MILESTONES.md stays in sync with specs, plans, and completed work.

**[Kanboard](https://github.com/Neuron-Mr-White/unipi/blob/HEAD/packages/kanboard/README.md)** — Web UI and TUI overlay for kanban boards. Parses all workflow documents into cards with progress indicators.

**[Info Screen](https://github.com/Neuron-Mr-White/unipi/blob/HEAD/packages/info-screen/README.md)** — Dashboard overlay showing module status, tools, and custom data groups.

**[Utility](https://github.com/Neuron-Mr-White/unipi/blob/HEAD/packages/utility/README.md)** — Environment info, diagnostics, cleanup, name badge, and Shiki-powered diff rendering.

**[Updater](https://github.com/Neuron-Mr-White/unipi/blob/HEAD/packages/updater/README.md)** — Checks npm for new versions on session start. Changelog browser and readme browser in TUI overlays.

**[Input Shortcuts](https://github.com/Neuron-Mr-White/unipi/blob/HEAD/packages/input-shortcuts/README.md)** — Keyboard shortcuts via vim-style chord overlay. Stash/restore, undo/redo, clipboard, thinking toggle.

**[Command Enchantment](https://github.com/Neuron-Mr-White/unipi/blob/HEAD/packages/autocomplete/README.md)** — Enhanced `/unipi:*` autocomplete with full command names, package tags, descriptions, colors, and registry audits that catch stale command docs before release.

## Architecture

Packages discover each other through events, not direct imports. Core defines the event types and constants. Every package emits `MODULE_READY` on load and subscribes to events it cares about.

```
┌─────────────────────────────────────────────────────────┐
│                        Core                             │
│              Events, Constants, Utilities                │
└───────────────────────┬─────────────────────────────────┘
                        │
    ┌───────────────────┼───────────────────┐
    │                   │                   │
    ▼                   ▼                   ▼
┌─────────┐       ┌──────────┐       ┌──────────┐
│ Workflow │       │ Compactor│       │  Memory  │
│  Skills  │       │  Engine  │       │  Store   │
└────┬─────┘       └────┬─────┘       └────┬─────┘
     │                  │                  │
     └──────────────────┼──────────────────┘
                        ▼
                  ┌──────────┐
                  │  Footer  │ ← Subscribes to all events
                  └──────────┘
```

Coexists triggers enhance behavior when packages are installed together. Workflow skills detect subagents and inject parallel strategies. All skills get MCP tools when MCP is installed. Web-api adds web research to investigation skills. Each package works standalone.

## Commands (Brief)

| Category | Prefix | Examples |
|----------|--------|----------|
| Workflow | `/unipi:` | brainstorm, plan, work, review-work, consolidate, quick-work, debug, fix |
| Ralph | `/unipi:ralph` | start, stop, resume, status |
| Memory | `/unipi:memory-` | process, search, consolidate, forget |
| Compactor | `/unipi:` | lossless-compact, session-recall, compact-stats, compact-settings, compact-preset, compact-help |
| CocoIndex | `/unipi:cocoindex-` | init, update, status, search, settings |
| Notify | `/unipi:notify-` | settings, test, set-tg, set-ntfy |
| MCP | `/unipi:mcp-` | add, settings, sync, status |
| Web | `/unipi:web-` | settings, cache-clear |
| BTW | `/unipi:btw` | question, btw-new, btw-tangent, btw-inject, btw-summarize |
| Utility | `/unipi:` | env, doctor, status, cleanup, badge-name |
| Milestone | `/unipi:milestone-` | onboard, update |
| Kanboard | `/unipi:kanboard` | toggle, doctor |
| Footer | `/unipi:footer` | toggle, settings |
| Updater | `/unipi:` | readme, changelog, updater-settings |
| Info | `/unipi:info` | dashboard, settings |

## Agent Tools (Brief)

| Tool | Package | What It Does |
|------|---------|--------------|
| `ralph_start` / `ralph_done` | ralph | Loop control |
| `spawn_helper` / `get_helper_result` | subagents | Parallel agents |
| `memory_store` / `memory_search` / `memory_delete` | memory | Memory CRUD |
| `web_search` / `web_read` / `web_llm_summarize` | web-api | Web research |
| `notify_user` | notify | Push notifications |
| `ask_user` | ask-user | User input |
| `compact` / `session_recall` / `sandbox` | compactor | Context management |
| `ctx_batch` / `ctx_env` | utility | Batch execution, env info |

## Development

```bash
git clone https://github.com/Neuron-Mr-White/unipi.git
cd unipi
npm install
npm run typecheck
```

### Project Structure

```
unipi/
├── packages/
│   ├── core/           # Shared constants, events, utilities
│   ├── workflow/       # 20 skill-based commands
│   ├── ralph/          # Iterative loops
│   ├── memory/         # SQLite + vector search
│   ├── compactor/      # Context engine
│   ├── cocoindex/      # Project indexing and semantic search
│   ├── subagents/      # Parallel execution
│   ├── web-api/        # Web research
│   ├── mcp/            # MCP server integration
│   ├── notify/         # Push notifications
│   ├── footer/         # Status bar
│   ├── btw/            # Side conversations
│   ├── ask-user/       # Structured input
│   ├── milestone/      # Goal tracking
│   ├── kanboard/       # Kanban visualization
│   ├── info-screen/    # Dashboard overlay
│   ├── utility/        # Diagnostics, diff rendering
│   ├── updater/        # Auto-update, browsers
│   ├── input-shortcuts/ # Keyboard shortcuts
│   ├── autocomplete/   # Enhanced command autocomplete
│   └── unipi/          # Umbrella package
├── .unipi/             # Runtime data (specs, plans, worktrees)
└── CHANGELOG.md
```

### Adding a Package

1. Create `packages/your-package/` with `package.json` and `index.ts`
2. Depend on `@pi-unipi/core` for constants and events
3. Emit `MODULE_READY` on load
4. Add to umbrella package dependencies and imports
5. Run `npm run typecheck`

### Running Tests

```bash
npm test
```

## Contributing

1. Fork the repo
2. Create a feature branch
3. Make your changes
4. Run `npm run typecheck` and `npm test`
5. Submit a pull request

Keep packages focused. One package, one responsibility. Use events for cross-package communication — no direct imports between packages.

## License

MIT