# Overview

> What pi is, the four run modes, default tools, and the first docs routes for CLI users and embedders.

- Repository: earendil-works/pi
- GitHub: https://github.com/earendil-works/pi
- Human docs: https://grok-wiki.com/public/docs/earendil-works-pi-7860a70e44d1
- Complete Markdown: https://grok-wiki.com/public/docs/earendil-works-pi-7860a70e44d1/llms-full.txt

## Source Files

- `packages/coding-agent/README.md`
- `packages/coding-agent/package.json`
- `packages/coding-agent/examples/README.md`
- `packages/coding-agent/src/core/agent-session.ts`
- `packages/coding-agent/src/cli/args.ts`

---

---
title: "Overview"
description: "What pi is, the four run modes, default tools, and the first docs routes for CLI users and embedders."
---

`@earendil-works/pi-coding-agent` (package version `0.84.1`) is the coding-agent package for **pi**: a minimal terminal coding harness with the `pi` binary (`dist/cli.js`), default tools `read` / `write` / `edit` / `bash`, session management, and four run surfaces—interactive TUI, print/JSON, RPC process integration, and an embeddable SDK.

## What pi is

Pi is designed so you adapt the agent to your workflow instead of forking internals. Core product facts from the package surface:

| Item | Value |
|------|--------|
| npm package | `@earendil-works/pi-coding-agent` |
| description | Coding agent CLI with `read`, `bash`, `edit`, `write` tools and session management |
| bin | `pi` → `dist/cli.js` |
| main / types | `./dist/index.js`, `./dist/index.d.ts` |
| module type | ESM (`"type": "module"`) |
| config dir key | `piConfig.configDir` = `.pi` |
| Node engine | `>=22.19.0` |
| license | MIT |
| repository | `github.com/earendil-works/pi` (`packages/coding-agent`) |

**Defaults, not a full product suite:** pi ships with strong defaults and intentionally omits built-in features such as sub-agents and plan mode. Those capabilities come from skills, prompt templates, TypeScript extensions, themes, or third-party Pi packages (npm or git)—or by asking pi to build what you need.

**Extension surfaces (product terms):**

- TypeScript **extensions**
- **Skills**
- **Prompt templates**
- **Themes**
- Shareable **Pi packages** that bundle the above

## Four run modes

README product modes and the CLI/package entry points that implement them:

| Product mode | Role | Entry / flags (evidence) |
|--------------|------|---------------------------|
| **Interactive** | Full terminal UI (header, messages, editor, footer) | Default `pi` TUI; optional `--tui-mode regular\|fullscreen` |
| **Print / JSON** | Non-interactive output for scripts and automation | `--print` / `-p` (optional message); CLI `--mode text\|json` |
| **RPC** | Process integration over a machine protocol | `--mode rpc`; package export `./rpc-entry` → `dist/rpc-entry.js` |
| **SDK** | Embed in your own apps | Package main export `./dist/index.js`; examples use `createAgentSession()` |

CLI mode values accepted by `--mode`:

```ts
export type Mode = "text" | "json" | "rpc";
```

Shared runtime: `AgentSession` is the core lifecycle abstraction used across interactive, print, and RPC. Modes add their own I/O on top of the same session engine (agent state, event subscription + session persistence, model/thinking control, compaction, bash, session switch/branch).

```mermaid
flowchart TB
  subgraph entry ["Entry surfaces"]
    CLI["pi bin<br/>dist/cli.js"]
    RPC["@earendil-works/pi-coding-agent/rpc-entry<br/>dist/rpc-entry.js"]
    SDK["package main<br/>dist/index.js<br/>createAgentSession()"]
  end

  subgraph modes ["Run modes"]
    I["Interactive TUI"]
    P["Print / JSON<br/>--print, --mode text|json"]
    R["RPC<br/>--mode rpc"]
    S["SDK embed"]
  end

  subgraph core ["Shared session core"]
    AS["AgentSession<br/>src/core/agent-session.ts"]
    Tools["Built-in tools<br/>read · bash · edit · write"]
  end

  CLI --> I
  CLI --> P
  CLI --> R
  RPC --> R
  SDK --> S
  I --> AS
  P --> AS
  R --> AS
  S --> AS
  AS --> Tools
```

