Pi Coding Agent: Extensible AI Terminal Agent for Developers

Pi Coding Agent is an open-source AI coding agent you run from a project directory in the terminal.

Describe a task such as tracing a bug or changing an API, and Pi can inspect the repository, edit files, run commands, and check the result from the same terminal session.

For longer tasks, Pi saves the conversation as a JSONL tree. If an approach goes wrong, returning to an earlier message starts another branch beside the original, with both paths available for comparison in the same session.

Pi Coding Agent at a Glance

What Makes Pi Coding Agent Different

Pi’s JSONL session file records the conversation as a tree. When you return to an earlier message with /tree, Pi opens another branch and preserves the path you left. You can then test a different prompt, model, or implementation inside the same history.

Extensions reach into the running agent. They can intercept tool calls, replace built-in tools, add providers or permission checks, change compaction, and rebuild terminal components. Files in the standard extension directories reload with /reload; runtime changes then take effect during the session.

Scripts and custom clients use the harness through print mode, JSON events, line-based RPC, or the Node.js SDK. Each interface shares Pi’s agent and session machinery; a custom client inherits the same tool loop and session management.

The default agent starts with four active tools. MCP, subagents, plan mode, background jobs, and permission prompts arrive through extensions or external workflows. You decide which pieces to add, how they behave, and how much code to trust.

Is Pi Coding Agent Free?

Pi Coding Agent is free to install, inspect, modify, and distribute under the MIT License. The coding agent has no separate Pi subscription.

Each agent request needs a model. Subscription access starts through /login. Pi also accepts API credentials for built-in providers, where the provider bills usage under its own terms. A local llama.cpp router uses your hardware and downloaded model files for inference.

Features

• Four built-in model tools read files, write files, apply precise edits, and run shell commands.
• The interactive terminal UI shows messages, tool calls, errors, token usage, cost, context use, and the active model.
• /model and Ctrl+L open the model selector during a session. Ctrl+P cycles through a configured model scope.
• Sessions use a JSONL tree. /tree returns to any earlier point while preserving every branch in one session file.
• Automatic compaction summarizes older context near the model limit. The complete history stays in the session file.
• Project instructions load from AGENTS.md or CLAUDE.md files in the current directory, parent directories, and the global agent directory.
• TypeScript extensions can register model tools, slash commands, shortcuts, events, provider authentication, and custom terminal components.
• Agent Skills store reusable task instructions in SKILL.md files and load on demand.
• Pi packages distribute extensions, skills, prompts, and themes through npm or Git repositories.
• Interactive, print, JSON, RPC, and SDK interfaces cover direct terminal work, scripts, external processes, and embedded Node.js applications.

Use Cases

• Inspect an unfamiliar repository, trace a feature across files, and ask Pi to explain the relevant code.
• Edit several files for a bug fix, then run tests or linters through the built-in bash capability.
• Branch a long coding session to compare two implementations while keeping the earlier conversation available.
• Apply the same project rules across repositories through shared AGENTS.md files and Pi packages.
• Run one prompt from a script, consume structured JSON events, or control a session through RPC.
• Embed the agent harness in a Node.js application through the coding-agent SDK.

How to Install and Start Pi

Install the npm release globally with dependency lifecycle scripts disabled:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Linux and macOS also have a shell installer:

curl -fsSL https://pi.dev/install.sh | sh

Open the project directory and start Pi:

cd /path/to/your-project
pi

For subscription access, enter /login and select a provider. For API access, set the provider’s environment variable before starting Pi. This Anthropic example keeps the credential out of the prompt history:

export ANTHROPIC_API_KEY=sk-ant-...
pi

Use /model to select a model, then describe a concrete task such as Find the validation logic for account creation and explain its tests. Pi will ask for project trust before it loads project-local settings, resources, or packages from an untrusted folder.

Run pi update to update the coding agent. Use pi update --models when you only need a fresh model catalog, or pi update --all to update Pi and installed packages together.

Uninstall the npm package with the command below. Pi leaves settings, credentials, sessions, and installed resources in ~/.pi/agent/. Remove that directory separately only when you also want to erase the saved local state.

npm uninstall -g @earendil-works/pi-coding-agent

