Using the Coding Agent CLI

The Coding Agent CLI, pi, is an interactive command-line AI assistant designed for software development tasks. It leverages large language models with a suite of tools to read files, execute bash commands, and modify code within a user's local environment. The agent supports persistent sessions, allowing users to continue conversations across multiple invocations.

The CLI is highly configurable through command-line arguments, environment variables, and configuration files. It operates in several modes, including a rich interactive Terminal UI (TUI), a non-interactive single-shot mode for scripting, and a headless RPC mode for programmatic integration.

Sources: packages/coding-agent/src/main.ts:310-312, README.md:6-8

Startup and Initialization

The application's entry point is the main function, which orchestrates the entire setup and execution flow. It begins by parsing command-line arguments, setting up session management, resolving the initial AI model, and constructing the system prompt. Based on the parsed arguments, it then routes execution to the appropriate mode (interactive, single-shot, or RPC).

Sources: packages/coding-agent/src/main.ts:1455-1458

This diagram illustrates the initialization sequence of the CLI.

Command-Line Arguments

The CLI's behavior is primarily controlled through command-line arguments. The following table summarizes the available options.

Sources: packages/coding-agent/src/main.ts:93-176, packages/coding-agent/src/main.ts:313-368

Execution Modes

The agent can run in one of three distinct modes, determined by the --mode and --print flags.

Sources: packages/coding-agent/src/main.ts:1612-1614

Interactive Mode

This is the default mode, providing a full-featured Terminal User Interface (TUI) for chatting with the agent. It is initiated when no --print or --mode flags are provided. This mode is managed by the TuiRenderer class, which handles all user input, event rendering, and UI components like selectors and the chat view.

The interactive loop waits for user input, sends it to the agent, and renders the agent's responses, including text, tool calls, and thinking steps, in real-time.

Sources: packages/coding-agent/src/main.ts:882-918, packages/coding-agent/src/tui/tui-renderer.ts:1003-1033

Single-Shot Mode

Activated with the --print (-p) flag, this mode is non-interactive. The agent processes the initial prompt, prints the final assistant message to standard output, and exits. It supports two output formats via --mode:

• text: (Default) Prints only the final text content from the assistant.
• json: Prints all agent events as a stream of JSON objects.

This mode is ideal for scripting and integrating the agent into automated workflows.

Sources: packages/coding-agent/src/main.ts:921-965

RPC Mode

Activated with --mode rpc, this mode runs the agent as a headless server that communicates over stdin/stdout using JSON-RPC. It listens for JSON commands on stdin and emits agent events as JSON objects on stdout. This mode is designed for tight integration with other applications, such as IDE extensions or web UIs.

The following diagram shows how RPC commands are processed.

System Prompt and Context

On startup, the agent's system prompt is dynamically constructed to provide it with essential context. The buildSystemPrompt function assembles this prompt.

Sources: packages/coding-agent/src/main.ts:422-424

The prompt includes:

1. Core Identity: Defines the agent as an expert coding assistant.
2. Tool Definitions: A list of enabled tools and their descriptions.
3. Guidelines: Best practices for using the tools, such as preferring read before edit.
4. Documentation Pointers: Paths to its own README.md for self-reference.
5. Project Context Files: Content from AGENTS.md or CLAUDE.md files.
6. Real-time Information: The current date, time, and working directory.

Sources: packages/coding-agent/src/main.ts:474-546

Project Context Files

The agent automatically loads context from special files named AGENTS.md or CLAUDE.md (with AGENTS.md having priority). This allows for project-specific instructions. The loading follows a specific hierarchy:

Sources: packages/coding-agent/src/main.ts:571-615

Tools

The agent is equipped with a set of tools to interact with the local file system and shell. The default tools are read, bash, edit, and write.

Sources: packages/coding-agent/src/main.ts:371-380, packages/coding-agent/test/tools.test.ts

The set of active tools can be customized using the --tools command-line argument. Some tools, like find and grep, rely on external binaries (fd and ripgrep respectively). The ensureTool function will automatically download and install these if they are not found on the system PATH.

Sources: packages/coding-agent/src/main.ts:133-146, packages/coding-agent/src/tools-manager.ts:182-203

Slash Commands

The interactive TUI supports slash commands for performing meta-actions and accessing features outside the standard chat flow.

Built-in Commands

Sources: packages/coding-agent/src/tui/tui-renderer.ts:192-288

Custom File-Based Commands

Users can create their own custom slash commands by placing .md files in specific directories. These commands act as powerful, parameterizable snippets.

Locations:

1. Global: ~/.pi/agent/commands/
2. Project: ./.pi/commands/

A command file is a Markdown file where the filename (without .md) becomes the command name. It can include YAML frontmatter for a description and supports argument substitution.

Example (/docs.md):

---
description: Reads a documentation file and asks a question about it.
---
Read the file packages/$1/README.md and answer the following question: $2

Usage: /docs mom "What does it do?"
Expansion: Read the file packages/mom/README.md and answer the following question: What does it do?

Sources: packages/coding-agent/src/slash-commands.ts:1-143

The expansion process is handled by expandSlashCommand, which parses arguments and substitutes them into the command's content.

Sources: packages/coding-agent/src/slash-commands.ts:145-159