<Note>
Print/JSON and RPC are selected on the CLI with `--mode` and/or `--print`. SDK embedding uses the package main export rather than the interactive TUI. Details for each mode live on the dedicated run-mode, RPC, and SDK pages.
</Note>

## Default tools

By default the model receives four built-in tools:

| Tool | Role (product default) |
|------|-------------------------|
| `read` | Read project files |
| `write` | Create / write files |
| `edit` | Edit existing files |
| `bash` | Run shell commands |

`AgentSessionConfig` documents the same default active set:

```ts
/** Initial active built-in tool names. Default: [read, bash, edit, write] */
initialActiveToolNames?: string[];
```

Tool exposure can be constrained at session construction:

| Config field | Effect |
|--------------|--------|
| `allowedToolNames` | Allowlist: only these tool names are exposed |
| `excludedToolNames` | Denylist: these tool names are not exposed |
| `baseToolsOverride` | Replace base tools (custom runtimes); synthesized into minimal `ToolDefinition`s |
| `customTools` | SDK custom tools registered outside extensions |

CLI flags that filter tools (parsed in `src/cli/args.ts`):

| Flag | Short | Effect |
|------|-------|--------|
| `--tools <names>` | `-t` | Comma-separated tool name list |
| `--exclude-tools <names>` | `-xt` | Comma-separated denylist |
| `--no-tools` | `-nt` | Disable tools |
| `--no-builtin-tools` | `-nbt` | Disable built-in tools |

Capabilities beyond the four defaults come from skills, prompt templates, extensions, or Pi packages—not from expanding the built-in set by default.

## Package exports (embedders)

Public npm surface for `@earendil-works/pi-coding-agent`:

| Export | Path | Use |
|--------|------|-----|
| `.` (main) | `dist/index.js` (+ types) | SDK / programmatic embedding |
| `./rpc-entry` | `dist/rpc-entry.js` | RPC process entry |
| `./client` | `dist/client/index.js` (+ types) | Client API surface |
| bin `pi` | `dist/cli.js` | CLI |

Published package files include `dist`, `docs`, `examples`, `containerization.md`, `CHANGELOG.md`, and `npm-shrinkwrap.json`.

Examples under `packages/coding-agent/examples/`:

- **`sdk/`** — programmatic usage via `createAgentSession()` (models, prompts, tools, extensions, session management)
- **`extensions/`** — lifecycle handlers, custom tools, commands/keybindings, UI, git hooks, system prompt / compaction, external integrations, custom providers

## First run (CLI)

Install paths:

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

`--ignore-scripts` disables dependency lifecycle scripts; pi does not require install scripts for normal npm installs.

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

Authenticate, then start interactive pi:

```bash
# API key (example provider env)
export ANTHROPIC_API_KEY=sk-ant-...
pi
```

```bash
# Or subscription /login in the TUI
pi
/login   # then select provider
```

Providers are BYOK and multi-provider: subscriptions (for example Anthropic Claude Pro/Max, OpenAI ChatGPT Plus/Pro Codex, GitHub Copilot) and many API-key providers (Anthropic, OpenAI, Azure OpenAI, Google Gemini/Vertex, Amazon Bedrock, xAI, OpenRouter, and others listed in the package README). Custom providers can be added via `~/.pi/agent/models.json` when they speak a supported API (OpenAI, Anthropic, Google); custom APIs or OAuth use extensions. Local llama.cpp router is configured with `/login llama.cpp` and `/llama`.

## Interactive UI (quick map)

Default interactive layout:

1. **Startup header** — shortcuts (`/hotkeys`), loaded `AGENTS.md`, prompt templates, skills, extensions  
2. **Messages** — user/assistant turns, tool calls/results, notifications, errors, extension UI  
3. **Editor** — input; border color reflects thinking level  
4. **Footer** — cwd, session name, token/cache usage, cost, context usage, current model  

Representative slash commands (type `/` in the editor):