Everyday Interactive Workflow

When Pi starts, the conversation occupies the center of the screen and the editor sits below it. The header and footer keep the current directory, session name, active model, reasoning level, token use, context use, and reported cost visible while you work. Tool calls and results appear in the conversation as they run.

Type a request and press Enter to send it. Prefix a path with @ to attach a file reference, or press Tab while typing a path to complete it. You can paste text and supported images into the editor. Ctrl+G opens the draft in the editor selected by VISUAL or EDITOR.

A line beginning with ! runs a shell command and sends the output into the conversation. Two exclamation marks reserve the command and its output for the terminal. Use the second form for terminal-only actions such as clearing the screen.

!git status
!!clear

Pi accepts new messages while the model is working. Enter sends a steering message at the next safe boundary, while Alt+Enter queues a follow-up for delivery after the current response. Escape aborts the response and restores the interrupted message to the editor; Alt+Up retrieves queued messages for editing. On Windows terminals that reserve Alt+Enter, change the terminal binding before using the shortcut.

Use /model to choose a model and Shift+Tab to change the reasoning level. /scoped-models limits the set cycled by Ctrl+P. The active provider, model, and reasoning level stay visible in the footer.

The default active tools are read, bash, edit, and write. Pi also ships built-in grep, find, and ls implementations. Use --tools to create an allowlist, --exclude-tools to disable selected tools, --no-builtin-tools to keep only extension tools, or --no-tools for a conversation with no executable tools.

pi --tools read,grep,find,ls -p "Review this project without changing files"

Pi Command Quick Reference

Sessions, Branching, and Compaction

Interactive sessions save automatically as JSONL files under ~/.pi/agent/sessions/, grouped by working directory. Run pi -c to continue the latest session or pi -r to open the session picker. The picker searches message text, filters by directory, and provides rename and delete actions. /name adds a readable session name.

pi -c
pi -r
pi --name "bug 142"
pi --session <path-or-session-id>
pi --no-session

Each JSONL session file stores a tree of conversation branches. /tree moves the active point to an earlier message and keeps the previous continuation as another branch. From the selected point, /fork starts a new session and /clone copies the current branch into a separate session. The earlier work stays available while you test a different prompt, model, or implementation.

Compaction protects the active context window. Pi summarizes older messages near the model limit and retains recent messages in full. The complete JSONL history stays on disk. Run /compact to compact early, then inspect or revisit the original branch through /tree. /export creates an HTML copy. /share uploads a private GitHub gist and returns a shareable HTML link only after you invoke it.

Project Instructions, Settings, and Trust

Pi reads AGENTS.md and CLAUDE.md as project instructions. It combines the global file in ~/.pi/agent/, files found while walking from the filesystem root toward the current directory, and the file in the working directory. Run /reload after editing an instruction file during a session.

A custom system prompt can live in ~/.pi/agent/SYSTEM.md or .pi/SYSTEM.md. An APPEND_SYSTEM.md file adds text to the standard prompt. The project version takes priority over the global version. CLI options also accept explicit context files and can disable automatic context discovery for a controlled automation run.

Global settings live in ~/.pi/agent/settings.json. Project settings live in .pi/settings.json and override global values. /settings edits common options inside the terminal. Settings select a default provider, model, reasoning level, theme, compaction behavior, retry policy, proxy, and project trust policy.

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-5",
  "defaultThinkingLevel": "medium",
  "theme": "dark"
}

The trust prompt controls which project-local configuration and executable resources Pi loads. A denial blocks .pi/settings.json, project extensions, skills, prompt templates, themes, packages, and project system-prompt files. General AGENTS.md and CLAUDE.md discovery follows the separate context-file setting. Command isolation is configured through sandboxing.

Extensions, Skills, and Packages

Pi separates runtime changes, reusable instructions, and distributable bundles. TypeScript extensions handle the runtime layer by registering model tools, commands, shortcuts, event handlers, provider logic, permission checks, or terminal interface components. They also implement MCP connections, subagents, plan mode, sandbox execution, and custom compaction.

Skills hold reusable agent instructions in SKILL.md files. Pi loads relevant skills automatically, and /skill:name invokes one directly. Their instructions teach a repeatable method, while executable behavior belongs in extensions.

