Architecture Overview

The pi-mono project is a monorepo containing a suite of tools and libraries for building AI agents and managing LLM deployments. The architecture is modular, with distinct packages for handling AI provider interactions, agent logic, user interfaces (TUI and Web), and specific applications like a coding agent and a Slack bot. This structure promotes code reuse and separation of concerns, allowing different agent implementations to share a common core.

The project uses a lockstep versioning system, ensuring all packages within the monorepo share the same version number for consistency and simplified dependency management. Development scripts are managed at the root level to build, test, and publish all packages concurrently.

Sources: README.md:3-4, README.md:52-55, package.json:5-8

Core Components

The monorepo is organized into several key packages, each with a specific responsibility. These packages work together to provide a comprehensive framework for agent development.

The following diagram illustrates the high-level dependencies between the main packages.

Sources: README.md:7-16, packages/mom/src/agent.ts:1, packages/coding-agent/src/main.ts:1-2

Package Breakdown

The table below, derived from the root README.md, summarizes the purpose of each package in the monorepo.

Sources: README.md:9-16

Agent Architecture

The core of the project is its agent architecture, which is implemented across several packages. The pi-agent-core package provides the fundamental Agent class, while application packages like pi-coding-agent and pi-mom build upon it to create specialized agents.

Agent Initialization and Execution

An agent is created with an initial state that includes a system prompt, a model, a thinking level, and a set of tools. The execution flow is managed by an AgentRunner or a similar controlling structure that handles the agent's lifecycle.

The following diagram shows the typical flow for running an agent in response to a user message.

Sources: packages/mom/src/agent.ts:400-560, packages/coding-agent/src/main.ts:1000-1050

System Prompt Construction

The system prompt is dynamically constructed to provide the agent with all necessary context for a given task. This includes static instructions, environment details, and dynamic content like conversation history and memory.

The mom agent's buildSystemPrompt function is a clear example of this process. It assembles:

• Current date and time.
• Slack-specific formatting rules and user/channel IDs.
• A description of the execution environment (Docker or host).
• The workspace file layout.
• Instructions for using "Skills" (custom CLI tools).
• The content of global and channel-specific MEMORY.md files.
• Critical instructions for querying the log.jsonl file for history.
• A list of available tools.

Sources: packages/mom/src/agent.ts:220-333, packages/coding-agent/src/main.ts:333-435

Tooling and Execution

Agents are equipped with tools to interact with their environment. The coding-agent and mom agent share a similar set of core tools: bash, read, write, and edit. The web-ui agent uses different tools like javascript_repl and artifacts.

mom and coding-agent Tools

• bash: The primary tool for executing shell commands, installing packages, and general interaction.
• read: Reads file contents.
• write: Creates or overwrites files.
• edit: Performs surgical find-and-replace operations on files.
• attach: (mom-specific) Shares files back to the Slack channel.

Sources: packages/mom/src/agent.ts:325-331, packages/coding-agent/src/main.ts:291-299

web-ui Tools

• javascript_repl: Executes JavaScript in a sandboxed browser environment with access to Web APIs and helper functions for managing artifacts.
• artifacts: A tool for creating and managing persistent files (e.g., .md, .html, .json) alongside the conversation. It supports create, update, rewrite, get, and delete actions.

Sources: packages/web-ui/src/prompts/prompts.ts:8-10, packages/web-ui/src/prompts/prompts.ts:71-74

Agent Event Lifecycle

The agent's interaction with tools and the generation of responses are managed through an event-driven system. The agent.subscribe method allows the application to react to different stages of the agent's process.

This sequence diagram shows the event flow during a single agent run involving a tool call.

Sources: packages/mom/src/agent.ts:494-559, packages/coding-agent/src/tui/tui-renderer.ts:400-500

Sandbox Environment (mom agent)

The mom agent is designed to operate within a sandboxed environment to enhance security and isolate its operations. It supports two modes:

