Coding Agent Configuration
Relevant source files
The following files were used as context for generating this wiki page:The Coding Agent's behavior is determined by a multi-layered configuration system that sources settings from command-line arguments, environment variables, session files, and dedicated configuration files. This system allows for both temporary, on-the-fly adjustments and persistent, project-wide settings. Key aspects of configuration include model selection, system prompt construction, tool availability, and session management.
The core of the configuration logic resides in main.ts, which parses arguments, resolves settings, and initializes the agent. User-specific preferences like themes and default models are managed by the SettingsManager, while conversation state is handled by the SessionManager.
Configuration Loading Hierarchy
The agent resolves its configuration by applying settings from multiple sources in a specific order of precedence. Settings from a higher-priority source override those from a lower-priority one.
This diagram illustrates the configuration loading and override hierarchy.
Command-Line Arguments
CLI arguments provide the highest-priority configuration, allowing for immediate overrides for a single session. They are parsed by the parseArgs function in main.ts.
| Argument | Alias | Description |
|---|---|---|
--provider <name> | Specifies the model provider (e.g., openai, anthropic). | |
--model <id> | Specifies the model ID (e.g., gpt-4o-mini). | |
--api-key <key> | Provides the API key directly, overriding environment variables. | |
--system-prompt <text> | Replaces the default system prompt with the provided text or file content. | |
--append-system-prompt <text> | Appends text or file content to the system prompt. | |
--mode <mode> | Sets the output mode: text, json, or rpc. Default is interactive TUI. | |
--print | -p | Enables non-interactive "single-shot" mode. |
--continue | -c | Continues the last session. |
--resume | -r | Opens a UI to select a previous session to resume. |
--session <path> | Specifies a path to a session file to use. | |
--no-session | Disables session saving for an ephemeral session. | |
--models <patterns> | A comma-separated list of model patterns for quick cycling with Ctrl+P. | |
--tools <tools> | A comma-separated list of tools to enable (e.g., read,bash,edit). | |
--thinking <level> | Sets the reasoning level: off, minimal, low, medium, high, xhigh. | |
--export <file> | Exports a session file to HTML and exits. | |
--help | -h | Displays the help message. |
Sources: packages/coding-agent/src/main.ts:77-172, packages/coding-agent/src/main.ts:286-345
System Prompt Construction
The system prompt is dynamically assembled by the buildSystemPrompt function. It combines a default prompt, tool definitions, user-provided context files, and runtime information.
This flowchart shows the process of building the final system prompt.
Project Context Files
The agent automatically loads context from AGENTS.md or CLAUDE.md files to provide project-specific instructions. This allows teams to define development rules, available tools, and other guidelines that the agent will follow.
The loading mechanism, loadProjectContextFiles, searches for these files in a specific order:
- Global Context:
~/.pi/agent/AGENTS.md(orCLAUDE.md) - Ancestor Directories: Searches from the root directory down to the parent of the current working directory.
- Current Directory:
AGENTS.mdin the current working directory.
This hierarchical loading allows for global, user-level, and project-level configurations to be layered.
Sources: packages/coding-agent/src/main.ts:590-652, AGENTS.md
Model and Provider Configuration
Model selection is a critical part of the agent's configuration, determining its capabilities and cost.
Model Selection Priority
The agent determines which model to use based on the following priority:
- CLI Arguments:
--providerand--modelflags. - Model Scope: The first model specified via the
--modelsargument. - Session Restore: The model saved in the session file when using
--continueor--resume. - User Settings: The default model saved in
~/.pi/agent/settings.json. - Default Model: A hardcoded default model for a known provider with a valid API key.
- First Available Model: The first model found with a valid API key.
Sources: packages/coding-agent/src/main.ts:1359-1498
Model Scope (--models)
The --models argument allows users to define a specific list of models to cycle through using Ctrl+P in the TUI. It also supports setting a default thinking level for each model in the scope.
The format is a comma-separated list, where each entry can be model-pattern or model-pattern:thinking-level.
# Cycle between Sonnet and Haiku, with high thinking for Sonnet
pi --models claude-sonnet:high,claude-haiku:low
The resolveModelScope function parses these patterns and finds the best-matching available models. It prefers aliased model IDs (e.g., claude-sonnet-4-5) over dated versions.
Sources: packages/coding-agent/src/main.ts:800-921
Tool Configuration
The agent's capabilities are extended through a set of tools. By default, the read, bash, edit, and write tools are enabled.
Available Tools
| Tool | Description | Default |
|---|---|---|
read | Read file contents. | Enabled |
bash | Execute bash commands (ls, grep, find, etc.). | Enabled |
edit | Make surgical edits to files (find exact text and replace). | Enabled |
write | Create or overwrite files. | Enabled |
grep | Search file contents for patterns (respects .gitignore). | Disabled |
find | Find files by glob pattern (respects .gitignore). | Disabled |
ls | List directory contents. | Disabled |
Sources: packages/coding-agent/src/main.ts:347-363, packages/coding-agent/test/tools.test.ts
Enabling Tools
Tools can be configured using the --tools CLI argument. For example, to run the agent in a read-only mode:
pi --tools read,grep,find,ls "Review the code in src/"
The system prompt is adjusted based on the enabled tools, providing the agent with appropriate guidelines (e.g., "You are in READ-ONLY mode").
Sources: packages/coding-agent/src/main.ts:131-145, packages/coding-agent/src/main.ts:487-543
Tool Management
The ToolsManager ensures that external binary dependencies for certain tools, like fd (for file autocomplete) and ripgrep (for grep), are available. If a tool is not found in the system PATH, the manager will attempt to download it from its GitHub releases to a local directory (~/.pi/tools).
Sources: packages/coding-agent/src/tools-manager.ts:1-185
Persistent Settings (SettingsManager)
The SettingsManager class handles persistent user preferences stored in ~/.pi/agent/settings.json. This allows users to set defaults that apply across all sessions.
Key settings managed include:
- Default provider and model
- Default thinking level
- TUI theme
- Message queue mode
- Compaction settings (enabled, thresholds)
- Visibility of thinking blocks
The TuiRenderer interacts with this manager to load and save these preferences, for example, when a user changes the theme via the /theme command or toggles auto-compaction.
Sources: packages/coding-agent/src/settings-manager.ts, packages/coding-agent/src/tui/tui-renderer.ts:100-102, packages/coding-agent/src/tui/tui-renderer.ts:1738-1745