Pi packages distribute extensions and skills together with prompt templates or themes through npm and Git. Manage them with pi install, pi remove, pi list, pi update, and pi config. A project-local install uses -l and stores its managed files under the project’s .pi directory.

Prompt templates are reusable prompts invoked by name. Themes change terminal colors and reload while Pi is running. Together with skills, these resources shape how a session looks and how the agent approaches a task. Extensions are the executable layer.

Local extensions are discovered in ~/.pi/agent/extensions/ and .pi/extensions/. The --extension option loads one file for a single run. The repository’s examples demonstrate permission gates, protected paths, sandbox execution, subagents, plan mode, presets, Git checkpoints, remote SSH tools, and custom providers. Those examples are source files, not preinstalled commands. Copy the chosen example, load its file directly, or install a package that distributes it.

Install a package from npm, a Git repository, or a local source. Add -l to keep it inside the current project. Global Git packages live under ~/.pi/agent/git; project Git packages live under .pi/git. npm packages use matching global and project package directories.

pi install npm:@scope/pi-package
pi install https://github.com/owner/pi-package
pi install -l ./local-package
pi list
pi config

pi update refreshes eligible packages. A Git source pinned to a commit, tag, or branch reference stays pinned during ordinary updates until you install a different reference. pi remove and pi uninstall remove a managed package. Package code has the same operating-system permissions as Pi. Inspect the source and dependency scripts first.

Model Providers and Subscription Access

Configured provider catalogs refresh automatically. pi update --models forces an immediate refresh. Custom model entries belong in ~/.pi/agent/models.json; a provider with custom authentication or streaming behavior requires an extension.

Subscription login stores provider credentials through Pi’s authentication flow. API access reads the corresponding environment variable or configured credential. /logout removes a selected login. The model selector identifies the provider, context size, image capability, and reasoning options reported by the catalog.

The built-in llama.cpp integration manages local models through /llama. It finds compatible files, downloads a model, starts or stops a router, and exposes loaded models to /model. Local inference depends on available memory, accelerator support, quantization, and model size. Pi supplies the agent loop; the chosen local model determines coding quality and speed.

Automation, JSON, RPC, and the SDK

For shell scripts and CI jobs, print mode runs a prompt and returns the final response. Standard input can supply a prompt or file content, @file arguments attach files, and compatible models accept image inputs from the CLI.

pi -p "Explain the authentication flow"
git diff | pi -p "Review this diff for correctness"
pi -p @screenshot.png "Find the layout problem"

JSON mode emits structured events for messages, tool calls, results, errors, token accounting, and session state. Choose it when another process needs to observe a run. RPC handles workflows that also need to steer the session.

pi --mode json -p "Run the unit tests and summarize failures"

RPC mode starts a long-lived process that reads and writes line-delimited JSON. Each request and event occupies one line. An editor, desktop application, or service sends prompts, steers the agent, changes models, compacts context, and inspects session state through that channel.

pi --mode rpc

The Node.js SDK provides direct access to the same harness. An application creates an agent session, selects a model runtime, chooses a session manager, and subscribes to events. This route fits a custom interface or internal coding service that needs Pi’s session and extension system inside its own process.

import {
  createAgentSession,
  SessionManager
} from "@earendil-works/pi-coding-agent";
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory()
});
await session.prompt("Inspect this project and identify its test command.");

Offline Mode, Telemetry, and Data Flow

PI_OFFLINE=1 skips startup network operations such as update checks, package checks, model-catalog refreshes, and telemetry. Cloud inference continues to use the selected provider’s network service. Pair the flag with a local model route and local-only extensions for a fully local run.

PI_OFFLINE=1 pi

PI_SKIP_VERSION_CHECK=1 disables the version check only. PI_TELEMETRY=0 controls telemetry but leaves version and package checks available. The httpProxy setting routes supported network requests through a proxy.

A cloud model receives the prompt, selected conversation context, tool results included in the conversation, and any attached file or image content. Pi stores sessions and settings locally. Extensions can add their own network requests and storage behavior. Review them separately. The shell tool also passes session, provider, model, and reasoning metadata through PI_* environment variables to child commands.

