pi-coding-agent

Python port of pi's terminal coding harness. The installed CLI entry point is pp; the lower-level OAuth helper is pp-ai; evals run with pp-evals. The package requires Python >= 3.11 and is developed as a uv workspace.

Pi is a minimal terminal coding harness. Adapt pi to your workflows without forking internals. Extend it with Python Extensions, Skills, Prompt Templates, and Themes. Bundle those resources in Pi Packages and share them by git or local path.

Pi ships with useful defaults but keeps the core small. It runs in interactive TUI mode, print mode, JSON event mode, a Python SDK, the stdio JSONL RPC mode, and a Unix-socket RPC stack.

Share your OSS coding agent sessions

Sessions are stored as JSONL files, so external tooling can process them. The TypeScript README's pi-share-hf workflow is not part of this Python port.

Table of Contents

• Quick Start
• Providers & Models
• Interactive Mode
  • Editor
  • Commands
  • Keyboard Shortcuts
  • Message Queue
• Sessions
  • Branching
  • Compaction
• Settings
• Context Files
• Customization
  • Prompt Templates
  • Skills
  • Extensions
  • Themes
  • Pi Packages
• Programmatic Usage
• Philosophy
• CLI Reference

Quick Start

From a source checkout:

uv sync --all-packages
uv run pp --help

From an installed wheel or package index:

python -m pip install pi-coding-agent
pp --help

Authenticate with an API key:

export ANTHROPIC_API_KEY=sk-ant-...
uv run pp

Or use interactive login:

/login  # Then select provider

Then talk to pi. By default, pi gives the model four tools: read, bash, edit, and write. Additional built-in tools (grep, find, ls) can be enabled with --tools.

Platform notes: Windows | Termux (Android) | tmux | Terminal setup | Shell aliases

Providers & Models

The Python port ships a static built-in model catalog and reads custom overlays from ~/.pi/agent/models.json. Remote model-catalog refresh and pp update --models are not ported.

OAuth login is ported for:

• Anthropic
• GitHub Copilot
• Kimi For Coding
• OpenRouter
• Radius
• xAI

API-key providers in the catalog:

• Amazon Bedrock
• Ant Ling
• Anthropic
• Azure OpenAI
• Baseten
• Cerebras
• Cloudflare AI Gateway
• Cloudflare Workers AI
• DeepSeek
• Fireworks
• GitHub Copilot
• Google
• Google Vertex AI
• Groq
• Hugging Face
• Kimi For Coding
• MiniMax
• MiniMax CN
• Mistral
• Moonshot AI
• Moonshot AI CN
• NVIDIA
• OpenAI
• OpenAI Codex
• OpenCode Zen
• OpenCode Go
• OpenRouter
• Qwen Token Plan
• Qwen Token Plan CN
• Qwen Token Plan Individual
• Radius
• Together
• Vercel AI Gateway
• xAI
• Xiaomi
• Xiaomi Token Plan AMS
• Xiaomi Token Plan CN
• Xiaomi Token Plan SGP
• Z.AI
• Z.AI Coding CN

Amazon Bedrock and OpenAI Codex models remain discoverable, but their streaming APIs are not ported and raise NotImplementedError when used.

Select a model with /model in the TUI, or use CLI options:

uv run pp --provider anthropic --model claude-sonnet-4-5
uv run pp --model anthropic/claude-sonnet-4-5
uv run pp --model claude-sonnet-4-5:high
uv run pp --list-models sonnet

Custom providers can be added in ~/.pi/agent/models.json when they use a ported API shape (openai-completions, openai-responses, anthropic-messages, or google-generative-ai). See docs/models.md and docs/custom-provider.md.

The llama.cpp local-model extension from the TypeScript package is not ported.

Interactive Mode

Run pp on a TTY with no -p flag to start the interactive TUI.

The interface from top to bottom:

• Startup header - Shows shortcuts, context files, prompt templates, skills, and extensions
• Messages - User messages, assistant responses, tool calls and results, notifications, errors, and generic custom entries
• Editor - Where you type; border color indicates thinking level
• Footer - Working directory, branch, token usage, context usage, current model, and extension status text

Both TUI modes are ported: regular and fullscreen. Runtime switching between them is not ported; changing the setting applies on the next start.

