Skip to main content

​
Overview

The @mariozechner/pi-coding-agent package is the flagship Pi package - a complete terminal-based coding agent with interactive TUI, session management, extension system, and built-in tools for reading, writing, editing, and executing code.

Interactive Mode

Full TUI with editor, autocomplete, and streaming responses

Session Management

Tree-based branching, resume, and auto-save functionality

Extension System

TypeScript-based plugins for tools, commands, and UI

Multiple Modes

Interactive, print, JSON, RPC, and SDK modes

​
Installation

npm install -g @mariozechner/pi-coding-agent
Or use locally in a project: 
npm install @mariozechner/pi-coding-agent

​
Quick Start

​
CLI Usage

# Interactive mode with Anthropic
export ANTHROPIC_API_KEY=sk-ant-...
pi

# Interactive mode with OpenAI
export OPENAI_API_KEY=sk-...
pi --provider openai --model gpt-4o

# Non-interactive print mode
pi -p "What files are in the current directory?"

# Continue previous session
pi -c

​
SDK Usage

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

const authStorage = AuthStorage.create();
const modelRegistry = new ModelRegistry(authStorage);

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

await session.prompt("What files are in the current directory?");

​
Key Features

​
Built-in Tools

The coding agent ships with powerful file and system tools:
  • read - Read file contents with offset/limit support
  • write - Create or overwrite files
  • edit - String replacement editing with exact matching
  • bash - Execute shell commands with timeout and workdir support
  • grep - Search file contents using regex patterns
  • find - Search for files by glob pattern
  • ls - List directory contents
Tools can be configured via --tools flag: 
# Only enable read and bash
pi --tools read,bash

# Disable all built-in tools
pi --no-tools

​
Session Management

Sessions are stored as JSONL files with tree structure for branching: 
# Continue most recent session
pi -c

# Browse and select from past sessions
pi -r

# Use specific session file
pi --session path/to/session.jsonl

# Ephemeral mode (don't save)
pi --no-session
Tree navigation: Use /tree command to navigate session history, branch to different points, and create forks. Compaction: Automatic context management when approaching token limits. Customize via settings or extensions.

​
Extension System

Extend pi with TypeScript modules that can:
  • Add custom tools
  • Register slash commands
  • Add keyboard shortcuts
  • Hook into events (tool calls, messages, session lifecycle)
  • Modify UI (overlays, widgets, custom editors)
  • Override built-in behavior
// ~/.pi/agent/extensions/my-extension.ts
export default function (pi: ExtensionAPI) {
  pi.registerTool({
    name: "deploy",
    description: "Deploy the application",
    parameters: Type.Object({
      environment: Type.String()
    }),
    execute: async (toolCallId, params, signal, onUpdate) => {
      // Your deployment logic
      return {
        content: [{ type: "text", text: "Deployed to " + params.environment }]
      };
    }
  });

  pi.registerCommand("stats", {
    description: "Show project stats",
    execute: async (ctx) => {
      ctx.notify("Lines of code: 12,345");
    }
  });

  pi.on("tool_call", async (event, ctx) => {
    console.log(`Tool called: ${event.name}`);
  });
}
See Extensions Guide for detailed documentation.

​
Skills and Prompt Templates

Skills are on-demand capability packages following the Agent Skills standard: 
<!-- ~/.pi/agent/skills/deploy/SKILL.md -->
# Deploy Application

Use this skill when the user wants to deploy the application.

## Steps
1. Run tests
2. Build production bundle
3. Upload to server
Prompt Templates are reusable prompts with variable substitution: 
<!-- ~/.pi/agent/prompts/review.md -->
Review this code for:
- Security vulnerabilities
- Performance issues
- {{focus}}

​
Multiple Modes

ModeUsageDescription
InteractivepiFull TUI with editor and streaming
Printpi -p "message"Single message, print response
JSONpi --mode jsonEvent stream as JSON lines
RPCpi --mode rpcJSON-RPC over stdin/stdout
SDKimport { createAgentSession }Programmatic API

​
Configuration

​
Settings Files

  • ~/.pi/agent/settings.json - Global settings
  • .pi/settings.json - Project-specific settings
{
  "thinking": "medium",
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "keepRecentTurns": 5
  }
}
See Customization Guide for all options.

​
Context Files

Pi automatically loads AGENTS.md or CLAUDE.md files from:
  • ~/.pi/agent/AGENTS.md (global)
  • Parent directories (walking up from cwd)
  • Current directory
Use for project conventions, common patterns, and instructions.

​
API Reference

For programmatic usage, see:

​
Examples

​
Custom Tool with Extension

import { Type } from "@mariozechner/pi-coding-agent";

export default function (pi) {
  pi.registerTool({
    name: "search_docs",
    description: "Search documentation",
    parameters: Type.Object({
      query: Type.String({ description: "Search query" })
    }),
    execute: async (id, { query }, signal) => {
      const results = await searchDocs(query);
      return {
        content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
      };
    }
  });
}

​
Session Branching

import { createAgentSession } from "@mariozechner/pi-coding-agent";

const { session } = await createAgentSession(config);

await session.prompt("Implement feature X");
// ... conversation continues

// Branch from a specific point
const tree = session.getTree();
const branchPoint = tree.find(entry => entry.message.content.includes("feature X"));
await session.switchToEntry(branchPoint.id);
await session.prompt("Actually, implement feature Y instead");

​
Package Structure

@mariozechner/pi-coding-agent/
├── dist/               # Compiled output
├── docs/               # Documentation
├── examples/           # Example code
│   ├── sdk/           # SDK examples
│   └── extensions/    # Extension examples
└── src/
    ├── core/          # Core logic
    ├── modes/         # Interactive, print, JSON, RPC modes
    ├── cli.ts         # CLI entry point
    └── index.ts       # SDK entry point

Build docs developers (and LLMs) love

Get started for freeTalk to us