diff --git a/packages/coding-agent/docs/docs.json b/packages/coding-agent/docs/docs.json index 94746c303..34d12d37a 100644 --- a/packages/coding-agent/docs/docs.json +++ b/packages/coding-agent/docs/docs.json @@ -7,6 +7,14 @@ "title": "Overview", "path": "index.md" }, + { + "title": "Quickstart", + "path": "quickstart.md" + }, + { + "title": "Using Pi", + "path": "usage.md" + }, { "title": "Providers", "path": "providers.md" diff --git a/packages/coding-agent/docs/index.md b/packages/coding-agent/docs/index.md index eb4091e83..dc55a895b 100644 --- a/packages/coding-agent/docs/index.md +++ b/packages/coding-agent/docs/index.md @@ -10,7 +10,7 @@ Install pi with npm: npm install -g @mariozechner/pi-coding-agent ``` -And run it: +Then run it in a project directory: ```bash pi @@ -18,11 +18,12 @@ pi Authenticate with `/login` for subscription providers, or set an API key such as `ANTHROPIC_API_KEY` before starting pi. -Once you are signed in, you can ask pi about itself and it will answer you. No -need to read the docs yourself ;-) +For the full first-run flow, see [Quickstart](quickstart.md). ## Start here +- [Quickstart](quickstart.md) - install, authenticate, and run a first session. +- [Using Pi](usage.md) - interactive mode, slash commands, context files, and CLI reference. - [Providers](providers.md) - subscription and API-key setup for built-in providers. - [Settings](settings.md) - global and project settings. - [Keybindings](keybindings.md) - default shortcuts and custom keybindings. diff --git a/packages/coding-agent/docs/quickstart.md b/packages/coding-agent/docs/quickstart.md new file mode 100644 index 000000000..8d1499fe7 --- /dev/null +++ b/packages/coding-agent/docs/quickstart.md @@ -0,0 +1,142 @@ +# Quickstart + +This page gets you from install to a useful first pi session. + +## Install + +Pi is distributed as an npm package: + +```bash +npm install -g @mariozechner/pi-coding-agent +``` + +Then start pi in the project directory you want it to work on: + +```bash +cd /path/to/project +pi +``` + +## Authenticate + +Pi can use subscription providers through `/login`, or API-key providers through environment variables or the auth file. + +### Option 1: subscription login + +Start pi and run: + +```text +/login +``` + +Then select a provider. Built-in subscription logins include Claude Pro/Max, ChatGPT Plus/Pro (Codex), GitHub Copilot, Google Gemini CLI, and Google Antigravity. + +### Option 2: API key + +Set an API key before launching pi: + +```bash +export ANTHROPIC_API_KEY=sk-ant-... +pi +``` + +You can also run `/login` and select an API-key provider to store the key in `~/.pi/agent/auth.json`. + +See [Providers](providers.md) for all supported providers, environment variables, and cloud-provider setup. + +## First session + +Once pi starts, type a request and press Enter: + +```text +Summarize this repository and tell me how to run its checks. +``` + +By default, pi gives the model four tools: + +- `read` - read files +- `write` - create or overwrite files +- `edit` - patch files +- `bash` - run shell commands + +Additional built-in read-only tools (`grep`, `find`, `ls`) are available through tool options. Pi runs in your current working directory and can modify files there. Use git or another checkpointing workflow if you want easy rollback. + +## Give pi project instructions + +Pi loads context files at startup. Add an `AGENTS.md` file to tell it how to work in a project: + +```markdown +# Project Instructions + +- Run `npm run check` after code changes. +- Do not run production migrations locally. +- Keep responses concise. +``` + +Pi loads: + +- `~/.pi/agent/AGENTS.md` for global instructions +- `AGENTS.md` or `CLAUDE.md` from parent directories and the current directory + +Restart pi, or run `/reload`, after changing context files. + +## Common things to try + +### Reference files + +Type `@` in the editor to fuzzy-search files, or pass files on the command line: + +```bash +pi @README.md "Summarize this" +pi @src/app.ts @src/app.test.ts "Review these together" +``` + +Images can be pasted with Ctrl+V (Alt+V on Windows) or dragged into supported terminals. + +### Run shell commands + +In interactive mode: + +```text +!npm run lint +``` + +The command output is sent to the model. Use `!!command` to run a command without adding its output to the model context. + +### Switch models + +Use `/model` or Ctrl+L to choose a model. Use Shift+Tab to cycle thinking level. Use Ctrl+P / Shift+Ctrl+P to cycle through scoped models. + +### Continue later + +Sessions are saved automatically: + +```bash +pi -c # Continue most recent session +pi -r # Browse previous sessions +pi --session # Open a specific session +``` + +Inside pi, use `/resume`, `/new`, `/tree`, `/fork`, and `/clone` to manage sessions. + +### Non-interactive mode + +For one-shot prompts: + +```bash +pi -p "Summarize this codebase" +cat README.md | pi -p "Summarize this text" +pi -p @screenshot.png "What's in this image?" +``` + +Use `--mode json` for JSON event output or `--mode rpc` for process integration. + +## Next steps + +- [Using Pi](usage.md) - interactive mode, slash commands, sessions, context files, and CLI reference. +- [Providers](providers.md) - authentication and model setup. +- [Settings](settings.md) - global and project configuration. +- [Keybindings](keybindings.md) - shortcuts and customization. +- [Pi Packages](packages.md) - install shared extensions, skills, prompts, and themes. + +Platform notes: [Windows](windows.md), [Termux](termux.md), [tmux](tmux.md), [Terminal setup](terminal-setup.md), [Shell aliases](shell-aliases.md). diff --git a/packages/coding-agent/docs/usage.md b/packages/coding-agent/docs/usage.md new file mode 100644 index 000000000..120846769 --- /dev/null +++ b/packages/coding-agent/docs/usage.md @@ -0,0 +1,275 @@ +# Using Pi + +This page collects day-to-day usage details that do not fit on the quickstart page. + +## Interactive Mode + +