Extension widgets, custom header/footer/editor replacement, extension-driven dialogs, and terminal input listeners from the TypeScript UI host are not ported.

Editor

Standard editing keybindings are loaded from ~/.pi/agent/keybindings.json. See docs/keybindings.md.

Commands

Type / in the editor to trigger commands. Extensions can register custom commands, skills are available as /skill:name, and prompt templates expand as /templatename.

Keyboard Shortcuts

See /hotkeys for the full list. Customize via ~/.pi/agent/keybindings.json.

Commonly used:

Message Queue

Submit messages while the agent is working:

• Enter queues a steering message, delivered after the current assistant turn finishes its tool calls
• Alt+Enter queues a follow-up message, delivered after the agent finishes all current work
• Escape aborts and restores queued messages to the editor
• Alt+Up retrieves queued messages back to the editor

Configure delivery in settings: steeringMode and followUpMode can be "one-at-a-time" or "all". transport selects provider transport preference ("sse", "websocket", "websocket-cached", or "auto") where supported.

Sessions

Sessions are JSONL files with a tree structure. Each entry has an id and parentId, enabling in-place branching without creating new files. See docs/session-format.md.

Management

Sessions auto-save to ~/.pi/agent/sessions/ organized by working directory.

uv run pp -c                  # Continue most recent session
uv run pp -r                  # Browse and select from past sessions
uv run pp --no-session        # Ephemeral mode
uv run pp --name "my task"    # Set session display name at startup
uv run pp --session <path|id> # Use specific session file or ID
uv run pp --fork <path|id>    # Fork a session file or ID into a new session

Use /session in interactive mode to see the current session ID before reusing it with --session <id> or --fork <id>.

Branching

/tree - Navigate the session tree in-place. Select any previous point, continue from there, and switch between branches. All history is preserved in a single file.

• Search by typing, fold/unfold and jump between branches with Ctrl+Left/Ctrl+Right or Alt+Left/Alt+Right
• Filter modes: default, no-tools, user-only, labeled-only, all
• Press Ctrl+X to copy the selected message
• Press Shift+L to label entries and Shift+T to toggle label timestamps

/fork creates a new session file from a previous user message on the active branch.

/clone duplicates the current active branch into a new session file at the current position.

--fork <path|id> forks an existing session file or partial session UUID from the CLI.

Compaction

Long sessions can exhaust context windows. Compaction summarizes older messages while keeping recent ones.

Manual: /compact or /compact <custom instructions>

Automatic: Enabled by default. It triggers on context overflow or near the context limit. Configure via /settings or settings.json.

Compaction is lossy. The full history remains in the JSONL file; use /tree to revisit it. Extension hooks for custom compaction are ported. See docs/compaction.md.

Settings

Use /settings to modify common options, or edit JSON files directly:

Important settings keys include defaultProvider, defaultModel, defaultThinkingLevel, steeringMode, followUpMode, transport, externalEditor, defaultProjectTrust, enableInstallTelemetry, versionCheckPackage, tuiMode, fullscreenExitOutput, fullscreenScrollbar, enabledModels, images.autoResize, and images.blockImages.

The markdown.mermaid setting exists, but Mermaid diagram rendering is not ported.

See docs/settings.md for all options.

Project Trust

On interactive startup, pi asks before trusting a project folder that contains project-local settings, resources, or project .agents/skills and has no saved decision for the folder or a parent folder in ~/.pi/agent/trust.json. Trusting a project allows pi to load .pi/settings.json, .pi resources, and project extensions.

Non-interactive modes (-p and --mode json) do not show a trust prompt. Without a saved trust decision, they use defaultProjectTrust: ask and never ignore project resources; always trusts them. Pass --approve or --no-approve to override project trust for one run.

Use /trust in interactive mode to save a project trust decision for future sessions. It writes ~/.pi/agent/trust.json; restart pi for newly trusted project resources to load.

Telemetry and update checks

Pi has two separate startup features:

• Update check: checks PyPI, not pi.dev. Configure the distribution with PI_VERSION_CHECK_PACKAGE or versionCheckPackage. Disable with PI_SKIP_VERSION_CHECK=1.
• Install/update telemetry: controlled by enableInstallTelemetry or PI_TELEMETRY. This also controls optional provider attribution headers for OpenRouter, Cloudflare, and direct NVIDIA requests.

