Overview

System: Unipi — extension suite for the Pi coding agent
C4 Level: System Context (Level 1)
Document generated: 2026-09-16 06:51:20 (UTC)

1. Project Introduction

1.1 Project Name and Description

Unipi is a TypeScript monorepo containing approximately 25 extension packages, all published under the @pi-unipi/* scope, that plug into the Pi coding agent — a terminal-based AI coding assistant. Unipi is not a standalone application; it is a set of extensions that load into the Pi host process through Pi's ExtensionAPI. Each package registers tools (with TypeBox schemas), slash commands, lifecycle hooks, TUI overlays and footer/widget segments, and the umbrella package @pi-unipi/unipi composes them into a single working assistant at runtime.

1.2 Core Functionality and Business Value

Unipi extends a single terminal AI coding agent into a fuller development platform. Its capabilities cluster around five functional areas:

Business value in one sentence: developers get longer autonomous agent sessions (less context-window pressure), parallel and long-running task execution, memory that survives across sessions, and access to external tools and data — all without leaving one CLI.

1.3 Technical Characteristics

• Plugin-style, event-driven architecture. A thin shared kernel (@pi-unipi/core) supplies constants, an inter-module event bus (MODULE_READY discovery and feature events), sandbox primitives and TUI helpers. Every other package depends on core but remains independently loadable and config-gated.
• Loose cross-package coupling. Packages communicate primarily through core events and footer segments rather than direct imports; the notable exception is kanboard importing milestone types.
• Process-oriented delegation. Subagents and MCP servers run as OS child processes; Unipi tails their output, tracks usage, and can terminate whole process trees (including Windows taskkill).
• File- and SQLite-based persistence with crash-safe atomic writes for task artifacts, session events and compaction statistics.
• Deterministic compaction pipeline. A six-stage compile() pipeline (normalize → filterNoise → buildSections → formatSummary → merge → ranked brief) produces structured summaries rather than relying solely on model-generated summaries.

2. Target Users

2.1 User Roles

%% litho-mermaid
graph LR
    AgentUser["AI coding agent user - developer running Pi in a terminal"]
    ExtDev["Extension developer - maintains packages in the monorepo"]
    Team["Team using structured workflows"]
    Unipi["Unipi extension suite"]

    AgentUser -->|installs and uses tools, commands, TUI| Unipi
    ExtDev -->|builds packages against core contracts| Unipi
    Team -->|runs workflow, milestone and kanban tooling| Unipi

2.2 Usage Scenarios

3. System Boundaries

3.1 Scope Statement

The system boundary is the collection of @pi-unipi/* packages that load into the Pi coding agent, plus their on-disk state (task artifacts, session databases, memory stores). Everything the extensions register, render, persist or spawn is in scope. The Pi host itself, external model providers, third-party MCP server implementations and OS notification services are outside the boundary.

3.2 Included Components

3.3 Excluded Components

4. External System Interactions

4.1 External System Inventory

4.2 Interaction Descriptions

Pi coding agent (host). This is the single most important relationship: Unipi has no runtime without Pi. Packages register tools with TypeBox schemas, slash commands (e.g. /unipi compact, /unipi:model, /unipi:ralph), hooks (compaction, lifecycle, milestone), and TUI overlays. The footer package drives Pi's setFooter/setWidget APIs, and the fusion, image and compactor packages consume Pi's model registry. Pi lifecycle events feed the notify package.

MCP servers. ServerRegistry loads server configuration, starts each configured server as a child process, and McpClient performs the initialize handshake and listTools over stdio. The translator converts MCP tool definitions into Pi-compatible schemas with unique names and registers them. Partial failures are cleaned up so one broken server does not block others. Agent tool calls are proxied back to the owning server via callTool.

LLM and image model providers. Unipi never talks to providers directly for chat; it resolves models through Pi's registry (cached in core/model-cache). The image package additionally includes an OpenAI-images-style API client and a chat-provider-to-images bridge, with vision gating based on the active model.

MemPalace and SQLite. Memory uses MemPalace as its primary backend through a Python bridge, with a markdown durable tier and migration from legacy SQLite. The compactor's SessionDB uses SQLite for per-project events, sessions and compaction counters, including schema migration.

Web fetch stack. The extraction pipeline validates URLs, fetches via wreq-js (TLS fingerprinting), routes by content type, extracts with defuddle and fallbacks, detects meta-refresh, and caches results. Search dispatch goes through a provider registry selectable via a TUI.

Notification platforms. Notify subscribes to Pi lifecycle events and to feature events discovered dynamically via MODULE_READY (task completion, ralph loop start/end, ask-user prompts), builds message text with priority mapping and recap summarization, and dispatches to whichever platforms are enabled.

Operating system. Background tasks and subagents spawn child Pi processes, tail output, parse usage payloads, persist snapshots and terminate process trees. The DelegateArtifactStore writes seed/prompt/result artifacts with crash-safe atomic writes and manifests.

4.3 Dependency Analysis

5. System Context Diagram

5.1 C4 System Context

%% litho-mermaid
graph TD
    AgentUser["AI coding agent user"]
    ExtDev["Extension developer"]
    Team["Team using structured workflows"]

    subgraph Boundary["System boundary"]
        Unipi["Unipi extension suite - about 25 pi-unipi packages loaded into Pi"]
    end

    PiHost["Pi coding agent host - ExtensionAPI, TUI APIs, model registry, event bus"]
    MCP["MCP servers - child processes"]
    Models["LLM and image model providers"]
    MemPalace["MemPalace memory backend"]
    SQLite["SQLite session and stats store"]
    WebStack["wreq-js, defuddle and web search providers"]
    Notif["Notification platforms - native, ntfy, gotify, Telegram, focus"]
    OS["Operating system - processes and filesystem"]
    Browser["Web browser - kanban board viewer"]

    AgentUser -->|uses tools, slash commands, TUI in terminal| PiHost
    ExtDev -->|develops packages against core contracts| Unipi
    Team -->|runs workflow and milestone commands| PiHost

    PiHost -->|loads extensions via ExtensionAPI| Unipi
    Unipi -->|registers tools, commands, hooks, footer| PiHost
    Unipi -->|resolves models via Pi registry| Models
    Unipi -->|JSON-RPC over stdio| MCP
    Unipi -->|stores and recalls memories via Python bridge| MemPalace
    Unipi -->|persists session events and counters| SQLite
    Unipi -->|fetches, searches, extracts content| WebStack
    Unipi -->|dispatches notifications| Notif
    Unipi -->|spawns child Pi processes, writes artifacts| OS
    Unipi -->|serves kanban pages over HTTP| Browser
    Browser -->|viewed by| Team

5.2 Internal Domain View (context for the next level)

While the SystemContext level treats Unipi as a single box, the domain analysis reveals six internal domains connected through the core kernel. This view is provided to orient readers toward the Container level.

%% litho-mermaid
graph TD
    Core["Platform Core and Shared Infrastructure - core, utility, updater, unipi"]
    Orch["Agent Orchestration - subagents, background-tasks, ralph"]
    Ctx["Context and Memory Management - compactor, memory, trajectory"]
    Ext["External Capability Integration - mcp, web-api, image, fusion"]
    UI["User Interaction and Presentation - footer, ask-user, notify, input-shortcuts, info-screen, autocomplete, btw"]
    Flow["Structured Development Workflow - workflow, milestone, kanboard"]

    Orch -->|imports constants, events, sandbox| Core
    Ctx -->|imports events, TUI helpers| Core
    Ext -->|imports core, publishes fusion status| Core
    UI -->|imports events, reads fusion status| Core
    Flow -->|imports sandbox and events| Core

    UI -->|footer segments and notify subscribe| Orch
    UI -->|footer segments show compaction and memory| Ctx
    UI -->|footer mcp segment, model autocomplete| Ext
    UI -->|footer workflow and kanboard segments| Flow
    Orch -->|context policy and token budgets| Ctx
    Flow -->|optional ralph detection, workflowScripts| Orch

5.3 Key Interaction Flows

The following flows are ranked by importance in the domain analysis and illustrate how external systems participate.

Flow 1 — Subagent Delegation (importance 9.5)

%% litho-mermaid
sequenceDiagram
    participant LLM as Pi agent LLM
    participant SA as subagents tool-handler
    participant BT as background-tasks registry
    participant OS as OS child process
    participant Core as core event bus
    participant Notify as notify
    participant Footer as footer

    LLM->>SA: spawn_helper
    SA->>SA: resolve agent, aliases, depth guard, budgets, context policy
    SA->>BT: launch delegate
    BT->>OS: spawn child Pi process, write seed and prompt artifacts
    OS-->>BT: output tailed, usage payload parsed, snapshot persisted
    BT->>Core: task completion event
    Core->>Notify: event delivered
    Notify->>Notify: dispatch to enabled platforms
    Core->>Footer: segment refresh
    LLM->>SA: get_helper_result
    SA-->>LLM: truncated result package

Flow 2 — Context Compaction and Session Recall (importance 9.0)

1. A compaction hook, the /unipi compact command or the auto-trigger fires; the auto-trigger compares the token estimate against the budget (compactor/src/compaction/auto-trigger.ts).
2. compile() runs the six-stage pipeline: normalize → filterNoise → buildSections → formatSummary → merge, optionally producing a ranked brief.
3. SessionDB records events and compaction counters in SQLite.
4. The compactor footer segment displays compaction statistics.
5. On resume, resume-inject and the session_recall tool restore prior context.

Flow 3 — MCP Server Tool Bridging (importance 8.0)

1. Configuration is loaded and synced (mcp/src/config/manager.ts).
2. ServerRegistry prepares and starts servers, handling partial failures.
3. McpClient performs the initialize handshake and listTools over stdio.
4. The translator converts tools and registers them with Pi's ExtensionAPI.
5. The MCP footer segment shows active server and tool counts.

Flow 4 — Web Smart-Fetch (importance 6.5)

Tool invoked → provider selected from registry → URL validated, fetched via wreq-js, content-type routed, extracted with defuddle and fallbacks → result formatted and cached.

Flow 5 — Model Fusion Preset (importance 6.5)

/unipi:model → model registry resolved, picker overlay mounted → preset persisted, sidekick runtime spawned → fusion status (active pair, savings) published through core → footer core segment renders it.

Flow 6 — Structured Workflow with Kanban Board (importance 6.0)

Workflow command dispatched to a skill with sandbox enforcement → milestones created/updated via commands and hooks → ParserRegistry parses plan and milestone markdown; HTTP routes render board pages → footer workflow and kanboard segments reflect state.

Flow 7 — Interactive Ask-User (importance 6.0)

ask_user validates schema against the settings allow-list and normalizes options → prompt notification dispatched to platforms → TUI renderer collects the answer, or the launcher hands off to a new session → AskUserResponse returned.

5.4 Architecture Decisions Visible at the Context Level

6. Technical Architecture Overview

6.1 Technology Stack

6.2 Architecture Patterns

• Plugin / microkernel. @pi-unipi/core is the kernel; all other packages are plugins that register with the host and discover one another through events. The umbrella @pi-unipi/unipi package composes them.
• Event-driven integration. Cross-domain coupling is deliberately loose — the presentation domain (footer, notify) subscribes to events from orchestration, context and integration domains rather than importing their internals.
• Registry pattern. Recurs throughout: background-task registry, MCP ServerRegistry, web provider registry, footer segment registry, notify event-subscription registry, kanboard ParserRegistry, info-screen registry.
• Pipeline pattern. Compaction compile() and web extract() are explicit staged pipelines with well-defined intermediate representations.
• Policy objects. Subagent spawning applies budgets, depth guards, context policy and authority policy as separable libraries; the compactor's sandbox executor is guarded by a security policy scanner/evaluator.
• Durable, crash-safe state. DelegateArtifactStore and durable-fs provide atomic writes and manifests so process crashes do not corrupt artifacts.

6.3 Key Design Decisions and Observations

Complexity concentration. Although coupling between domains is low, complexity inside a few hub files is high: background-tasks/src/registry.ts, subagents/src/tool-handler.ts, compactor/src/compaction/summarize.ts and tools/register.ts, mcp/src/bridge/registry.ts, and web-api/src/engine/extract.ts. These are the natural focus points for review and testing.

Domain placement versus documentation. Product documentation groups "structured development" as workflow/kanboard/milestone/trajectory/ralph. In code, ralph behaves as orchestration (iterative loops emitting loop events) and trajectory as context capture; this document places them with Agent Orchestration and Context & Memory Management respectively. Readers reconciling with earlier documentation should note this refinement.

Cross-package coupling to watch. kanboard/parser imports milestone types directly (strength 7.0 in the domain analysis). This is the strongest direct inter-package dependency outside the core kernel and is worth monitoring if the milestone model evolves.

Configuration gating. Every package is independently enableable, which supports incremental adoption but means the effective system context varies per installation — e.g. notify, kanboard's HTTP server or MCP bridging may be absent.

Platform specifics. Windows process-tree termination is handled explicitly (windows-taskkill.ts); the memory package depends on a Python runtime for the MemPalace bridge. Both are environmental prerequisites that sit at the system boundary.

6.4 Summary

Unipi occupies a clear position in its environment: it lives entirely inside the Pi coding agent as a family of loosely coupled extensions, and it reaches outward to MCP servers, model providers, web content, notification platforms and the operating system to make the agent more capable and its sessions longer. Its boundary is the set of @pi-unipi/* packages plus the local state they persist; everything it hosts, bridges or notifies is external. The core kernel and event bus are the architectural linchpin, and the next level of documentation (Container view) should elaborate the six internal domains and their hub components identified here.