Interactive Mode

+ +The interface has four main areas: + +- **Startup header** - shortcuts, loaded context files, prompt templates, skills, and extensions +- **Messages** - user messages, assistant responses, tool calls, tool results, notifications, errors, and extension UI +- **Editor** - where you type; border color indicates the current thinking level +- **Footer** - working directory, session name, token/cache usage, cost, context usage, and current model + +The editor can be replaced temporarily by built-in UI such as `/settings` or by custom extension UI. + +### Editor Features + +| Feature | How | +|---------|-----| +| File reference | Type `@` to fuzzy-search project files | +| Path completion | Press Tab to complete paths | +| Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal | +| Images | Paste with Ctrl+V, Alt+V on Windows, or drag into the terminal | +| Shell command | `!command` runs and sends output to the model | +| Hidden shell command | `!!command` runs without sending output to the model | +| External editor | Ctrl+G opens `$VISUAL` or `$EDITOR` | + +See [Keybindings](keybindings.md) for all shortcuts and customization. + +## Slash Commands + +Type `/` in the editor to open command completion. Extensions can register custom commands, skills are available as `/skill:name`, and prompt templates expand via `/templatename`. + +| Command | Description | +|---------|-------------| +| `/login`, `/logout` | Manage OAuth or API-key credentials | +| `/model` | Switch models | +| `/scoped-models` | Enable/disable models for Ctrl+P cycling | +| `/settings` | Thinking level, theme, message delivery, transport | +| `/resume` | Pick from previous sessions | +| `/new` | Start a new session | +| `/name ` | Set session display name | +| `/session` | Show session file, ID, messages, tokens, and cost | +| `/tree` | Jump to any point in the session and continue from there | +| `/fork` | Create a new session from a previous user message | +| `/clone` | Duplicate the current active branch into a new session | +| `/compact [prompt]` | Manually compact context, optionally with custom instructions | +| `/copy` | Copy last assistant message to clipboard | +| `/export [file]` | Export session to HTML | +| `/share` | Upload as private GitHub gist with shareable HTML link | +| `/reload` | Reload keybindings, extensions, skills, prompts, and context files | +| `/hotkeys` | Show all keyboard shortcuts | +| `/changelog` | Display version history | +| `/quit` | Quit pi | + +## Message Queue + +You can submit messages while the agent is still working: + +- **Enter** queues a steering message, delivered after the current assistant turn finishes executing its tool calls. +- **Alt+Enter** queues a follow-up message, delivered after the agent finishes all work. +- **Escape** aborts and restores queued messages to the editor. +- **Alt+Up** retrieves queued messages back to the editor. + +On Windows Terminal, Alt+Enter is fullscreen by default. Remap it as described in [Terminal setup](terminal-setup.md) if you want pi to receive the shortcut. + +Configure delivery in [Settings](settings.md) with `steeringMode` and `followUpMode`. + +## Sessions + +Sessions are saved automatically to `~/.pi/agent/sessions/`, organized by working directory. + +```bash +pi -c # Continue most recent session +pi -r # Browse and select a session +pi --no-session # Ephemeral mode; do not save +pi --session # Use a specific session file or session ID +pi --fork # Fork a session into a new session file +``` + +Useful session commands: + +- `/session` shows the current session file and ID. +- `/tree` navigates the in-file session tree and can summarize abandoned branches. +- `/fork` creates a new session from an earlier user message. +- `/clone` duplicates the current active branch into a new session file. +- `/compact` summarizes older messages to free context. + +See [Sessions](session.md), [Session Tree](tree.md), and [Compaction](compaction.md) for details. + +## Context Files + +Pi loads `AGENTS.md` or `CLAUDE.md` at startup from: + +- `~/.pi/agent/AGENTS.md` for global instructions +- parent directories, walking up from the current working directory +- the current directory + +Use context files for project conventions, commands, safety rules, and preferences. Disable loading with `--no-context-files` or `-nc`. + +### System Prompt Files + +Replace the default system prompt with: + +- `.pi/SYSTEM.md` for a project +- `~/.pi/agent/SYSTEM.md` globally + +Append to the default prompt without replacing it with `APPEND_SYSTEM.md` in either location. + +## Exporting and Sharing Sessions + +Use `/export [file]` to write a session to HTML. + +Use `/share` to upload a private GitHub gist with a shareable HTML link. + +If you use pi for open source work and want to publish sessions for model, prompt, tool, and evaluation research, see [`badlogic/pi-share-hf`](https://github.com/badlogic/pi-share-hf). It publishes sessions to Hugging Face datasets. + +## CLI Reference + +```bash +pi [options] [@files...] [messages...] +``` + +### Package Commands + +```bash +pi install [-l] # Install package, -l for project-local +pi remove [-l] # Remove package +pi uninstall [-l] # Alias for remove +pi update [source|self|pi] # Update pi and packages; skips pinned packages +pi update --extensions # Update packages only +pi update --self # Update pi only +pi update --extension # Update one package +pi list # List installed packages +pi config # Enable/disable package resources +``` + +See [Pi Packages](packages.md) for package sources and security notes. + +### Modes + +| Flag | Description | +|------|-------------| +| default | Interactive mode | +| `-p`, `--print` | Print response and exit | +| `--mode json` | Output all events as JSON lines; see [JSON mode](json.md) | +| `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](rpc.md) | +| `--export [out]` | Export a session to HTML | + +In print mode, pi also reads piped stdin and merges it into the initial prompt: + +```bash +cat README.md | pi -p "Summarize this text" +``` + +### Model Options + +| Option | Description | +|--------|-------------| +| `--provider ` | Provider, such as `anthropic`, `openai`, or `google` | +| `--model ` | Model pattern or ID; supports `provider/id` and optional `:` | +| `--api-key ` | API key, overriding environment variables | +| `--thinking ` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` | +| `--models ` | Comma-separated patterns for Ctrl+P cycling | +| `--list-models [search]` | List available models | + +### Session Options + +| Option | Description | +|--------|-------------| +| `-c`, `--continue` | Continue the most recent session | +| `-r`, `--resume` | Browse and select a session | +| `--session ` | Use a specific session file or partial UUID | +| `--fork ` | Fork a session file or partial UUID into a new session | +| `--session-dir ` | Custom session storage directory | +| `--no-session` | Ephemeral mode; do not save | + +### Tool Options + +| Option | Description | +|--------|-------------| +| `--tools `, `-t ` | Allowlist specific built-in, extension, and custom tools | +| `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep extension/custom tools enabled | +| `--no-tools`, `-nt` | Disable all tools | + +Built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`. + +### Resource Options + +| Option | Description | +|--------|-------------| +| `-e`, `--extension ` | Load an extension from path, npm, or git; repeatable | +| `--no-extensions` | Disable extension discovery | +| `--skill ` | Load a skill; repeatable | +| `--no-skills` | Disable skill discovery | +| `--prompt-template ` | Load a prompt template; repeatable | +| `--no-prompt-templates` | Disable prompt template discovery | +| `--theme ` | Load a theme; repeatable | +| `--no-themes` | Disable theme discovery | +| `--no-context-files`, `-nc` | Disable `AGENTS.md` and `CLAUDE.md` discovery | + +Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings. Example: + +```bash +pi --no-extensions -e ./my-extension.ts +``` + +### Other Options + +| Option | Description | +|--------|-------------| +| `--system-prompt ` | Replace default prompt; context files and skills are still appended | +| `--append-system-prompt ` | Append to system prompt | +| `--verbose` | Force verbose startup | +| `-h`, `--help` | Show help | +| `-v`, `--version` | Show version | + +### File Arguments + +Prefix files with `@` to include them in the message: + +```bash +pi @prompt.md "Answer this" +pi -p @screenshot.png "What's in this image?" +pi @code.ts @test.ts "Review these files" +``` + +### Examples + +```bash +# Interactive with initial prompt +pi "List all .ts files in src/" + +# Non-interactive +pi -p "Summarize this codebase" + +# Non-interactive with piped stdin +cat README.md | pi -p "Summarize this text" + +# Different model +pi --provider openai --model gpt-4o "Help me refactor" + +# Model with provider prefix +pi --model openai/gpt-4o "Help me refactor" + +# Model with thinking level shorthand +pi --model sonnet:high "Solve this complex problem" + +# Limit model cycling +pi --models "claude-*,gpt-4o" + +# Read-only mode +pi --tools read,grep,find,ls -p "Review the code" +``` + +### Environment Variables + +| Variable | Description | +|----------|-------------| +| `PI_CODING_AGENT_DIR` | Override config directory; default is `~/.pi/agent` | +| `PI_PACKAGE_DIR` | Override package directory, useful for Nix/Guix store paths | +| `PI_SKIP_VERSION_CHECK` | Skip version check at startup | +| `PI_TELEMETRY` | Override install telemetry: `1`/`true`/`yes` or `0`/`false`/`no` | +| `PI_CACHE_RETENTION` | Set to `long` for extended prompt cache where supported | +| `VISUAL`, `EDITOR` | External editor for Ctrl+G | + +## Design Principles + +Pi keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages. + +It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. You can build or install those workflows as extensions or packages, or use external tools such as containers and tmux. + +For the full rationale, read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/).