Use --offline or PI_OFFLINE=1 to disable startup network operations, including update checks, package update checks, and install/update telemetry.

Context Files

Pi loads AGENTS.md or CLAUDE.md at startup from:

• ~/.pi/agent/AGENTS.md
• Parent directories, walking up from cwd
• Current directory

If a directory contains AGENTS.override.md, pi loads it instead of AGENTS.md or CLAUDE.md from that directory. Context files from other directories are still concatenated.

Disable context file loading with --no-context-files or -nc.

System Prompt

Replace the default system prompt with .pi/SYSTEM.md or ~/.pi/agent/SYSTEM.md. Append without replacing via APPEND_SYSTEM.md.

Customization

Prompt Templates

Reusable prompts as Markdown files. Type /name to expand.

<!-- ~/.pi/agent/prompts/review.md -->
Review this code for bugs, security issues, and performance problems.
Focus on: $ARGUMENTS

Place in ~/.pi/agent/prompts/, .pi/prompts/, or a pi package. See docs/prompt-templates.md.

Skills

On-demand capability packages following the Agent Skills layout. Invoke via /skill:name or let the agent load them automatically.

---
name: my-skill
description: Use this skill when the user asks about X.
---

# My Skill

## Steps
1. Do this
2. Then that

Place in ~/.pi/agent/skills/, ~/.agents/skills/, .pi/skills/, or .agents/skills/ from cwd up through parent directories, or in a pi package. See docs/skills.md.

Extensions

Python modules that extend pi with custom tools, commands, and event handlers. An extension file exports a callable named pi_extension.

from typing import Any

from pi_agent.types import AgentToolResult, AgentToolUpdateCallback
from pi_ai.types import TextContent
from pi_ai.utils.abort import AbortSignal
from pi_coding_agent.core.extensions import ExtensionAPI, ExtensionContext, ToolDefinition


async def echo_tool(
    tool_call_id: str,
    params: dict[str, Any],
    signal: AbortSignal | None,
    on_update: AgentToolUpdateCallback | None,
    ctx: ExtensionContext,
) -> AgentToolResult:
    text = str(params.get("text", ""))
    return AgentToolResult(content=[TextContent(text=text)])


def pi_extension(pi: ExtensionAPI) -> None:
    pi.register_tool(
        ToolDefinition(
            name="echo",
            label="Echo",
            description="Echo text back.",
            parameters={
                "type": "object",
                "properties": {"text": {"type": "string"}},
            },
            execute=echo_tool,
        )
    )

The ported extension API supports tool registration, command registration, event handlers, extension events, and headless-safe UI methods (select, confirm, input, notify, set_status, set_title). Provider registration, custom CLI flags, shortcut registration, markdown/message/entry renderer registration, and the TypeScript extension UI host are not ported.

Place extensions in ~/.pi/agent/extensions/, .pi/extensions/, or a pi package. Python package manifests use pi.json, not package.json. See docs/extensions.md and examples/extensions/.

Themes

Built-in themes: dark, light. Custom theme loading is ported; live file-watcher hot reload is not ported.

Place themes in ~/.pi/agent/themes/ or provide them through a package. Project .pi/themes/ and package themes are resolved by the package manager; the interactive runtime currently initializes built-in and global custom-directory themes directly. See docs/themes.md.

Pi Packages

Bundle and share extensions, skills, prompts, and themes by git repository or local path.

Security: Pi packages run with full system access. Extensions execute arbitrary Python code, and skills can instruct the model to perform actions. Review third-party code before installing it.

uv run pp install git:github.com/user/repo
uv run pp install git:github.com/user/repo@v1
uv run pp install https://github.com/user/repo
uv run pp install ssh://git@github.com/user/repo
uv run pp install ./local/path
uv run pp remove git:github.com/user/repo
uv run pp uninstall ./local/path
uv run pp list
uv run pp update
uv run pp update git:github.com/user/repo
uv run pp config

Use -l or --local with install, remove, or uninstall for project-local settings. Git packages install to ~/.pi/agent/git/ or .pi/git/; local-path packages are referenced in place. npm: sources, package dependency install, self-update, update --all, update --self, update --models, and update --extension are not ported.

