Documentation Index

Fetch the complete documentation index at: https://mintlify.com/badlogic/pi-mono/llms.txt

Use this file to discover all available pages before exploring further.

​

Architecture Overview

​

Architectural Layers

​

Foundation Layer

• Component-based architecture
• Synchronized output for flicker-free updates
• Built-in components: Text, Editor, Markdown, Image, SelectList
• Theme support for customization
• Handles bracketed paste mode and autocomplete

• CLI for deploying and managing LLM inference servers
• Handles GPU resource allocation
• Independent utility for self-hosted deployments

​

AI Layer

• Abstracts differences between OpenAI, Anthropic, Google, etc.
• Automatic model discovery with 50+ pre-configured models
• Streaming and non-streaming interfaces
• Tool calling (function calling) support
• Token and cost tracking
• Cross-provider context handoff
• OAuth provider support

​

Agent Layer

• Agent loop with tool execution
• Event-based architecture for streaming updates
• State management for conversations
• Message queue system for steering and follow-ups
• Abort handling and error recovery
• Custom message type support via declaration merging

• Turn management (LLM call + tool executions)
• Tool result formatting
• Context transformation
• Streaming event emission

​

Application Layer

• Interactive TUI mode with editor
• Session management with branching
• Extension system
• Skills and prompt templates
• Built-in tools: read, write, edit, bash, grep, find
• Multiple output modes: interactive, print, JSON, RPC

• Delegates Slack messages to pi-coding-agent
• Manages multiple concurrent conversations
• Scheduled task execution
• Shared session management

• Chat interface components
• Model selection UI
• Integration with pi-ai for browser-based apps
• Works with Lit or mini-lit

​

Data Flow

​

User Request Flow

┌─────────────┐
│   User      │
│   Input     │
└──────┬──────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  pi-coding-agent                        │
│  - Parse input                          │
│  - Check for commands/templates         │
│  - Build context with session history   │
└──────┬──────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  pi-agent-core                          │
│  - Start agent loop                     │
│  - Transform context                    │
│  - Emit events (agent_start, turn_start)│
└──────┬──────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  pi-ai                                  │
│  - Convert messages to provider format  │
│  - Call LLM API                         │
│  - Parse streaming response             │
│  - Emit events (text_delta, tool_call)  │
└──────┬──────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  pi-agent-core                          │
│  - Collect tool calls                   │
│  - Execute tools                        │
│  - Add tool results to context          │
│  - Continue loop if needed              │
│  - Emit events (tool_execution_*, done) │
└──────┬──────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  pi-coding-agent                        │
│  - Update session                       │
│  - Render response in TUI               │
│  - Save session to disk                 │
└─────────────────────────────────────────┘

​

Event Flow

// Streaming events from LLM
type AssistantMessageEvent =
  | { type: 'start' }
  | { type: 'text_delta', delta: string }
  | { type: 'tool_call_start' }
  | { type: 'tool_call_delta', delta: string }
  | { type: 'done', reason: StopReason }

​

Package Dependencies

pi-coding-agent
├── pi-agent-core
│   └── pi-ai
├── pi-tui
└── jiti (for extension loading)

pi-mom
├── pi-coding-agent
├── pi-agent-core
└── pi-ai

pi-web-ui
├── pi-ai
├── pi-tui
└── mini-lit / lit

pi-pods
└── pi-agent-core

​

Extension Points

​

At the AI Layer (pi-ai)

• Custom models with Model<Api> interface
• Provider registration for new LLM APIs
• Custom stream functions for proxy backends

​

At the Agent Layer (pi-agent-core)

• Custom message types via declaration merging
• Tool registration with AgentTool interface
• Context transformation hooks
• Custom convertToLlm function

​

At the Application Layer (pi-coding-agent)

• Extensions: TypeScript modules with full access to agent lifecycle
• Skills: Markdown files with instructions for specific tasks
• Prompt Templates: Reusable prompt snippets with argument substitution
• Themes: JSON-based UI customization

​

Design Principles

​

1. Layered Abstraction

• pi-ai abstracts provider differences
• pi-agent-core abstracts the agent loop
• pi-coding-agent abstracts session management and UI

​

2. Event-Driven Architecture

• Enables streaming UIs
• Allows extensions to observe without blocking
• Supports multiple subscribers (extensions, logging, metrics)

​

3. Type Safety

• Model types enforce API compatibility
• Tool schemas use TypeBox for runtime validation
• Extension types ensure compile-time correctness

​

4. Composability

• Use pi-ai alone for LLM calls in any app
• Use pi-agent-core for custom agent implementations
• Use pi-tui for any terminal UI application
• Use pi-coding-agent as a library or CLI

​

Next Steps