Workflow Components Added Separately

• Add MCP through an extension or package.
• Run subagents through an extension, a package, or separate Pi processes.
• Add plan mode through an extension, package, or a plan stored in a file.
• Build per-command permission prompts with an extension-defined confirmation flow.
• Use a separate client for browser or mobile access.
• Run background shell jobs outside the default harness.

Pi vs Claude Code

Pi and Claude Code both work from a terminal, edit project files, and run shell commands. Pi is an MIT-licensed harness with multiple model access routes and a TypeScript extension API. Claude Code is an Anthropic application built around Claude accounts, Anthropic API access, and supported cloud platforms.

Pi keeps the default agent small and moves MCP, plan mode, subagents, and permission gates into extensions. Claude Code supplies more first-party clients and configuration for its own coding environment.

Security and Project Trust

Pi asks for a trust decision before loading project-local settings, Pi resources, system-prompt files, and packages from a folder with no saved decision. Interactive sessions display the prompt. Non-interactive runs use the global defaultProjectTrust setting unless you pass --approve or --no-approve.

The trust decision governs project-resource loading. Extensions execute arbitrary code, and skills can direct the model to run executables. Review a package’s source and dependencies before installation, then use a container or isolated environment for an unfamiliar repository or extension.

Cloud model requests send the prompt and selected session context to the chosen provider. A local llama.cpp router keeps model inference on your machine, while extensions and shell commands retain their own file, process, and network access. A complete sandbox must constrain those components as well.

Common Setup and Usage Problems

A missing pi command usually points to npm’s global binary directory. Confirm that directory is on PATH. A Node.js version error requires Node 22.19.0 or newer, while a Windows shell error usually calls for Git for Windows or a correct shellPath to bash.exe.

An empty model list needs an authenticated provider or a running local route. Use /login for subscription access or set the required API credential, then run pi update --models. For local inference, confirm that the llama.cpp router is running and /llama reports a loaded model.

Missing project resources often trace back to the saved trust decision; inspect it with /trust. After editing settings, skills, extensions, themes, prompt templates, or context files, run /reload. Use --no-session for a disposable troubleshooting run that leaves the session directory unchanged.

Frequent context-limit warnings call for a smaller working set. Run /compact, start a focused branch through /tree, or open a new session. Large generated files and verbose command output consume context rapidly. Narrow the command or use !! for terminal-only output.

Pros

• Branches share one JSONL history.
• Extensions replace built-in tools.
• Runtime components hot-reload during sessions.
• RPC exposes live session control.
• SDK reuses the agent harness.
• Four-tool default keeps Pi small.

Cons

• MCP needs an extension.
• Subagents need an extension.
• Permission gates need custom logic.
• Local models depend on your hardware.

Alternatives and Related Resources

• 7 Best CLI AI Coding Agents (Open Source)
• Qwen Code CLI: Open-source Command-line AI Agent
• Kimi Code CLI: Open-Source AI Coding Agent with Skills & MCP Support
• Pi Coding Agent Official Documentation

FAQs

Q: How do I change Pi’s keyboard shortcuts?
A: Create ~/.pi/agent/keybindings.json and map Pi’s namespaced action IDs to one or more key combinations. Run /reload after saving the file. This also resolves terminal conflicts such as Alt+Enter on Windows.

Q: Can I change where Pi stores sessions?
A: Yes. Pass --session-dir <dir> for one run, set PI_CODING_AGENT_SESSION_DIR for an environment, or add sessionDir to settings.json. The CLI option has the highest priority.

Q: Can Pi import a saved JSONL session?
A: Yes. Run /import <file> inside Pi to load a JSONL session and continue it. Use this for a session received from another machine or restored from a backup.

Q: What happens when I delete a Pi session?
A: The session picker asks for confirmation. When the trash command is available, Pi sends the JSONL file to the operating system’s trash, where it can be recovered.

Q: Can I replace the system prompt for one Pi run?
A: Yes. Pass --system-prompt "..." to replace the default prompt or --append-system-prompt "..." to add instructions for that process. Pi continues to load context files and skills as separate inputs.

Last Updated: July 30, 2026