Christian Klotz
25cc5c7bf4
* docs(coding-agent): improve getting started documentation * docs(coding-agent): correct getting started details * docs(coding-agent): clarify SDK entry point * docs(coding-agent): restructure guides and references * docs(coding-agent): improve getting started guides * docs(coding-agent): refresh integration guides * docs(coding-agent): improve terminal and CLI guides * docs(coding-agent): refresh customisation guides * docs(coding-agent): clarify project trust terminology * docs(coding-agent): simplify customisation guidance * docs(coding-agent): improve runtime and reference guidance * Fix settings reference * feat(coding-agent): add Crowdin documentation sync * docs(coding-agent): separate CLI and slash command references * docs(coding-agent): correct compaction reference * docs(coding-agent): streamline package documentation * docs(coding-agent): split RPC reference documentation * Update configuration docs * Shorten config docs * docs(coding-agent): refine configuration references * docs(coding-agent): streamline settings reference * docs(coding-agent): clarify configuration reference * docs(coding-agent): clarify project trust exception * docs(coding-agent): simplify keybindings reference * docs(coding-agent): remove Crowdin integration * docs(coding-agent): turn themes reference into guide * docs(coding-agent): consolidate model and authentication docs * docs(tui): require Component.invalidate() (fixes #9358) * docs(coding-agent): document offline catalog behavior (fixes #8684) * docs(coding-agent): preserve established documentation routes * docs(coding-agent): reorganize documentation navigation * docs(coding-agent): correct audited behavior Clarify provider, session, local-model, Termux, TUI, SDK, debug, and extension behavior. Simplify the documentation audit to report only clear user-visible contradictions. * docs(coding-agent): fix broken documentation links
3.0 KiB
Configuration
Pi supports user-level and project configuration. User-level configuration lives in the agent directory, which defaults to ~/.pi/agent. Project configuration lives in .pi under the working directory and loads after project trust is granted. The only exception is sessionDir, which Pi reads before resolving trust so it can locate sessions.
In interactive mode, use /settings to change common preferences. For other options, ask Pi to update the configuration or edit the relevant files directly. Run /reload after manually changing settings, keybindings, instructions, or resources.
Agent directory
The agent directory is shown as <agent-dir> below. Set its location with the PI_CODING_AGENT_DIR environment variable or the SDK's agentDir option.
| Path | Responsibility |
|---|---|
<agent-dir>/settings.json |
User-level settings, including preferences, defaults, resource paths, and Pi package declarations. |
<agent-dir>/keybindings.json |
Custom terminal UI and application keybindings. |
<agent-dir>/models.json |
Compatible endpoints, models, and model overrides. |
<agent-dir>/auth.json |
Saved API keys and OAuth credentials. |
<agent-dir>/AGENTS.override.md, AGENTS.md, AGENTS.MD, CLAUDE.md, or CLAUDE.MD |
User instructions applied across working directories. |
<agent-dir>/SYSTEM.md |
Replaces Pi’s default system prompt. |
<agent-dir>/APPEND_SYSTEM.md |
Adds instructions to Pi’s system prompt. |
<agent-dir>/extensions/ |
User extensions. |
<agent-dir>/skills/ |
User skills and supporting files. |
<agent-dir>/prompts/ |
User prompt templates exposed as slash commands. |
<agent-dir>/themes/ |
User theme files. |
Project .pi directory
| Path | Responsibility |
|---|---|
.pi/settings.json |
Project-level settings, resource paths, and Pi package declarations. |
.pi/SYSTEM.md |
Replaces the system prompt for the project. |
.pi/APPEND_SYSTEM.md |
Adds project-specific instructions to the system prompt. |
.pi/extensions/ |
Project extensions. |
.pi/skills/ |
Project skills and supporting files. |
.pi/prompts/ |
Project prompt templates exposed as slash commands. |
.pi/themes/ |
Project theme files. |
For SYSTEM.md and APPEND_SYSTEM.md, the trusted project file takes precedence over the corresponding agent-directory file. Files with the same name are not combined.
Context files
Context files are separate from project .pi configuration. Pi loads them from the agent directory, the working directory, and its parent directories. A context file applies whenever Pi runs in its directory or anywhere below it.
An AGENTS.override.md replaces AGENTS.md or CLAUDE.md only in the same directory. It does not suppress context files from the agent directory or other directories.
Context-file discovery does not require project trust.