| Command | Description |
|---------|-------------|
| `/login`, `/logout` | Provider credentials |
| `/model` | Switch models |
| `/settings` | Thinking level, theme, message delivery, transport |
| `/resume`, `/new` | Session lifecycle |
| `/tree` | Jump in the session tree |
| `/fork`, `/clone` | Branch-related session ops |
| `/compact [prompt]` | Manual context compaction |
| `/export [file]` | Export session to HTML or JSONL |

Skills appear as `/skill:name`; prompt templates expand as `/templatename`. Extensions can register additional commands and replace or decorate the editor.

## Shared session core

`AgentSession` (`src/core/agent-session.ts`) owns:

- Agent state access  
- Event subscription with automatic session persistence  
- Model and thinking-level management  
- Compaction (manual and auto; reasons include `manual`, `threshold`, `overflow`)  
- Bash execution  
- Session switching and branching  

Session events include (non-exhaustive): `agent_end` (with `willRetry`), `agent_settled`, `queue_update`, `compaction_start` / `compaction_end`, `entry_appended`, `session_info_changed`, `thinking_level_changed`, auto-retry and summarization-retry events, and `bash_execution_update`.

Resource loading for a session covers extensions, skills, prompts, themes, context files, and the system prompt via `resourceLoader` on `AgentSessionConfig`.

## Useful CLI flags (overview)

Parsed in `src/cli/args.ts` (not a full flag reference):

| Area | Flags |
|------|--------|
| Mode / print | `--mode text\|json\|rpc`, `--print` / `-p` |
| Model / auth | `--provider`, `--model`, `--api-key`, `--models`, `--list-models`, `--thinking` |
| Session | `--continue` / `-c`, `--resume` / `-r`, `--session`, `--session-id`, `--session-dir`, `--fork`, `--name` / `-n`, `--no-session` |
| Tools | `--tools` / `-t`, `--exclude-tools` / `-xt`, `--no-tools` / `-nt`, `--no-builtin-tools` / `-nbt` |
| Resources | `--extension` / `-e`, `--no-extensions` / `-ne`, `--skill`, `--no-skills` / `-ns`, `--prompt-template`, `--no-prompt-templates` / `-np`, `--theme`, `--no-themes`, `--no-context-files` / `-nc` |
| Other | `--system-prompt`, `--append-system-prompt`, `--export`, `--tui-mode`, `--offline`, `--verbose`, `--approve` / `-a`, `--no-approve` / `-na`, `@file` args |

Valid thinking levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`.

## Who should open which docs next

| Audience | Start here |
|----------|------------|
| New CLI users | Install → authenticate → interactive session with default tools |
| Script / CI users | Print/JSON and CLI flags |
| Process integrators | RPC entry and `--mode rpc` |
| App embedders | Package main export, `createAgentSession()`, SDK examples |
| Extenders | Skills, extensions, prompt templates, themes, Pi packages |

## Next

<CardGroup cols={2}>
  <Card title="Installation" href="/installation">
    npm and installer paths, bin entry, package exports, and verification for `@earendil-works/pi-coding-agent`.
  </Card>
  <Card title="Quickstart" href="/quickstart">
    Install, authenticate with API key or `/login`, start interactive `pi`, and confirm the default tool surface.
  </Card>
  <Card title="Run modes" href="/run-modes">
    Interactive, print/JSON, RPC, and SDK: invocation, entry points, and when to choose each.
  </Card>
  <Card title="SDK" href="/sdk">
    Embed pi via the package main export: agent construction, hooks, custom models, tools, and settings.
  </Card>
  <Card title="Tools and allowlists" href="/tools">
    Default read/write/edit/bash tools, extension tools, allowlist and exclude-tools filters.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    `pi` binary flags, argument parsing, auth-related entry points, and package bin wiring.
  </Card>
  <Card title="Package exports" href="/package-exports">
    Public npm surface: main, rpc-entry, client, bin name, and `piConfig.configDir`.
  </Card>
  <Card title="SDK examples" href="/sdk-examples">
    Copy-paste recipes for minimal agents, custom models, skills, tools, extensions, and sessions.
  </Card>
</CardGroup>