Definition

Pi Mono is a minimalist, modular AI agent framework designed for embedding agentic capabilities into applications with minimal abstraction. It prioritizes low-level primitives over opinionated features, enabling granular control over the execution loop, tool calling, and state management.

The framework is hosted at github.com/badlogic/pi-mono.

Core Architecture

The system is decomposed into specialized TypeScript packages under the @mariozechner scope.

  1. pi-ai: A unified API abstraction for multiple LLM providers (Anthropic, OpenAI, Google, Groq, etc.).
  2. pi-agent-core: The stateful runtime implementing the "thought-action-observation" loop.
  3. pi-coding-agent: Implementation of interactive CLI-specific tools and logic.
  4. pi-tui: A terminal UI library for high-performance, differential rendering.

Applied Tutorial: Basic System Agent

This project implements a system diagnostic agent that uses a custom tool to monitor local resource usage.

1. Project Initialization

npm install @mariozechner/pi-agent-core @mariozechner/pi-ai

2. Tool Implementation

A tool requires a JSON schema for parameters and an asynchronous execution function.

import { Tool } from "@mariozechner/pi-agent-core";

const resourceTool: Tool = {
  name: "get_resources",
  description: "Retrieves current memory and CPU usage",
  parameters: {
    type: "object",
    properties: {}
  },
  execute: async () => {
    return {
      memory: process.memoryUsage().rss,
      uptime: process.uptime()
    };
  }
};

3. Session Configuration

The session binds the model provider, the toolset, and the system instructions.

import { createAgentSession } from "@mariozechner/pi-agent-core";
import { AnthropicProvider } from "@mariozechner/pi-ai";

const session = await createAgentSession({
  provider: new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY }),
  model: "claude-3-5-sonnet",
  tools: [resourceTool],
  systemPrompt: "You are a diagnostic assistant. Provide concise system reports."
});

4. Agent Execution

const result = await session.prompt("Report current system health.");
console.log(result.text);

Operational Mechanics

Session Branching

Pi Mono treats conversation history as a directed acyclic graph (DAG). A session can be "branched" at any turn, allowing the agent to explore alternate trajectories without re-transmitting the entire history or corrupting the main thread. History is persisted as a JSONL stream.

Context Compaction

Automatic compaction maintains context window efficiency. When token limits are approached, the framework generates a summary of the earliest turns, which replaces the raw history. This ensures the agent retains global context while freeing up space for active reasoning.

Headless RPC Mode

For integration with external systems (e.g., as a backend for a desktop app), Pi Mono supports an RPC mode (pi --mode rpc). This exposes the session over a socket or HTTP interface, allowing remote control of the agent loop.

Production Heuristics

  1. Tool Minimization: Register the smallest possible toolset to reduce the search space and prevent model confusion.
  2. Deterministic Validation: Use the @mariozechner/pi-ai output schemas to validate LLM responses before tool execution.
  3. Durable State: Map the session directory to a persistent volume to ensure agent continuity across process restarts.

References

  1. Pi Mono Repository — github.com/badlogic/pi-mono
  2. Mario Zechner — github.com/mariozechner
  3. Pi Agent Core NPM — npm.im/@mariozechner/pi-agent-core