SDK / Programmatic Usage

✓ Fresh · 2026-02-24

Pi can be used programmatically as a library, enabling you to build applications that leverage Pi's agent capabilities without the interactive CLI.

Installation

npm install @mariozechner/pi-coding-agent

Basic Usage

import {
  AuthStorage,
  createAgentSession,
  ModelRegistry,
  SessionManager
} from "@mariozechner/pi-coding-agent";

// Create auth storage for API keys
const authStorage = new AuthStorage();

// Create model registry
const modelRegistry = new ModelRegistry(authStorage);

// Create an agent session
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage,
  modelRegistry,
});

// Send a prompt and get a response
await session.prompt("What files are in the current directory?");

Architecture

Key Components

AuthStorage

Manages authentication credentials (API keys and OAuth tokens):

const authStorage = new AuthStorage();
// API keys are read from environment variables automatically

ModelRegistry

Tracks available models and their configurations:

const modelRegistry = new ModelRegistry(authStorage);
// Discovers models based on available API keys

SessionManager

Controls how sessions are stored:

// In-memory (no persistence)
SessionManager.inMemory()

// File-based (persists to disk)
SessionManager.fileBased("/path/to/sessions/")

AgentSession

The main interface for interacting with the agent:

const { session } = await createAgentSession({ ... });

// Send a prompt
const result = await session.prompt("Your request here");

// Access session info
console.log(session.tokenCount);
console.log(session.cost);

RPC Mode

For non-Node.js applications, Pi supports an RPC protocol over stdin/stdout:

pi --mode rpc

RPC Communication

The RPC mode uses JSON messages over stdin/stdout:

This enables integration with:

• Python applications
• Go services
• Rust tools
• Any language that can spawn a process and communicate via stdin/stdout

Monorepo Packages

The Pi monorepo provides multiple packages at different abstraction levels:

Package	Purpose	Use When
@mariozechner/pi-coding-agent	Full interactive CLI + SDK	Building apps with full agent capabilities
@mariozechner/pi-agent-core	Agent runtime without CLI	Custom agent UIs, embedded agents
@mariozechner/pi-ai	Multi-provider LLM API only	Just need LLM access without agent features
@mariozechner/pi-tui	Terminal UI library	Building custom terminal interfaces
@mariozechner/pi-web-ui	Web components for chat	Building web-based chat UIs
@mariozechner/pi-mom	Slack bot	Delegating to Pi from Slack
@mariozechner/pi-pods	vLLM deployment CLI	Managing GPU pods for self-hosted models

Use Cases

Automated Code Review Bot

const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage: new AuthStorage(),
  modelRegistry: new ModelRegistry(authStorage),
});

const diff = await getDiffFromPR(prNumber);
const review = await session.prompt(
  `Review this code diff for bugs, security issues, and style:\n\n${diff}`
);
postReviewComment(prNumber, review);

Batch File Processing

const files = await glob("src/**/*.ts");
for (const file of files) {
  const { session } = await createAgentSession({
    sessionManager: SessionManager.inMemory(),
    authStorage: new AuthStorage(),
    modelRegistry: new ModelRegistry(authStorage),
  });
  await session.prompt(`Analyze ${file} for potential improvements.`);
}

CI/CD Integration

const { session } = await createAgentSession({ ... });
await session.prompt(
  "Run the test suite and fix any failing tests. " +
  "Commit the fixes with descriptive messages."
);