# Configuration

> Last updated: 2026-03-06

Pilot has no `.env` files. All configuration is stored in JSON files on disk. There are three layers: **app-level** (user preferences, `<PILOT_DIR>/app-settings.json`), **SDK-level** (Pi agent config, `<PILOT_DIR>/config.json`), and **project-level** (per-project settings, `<project>/.pilot/settings.json`).

## Config Directory

| Platform | Path |
|----------|------|
| macOS | `~/.config/pilot/` |
| Windows | `%APPDATA%\pilot\` |
| Linux | `$XDG_CONFIG_HOME/pilot/` (default: `~/.config/pilot/`) |

Resolved at runtime by `electron/services/pilot-paths.ts`.

## Configuration Files and Directories

The following files and directories live inside `<PILOT_DIR>`:

| Path | Contents |
|---|---|
| `<PILOT_DIR>/auth.json` | API keys and OAuth tokens |
| `<PILOT_DIR>/models.json` | Model registry cache |
| `<PILOT_DIR>/app-settings.json` | Terminal, editor, developer mode, keybind overrides |
| `<PILOT_DIR>/workspace.json` | Saved tab layout and UI state |
| `<PILOT_DIR>/config.json` | Pi SDK configuration |
| `<PILOT_DIR>/mcp-servers.json` | Global MCP server configurations |
| `<PILOT_DIR>/sessions/` | Session `.jsonl` files (managed by Pi SDK) |
| `<PILOT_DIR>/extensions/` | Global extensions |
| `<PILOT_DIR>/skills/` | Global skills |
| `<PILOT_DIR>/themes/` | Custom theme JSON files. Each file defines a complete color palette. See [user/themes.md](user/themes.md). |
| `<PILOT_DIR>/extension-registry.json` | Extension enabled/disabled state |
| `<PILOT_DIR>/MEMORY.md` | Global memory |
| `<PILOT_DIR>/logs/` | Rotating log files (if file logging is enabled) |

Project-specific paths (inside each project):

| Path | Contents |
|---|---|
| `<project>/.pilot/settings.json` | Jail, yolo mode, allowed paths |
| `<project>/.pilot/commands.json` | Dev command buttons |
| `<project>/.pilot/mcp-servers.json` | Project-specific MCP server configurations |
| `<project>/.pilot/desktop/` | Docker customization for desktop service |
| `<project>/.pilot/MEMORY.md` | Project memory (can be git-tracked) |

## App Settings (`app-settings.json`)

Managed by `electron/services/app-settings.ts`. Read/written via `APP_SETTINGS_GET` / `APP_SETTINGS_UPDATE` IPC channels.

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `piAgentDir` | `string` | `<PILOT_DIR>` | Base directory for SDK data (sessions, models, auth) |
| `theme` | `ThemeMode` | `'dark'` | App colour theme: `'dark'`, `'light'`, or `'system'` |
| `terminalApp` | `string \| null` | `null` | External terminal app CLI. `null` = system default |
| `editorCli` | `string \| null` | `null` | External editor CLI (`code`, `cursor`, `vim`, etc.). `null` = auto-detect |
| `onboardingComplete` | `boolean` | `false` | Set to `true` after first-launch wizard |
| `developerMode` | `boolean` | `false` | Unlocks terminal panel and dev command buttons |
| `keybindOverrides` | `Record<string, string \| null>` | `{}` | Overrides default keybindings. Map shortcut ID → combo string (e.g. `"meta+shift+t"`) or `null` to disable |
| `companionPort` | `number` | `18088` | TCP port for the companion HTTPS server |
| `companionProtocol` | `'http' \| 'https'` | `'https'` | Companion server protocol (`https` strongly recommended) |
| `companionAutoStart` | `boolean` | `false` | Automatically start companion server on app launch |
| `autoStartDevServer` | `boolean` | `false` | Automatically start dev commands marked as `autoStart: true` when opening a project |
| `hiddenPaths` | `string[]` | Standard ignores | Gitignore-syntax glob patterns to hide from the file tree |
| `commitMsgMaxTokens` | `number` | `4096` | Max tokens for AI-generated commit message summaries |
| `commitMsgModel` | `string` | auto-select cheapest | Model ID for AI commit messages. Format: `"provider/model-id"` |
| `logging.level` | `'debug' \| 'info' \| 'warn' \| 'error'` | `'warn'` | Minimum log level |
| `logging.file.enabled` | `boolean` | `false` | Write rotating log files to `<PILOT_DIR>/logs/` |
| `logging.file.maxSizeMB` | `number` | `10` | Max log file size before rotation |
| `logging.file.retainDays` | `number` | `14` | Days to keep log files |
| `logging.syslog.enabled` | `boolean` | `false` | Forward logs via UDP syslog (RFC 5424) |
| `logging.syslog.host` | `string` | `'localhost'` | Syslog server hostname |
| `logging.syslog.port` | `number` | `514` | Syslog UDP port |
| `logging.syslog.facility` | `number` | `16` | Syslog facility code (16 = local0) |
| `logging.syslog.appName` | `string` | `'pilot'` | App name in syslog messages |

## Pi Agent Settings (`config.json`)

Managed by the Pi SDK. Read/written via `PI_SETTINGS_GET` / `PI_SETTINGS_UPDATE` IPC channels. Schema is defined by `@mariozechner/pi-coding-agent`.

## Project Settings (`<project>/.pilot/settings.json`)

Managed by `electron/services/project-settings.ts`. Read/written via `SETTINGS_GET` / `SETTINGS_UPDATE` IPC channels.

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `jail.enabled` | `boolean` | `true` | Enforce project file jail (block writes outside project root) |
| `jail.allowedPaths` | `string[]` | `[]` | Absolute paths outside project root the agent is allowed to write |
| `yoloMode` | `boolean` | `false` | Skip diff review; agent writes go directly to disk |

## MCP Server Config (`mcp-servers.json`)

Managed by `electron/services/mcp-config.ts`. Exists at two levels:

- **Global**: `<PILOT_DIR>/mcp-servers.json` — servers available to all projects
- **Project**: `<project>/.pilot/mcp-servers.json` — servers specific to one project

Merged at runtime with project config taking precedence. Read/written via `MCP_LIST_SERVERS` / `MCP_ADD_SERVER` / `MCP_UPDATE_SERVER` / `MCP_REMOVE_SERVER` IPC channels.

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique server ID |
| `name` | `string` | Human-readable name |
| `transport` | `'stdio' \| 'sse' \| 'streamable-http'` | Connection transport |
| `command` | `string \| undefined` | Shell command (stdio only) |
| `args` | `string[] \| undefined` | Command arguments (stdio only) |
| `url` | `string \| undefined` | Server URL (SSE/HTTP only) |
| `env` | `Record<string, string> \| undefined` | Environment variables |
| `enabled` | `boolean` | Whether the server is active |
| `autoStart` | `boolean \| undefined` | Start when project opens |
| `scope` | `'global' \| 'project'` | Config scope |

## Desktop Config (`<project>/.pilot/desktop/`)

Optional project-specific Docker customisation. If a `Dockerfile` exists in this directory, the desktop service builds a project-specific image with those customisations layered on top of the base `pilot-desktop:latest` image.

## Dev Commands (`<project>/.pilot/commands.json`)

Array of `DevCommand` objects. Managed via the dev commands settings UI and `DEV_LOAD_CONFIG` / `DEV_SAVE_CONFIG` IPC channels.

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique ID |
| `label` | `string` | Button label in Pilot UI |
| `command` | `string` | Shell command to run |
| `cwd` | `string \| undefined` | Working directory (default: project root) |
| `env` | `Record<string, string> \| undefined` | Additional environment variables |
| `autoStart` | `boolean \| undefined` | Auto-start when project opens (requires `developerMode` + `autoStartDevServer`) |
| `detectUrl` | `boolean \| undefined` | Watch stdout for a URL and display it |

## Keybinding System

Default keybindings are defined in `src/lib/keybindings.ts`. Each shortcut has an ID, default combo, and optional platform-specific variant.

- On **macOS**, `Meta` = `⌘ Command`
- On **Windows/Linux**, `Ctrl` is used in place of `Meta`

Overrides are stored in `app-settings.json` under `keybindOverrides`. A `null` value disables the shortcut entirely.

## File Tree Filtering

Controlled by `hiddenPaths` in `app-settings.json`. Uses gitignore syntax via the `ignore` npm package:

- `node_modules/` — ignore a directory
- `*.log` — ignore by extension
- `dist/` — ignore a build output directory
- `!important.log` — negation: un-hide a specific file

Default hidden patterns include `node_modules/`, `.git/`, `dist/`, `build/`, `out/`, `*.log`, `.DS_Store`, and similar common noise.

## Auth / API Keys (`auth.json`)

Stored in `<PILOT_DIR>/auth.json` with file permissions `0600`. Managed entirely by the Pi SDK. API keys can be set via the Settings → Auth UI (`AUTH_SET_API_KEY` IPC) or via OAuth (`AUTH_LOGIN_OAUTH` IPC).

## Workspace State (`workspace.json`)

Auto-saved (debounced 500ms) by `useWorkspacePersistence` hook. Contains the full tab layout and UI panel visibility state. Restored automatically on app launch.

## Changes Log

- 2026-03-06: Added MCP server config, Desktop config, theme setting, ThemeMode type
- 2026-02-24: Initial documentation generated