• Docker (Recommended): Commands are executed inside an isolated Linux container. The agent can only access a mounted data directory from the host. This protects the host system from unintended modifications.
• Host: Commands are executed directly on the host machine, giving the agent full access to the user's system. This is not recommended for security reasons.

The sandbox type is configured via the --sandbox CLI option.

Sources: packages/mom/README.md:54-58, packages/mom/README.md:104-114, packages/mom/src/agent.ts:400-401

Data and State Management

Persistent state, conversation history, and agent-generated artifacts are managed through a structured file system layout and session management logic.

mom Agent Workspace

The mom agent uses a dedicated data directory to store all its operational data, creating a persistent and self-contained workspace.

The diagram below shows the structure of the mom agent's data directory.

• MEMORY.md: Global memory shared across all channels.
• skills/: Global custom CLI tools ("skills") created by the agent.
• <ChannelID>/: A directory for each Slack channel the agent operates in.
  • MEMORY.md: Channel-specific memory.
  • log.jsonl: Full conversation history for the channel, including user messages and tool interactions.
  • attachments/: Files shared by users in the channel.
  • scratch/: A working directory for the agent.

Sources: packages/mom/README.md:120-132, packages/mom/src/agent.ts:199-216

coding-agent Session Management

The pi-coding-agent uses a SessionManager to handle conversation history. Sessions are stored as .jsonl files.

• Continuation: The --continue or -c flag allows resuming the most recent session.
• Resuming: The --resume or -r flag opens a TUI to select a specific past session to resume.
• Branching: The /branch command allows creating a new session that forks from a previous point in the conversation history.
• Context Compaction: The agent supports both manual (/compact) and automatic context compaction. This feature summarizes older parts of the conversation to reduce token usage while preserving key information.

Sources: packages/coding-agent/src/main.ts:1010-1022, packages/coding-agent/src/tui/tui-renderer.ts:680-684, packages/coding-agent/src/tui/tui-renderer.ts:1330-1345

User Interfaces

The project provides two primary user interfaces for interacting with agents: a Terminal User Interface (TUI) and a set of Web Components.

Terminal UI (pi-tui)

The pi-coding-agent uses the @mariozechner/pi-tui package to provide a rich, interactive chat experience in the terminal. The TuiRenderer class orchestrates the display.

Key components include:

• Chat Container: Displays the conversation history, including user messages, assistant responses, and tool executions.
• Editor: A multi-line input for composing messages, with support for history, autocomplete for slash commands, and file paths.
• Footer: Shows the current model, thinking level, token usage, cost, and other status information.
• Selectors: Modal-like views for selecting models, thinking levels, themes, and sessions.

Sources: packages/coding-agent/src/tui/tui-renderer.ts:80-100, packages/tui/test/markdown.test.ts

Web UI (pi-web-ui)

The @mariozechner/pi-web-ui package provides web components for building AI chat interfaces. The example application demonstrates a ChatPanel component that facilitates interaction with an agent.

• Direct API Calls: The example is configured to make API calls directly from the browser to AI providers.
• API Key Management: Keys are managed in the browser's localStorage.
• Tools: The web UI agent is demonstrated with a javascript_repl for executing code and an artifacts tool for creating files like HTML, which can be rendered directly in the interface.

Sources: packages/web-ui/example/README.md:11-12, packages/web-ui/example/README.md:20-24, packages/web-ui/src/utils/test-sessions.ts:1-300

Development and Versioning

The monorepo uses a standardized set of scripts and a lockstep versioning strategy to maintain consistency across all packages.

Lockstep Versioning

All packages must have the same version number. The root package.json provides scripts to manage this:

• npm run version:patch
• npm run version:minor
• npm run version:major

These commands update all package.json files and inter-package dependencies simultaneously.

Sources: README.md:52-62

Release Process

The release process is a multi-step workflow involving version bumping, changelog updates, git tagging, and publishing to npm.

The following flowchart outlines the release process.

Sources: README.md:65-95, AGENTS.md:58-79