@mariozechner/pi-coding-agent

Full-featured coding agent CLI with tools, sessions, and extensibility

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

Mode	Usage	Description
Interactive	pi	Full TUI with editor and streaming
Print	pi -p "message"	Single message, print response
JSON	pi --mode json	Event stream as JSON lines
RPC	pi --mode rpc	JSON-RPC over stdin/stdout
SDK	import { 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:

• SDK API
• Extension API
• Extension Hooks
• Tool Creation

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

Links

• GitHub Repository
• npm Package
• Extensions Guide
• Skills Documentation
• Session Format