Create a package with a pi.json manifest:

{
  "extensions": ["./extensions"],
  "skills": ["./skills"],
  "prompts": ["./prompts"],
  "themes": ["./themes"]
}

Without a manifest, pi auto-discovers conventional directories: extensions/, skills/, prompts/, and themes/. See docs/packages.md.

Programmatic Usage

SDK

import asyncio

from pi_coding_agent.core.sdk import CreateAgentSessionOptions, create_agent_session
from pi_coding_agent.core.session_manager import SessionManager


async def main() -> None:
    result = await create_agent_session(CreateAgentSessionOptions(session_manager=SessionManager.in_memory()))
    try:
        await result.session.prompt("What files are in the current directory?")
        print(result.session.get_last_assistant_text())
    finally:
        result.session.dispose()


asyncio.run(main())

For custom setup, pass model_runtime, settings_manager, resource_loader, custom_tools, or loaded extensions in CreateAgentSessionOptions. See docs/sdk.md and examples/sdk/.

RPC Mode

pp --mode rpc runs the agent headless behind a JSON protocol on stdin/stdout: a host writes one command per line and reads responses and events back. See docs/rpc-stdio.md.

For multi-client access over a Unix socket, the pi_server / pi_client / pi_protocol stack is documented in docs/rpc.md.

Philosophy

Pi is extensible so it does not have to dictate your workflow. Features that other tools bake in can be built with extensions, skills, or packages.

No MCP by default. Build CLI tools with READMEs or add MCP support through an extension.

No built-in sub-agents. Spawn pi instances yourself or build the workflow as an extension or package.

No permission popups. Run in a container or add a confirmation flow through an extension.

No plan mode. Write plans to files or build plan mode as an extension.

No built-in to-dos. Use a TODO file or build a task system as an extension.

No background bash. Use tmux for direct observability and control.

CLI Reference

pp [options] [@files...] [messages...]

Package Commands

pp install <source> [-l]
pp remove <source> [-l]
pp uninstall <source> [-l]
pp update [source]
pp list
pp config

pp config and project-local package commands accept --approve and --no-approve for one-command project trust overrides. pp update never prompts for project trust.

Modes

In print mode, pi also reads piped stdin and merges it into the initial prompt:

cat README.md | pp -p "Summarize this text"

Model Options

Session Options

Tool Options

Available built-in tools: read, bash, edit, write, grep, find, ls.

Resource Options

Other Options

File Arguments

Prefix files with @ to include them in the message:

pp @prompt.md "Answer this"
pp -p @screenshot.png "What's in this image?"
pp @code.py @test_code.py "Review these files"

Examples

# Interactive with initial prompt
pp "List all .py files in src/"

# Non-interactive
pp -p "Summarize this codebase"

# Non-interactive with piped stdin
cat README.md | pp -p "Summarize this text"

# Named one-shot session
pp --name "release audit" -p "Audit this repository"

# Different model
pp --provider openai --model gpt-4o "Help me refactor"

# Model with provider prefix
pp --model openai/gpt-4o "Help me refactor"

# Model with thinking level shorthand
pp --model claude-sonnet-4-5:high "Solve this complex problem"

# Limit model cycling
pp --models "anthropic/*,*sonnet*"

# Read-only mode
pp --tools read,grep,find,ls -p "Review the code"

# Disable one tool while keeping the rest available
pp --exclude-tools bash

# High thinking level
pp --thinking high "Solve this complex problem"

Environment Variables

Commands run by the LLM-callable bash tool also receive current session metadata:

See Environment Variables.

Contributing & Development

See the repository root README for port status and verification commands. Do not confuse that root document with this package-level product manual.

License

MIT

See Also

• pi-ai: provider registry and LLM API layer; CLI entry point pp-ai
• pi-agent: agent loop and session-independent agent types
• pi-tui: terminal UI components
• pi-protocol, pi-server, pi-client: socket RPC stack
• pp-evals: eval harness; CLI entry point pp-evals

pp-coding-agent is developed in HSPK/pp. It was split out of the pp monorepo; sibling packages (pp-ai, pp-agent-core, pp-tui, pp-coding-agent, ...) each live in their own repository and are consumed from PyPI.