mirror of
https://github.com/badlogic/pi-mono.git
synced 2026-11-05 23:37:25 +00:00
bf8e4b9531
* feat(coding-agent,tui): add system theme derived from terminal colors The new default system theme builds pi's colors from the terminal's reported foreground, background, and ANSI palette. Tokens take their hue and relative saturation from a palette slot; lightness is placed by OKLab lightness difference and WCAG 2 contrast minimums. Terminals that report only a background get built-in hues, and terminals that report nothing get ANSI indices with faint secondary text. The TUI queries OSC 10, 11, and 4 in one burst ended by DA1, so replies complete in one round trip, and reports replies that arrive after the timeout. Startup never waits: the system theme starts in grayscale and updates when colors arrive. Light/dark detection now uses the reported colors instead of the ?996 query; mode 2031 notifications trigger a new query. * fix(coding-agent): wait for terminal colors before building the startup header The header and startup notices bake theme colors into their text. When the color replies arrived after they were built, as in Windows Terminal, they stayed grayscale. Startup now waits for the first color query, which ends at the DA1 reply or after 100 ms. * fix(coding-agent): rebuild header and notices on theme changes The startup header, loaded resources, and chat notices baked theme colors into their text, so they kept the old colors after a theme switch or when the system theme received the terminal's colors. They now use ThemedText, which rebuilds its text from a function whenever the UI is invalidated. * fix(tui): keep focus on components that forward mouse events to children A component that forwards a mouse event to a child it hosts, such as SettingsList with an open submenu, left keyboard focus on the child. When the host removed the child, focus stayed on a detached component and all keys were lost. The forwarding component now keeps focus, like delegating containers do. * feat(coding-agent): describe the system theme in the theme selector * feat(coding-agent): list the system theme above automatic in the theme selector * refactor(coding-agent,tui): remove leftovers of the light/dark startup detection Theme detection only reports dark or light now; the source and confidence fields only served saving the detected theme. The first-time setup no longer shows the detected appearance. Removes the TUI's unused queryTerminalColorScheme(), queryTerminalBackgroundColor(), queryTerminalForegroundColor(), and parseOsc11BackgroundColor(); queryTerminalColors() covers them. * feat(coding-agent): match the reviewed system and light/dark theme design The system theme now follows the reviewed design: color families with OKHSL saturation curves, palette slots per family, contrast rules per token and panel, relaxation for mid-gray backgrounds, and the terminal foreground for body text. Each contrast level is a target-lightness curve fitted to the reviewed output. The built-in dark and light themes use the reviewed Pi dark and light colors. * feat(coding-agent): show the pi logo in the startup header A two-line pixel logo replaces the app name. Its first line carries the version, its second line the first line of key hints. * feat(tui,coding-agent): support OKHSL colors in themes parseColor() accepts okhsl(H S L), and okhslColor() and colorToOkhsl() construct and read OKHSL colors. OKHSL saturation is relative to the sRGB gamut, so every value is in gamut. Theme files accept okhsl() values; HTML exports convert them to hex. The OKHSL code moves from coding-agent into pi-tui, where colors.ts now shares its Oklab conversion instead of keeping a second copy. * refactor(coding-agent): write the built-in themes in OKHSL The built-in dark and light themes use okhsl() values, with variables for colors that several roles share, so they read as color families and serve as editable templates. Near-identical values collapsed into one; no color changes visibly. * refactor(coding-agent,tui): simplify terminal color and theme code Share the terminal color query between startup and the theme controller, merge the query's resolve/late-reply state into one callback, keep a single global for terminal colors, use oklab.ts arrays directly in colors.ts, and drop leftover helpers and exports. * fix(coding-agent): use one terminal light/dark decision everywhere Theme pairs, the system theme, and Theme.appearance now share getTerminalTheme(): the reported background decides, then the terminal's light/dark report, then COLORFGBG, then dark. COLORFGBG is classified by palette index like Vim (0-6 and 8 dark) and only reads the last field, so rxvt's "default" no longer picks up the foreground index. Simplify the tests added on this branch. * fix(ai): use an OpenRouter model that still exists in beta test OpenRouter removed anthropic/claude-3-haiku, which broke type checking in CI after model regeneration.
10 KiB
10 KiB
Settings Reference
This reference lists user-configurable settings, their types, defaults, and purposes. Project settings override agent-directory settings. Resource lists are combined. See Configuration for file locations and trust behavior.
Model and thinking
| Setting | Type | Default | Description |
|---|---|---|---|
defaultProvider |
string | Automatic | Startup AI provider. |
defaultModel |
string | Automatic | Startup model ID. |
defaultThinkingLevel |
"off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" |
"medium" |
Startup thinking level. |
modelThinkingLevels |
object | None | Per-model startup thinking levels keyed by exact provider/modelId. |
thinkingBudgets |
object | Built-in budgets | Token budgets for minimal, low, medium, and high thinking levels. |
enabledModels |
string[] |
All available models | Model patterns used for startup selection and model cycling. Uses the same format as --models. |
hideThinkingBlock |
boolean | false |
Hide thinking blocks in the transcript. |
showCacheMissNotices |
boolean | false |
Show notices for significant cache misses, successful cache warming, compaction usage, and provider recovery. |
cacheWarming |
"off" | "streaming" | "idle" |
"streaming" |
Keep eligible provider prompt caches warm during active runs or, with "idle", between runs. Global setting only. |
Cache warming runs only when the model declares a cache lifetime and Pi estimates at least $0.05 in avoided cache-miss cost. Refresh usage counts toward session totals but does not enter model context. /session shows the next decision; extensions can override it with cache_warming_decision. See Prompt Cache Lifetimes.
See Choose a Model for model selection and thinking controls.
Interaction
| Setting | Type | Default | Description |
|---|---|---|---|
steeringMode |
"all" | "one-at-a-time" |
"one-at-a-time" |
How queued steering messages are delivered. |
followUpMode |
"all" | "one-at-a-time" |
"one-at-a-time" |
How queued follow-up messages are delivered. |
externalEditor |
string | $VISUAL, $EDITOR, then platform default |
Command opened by the external-editor keybinding. |
doubleEscapeAction |
"tree" | "fork" | "none" |
"tree" |
Action for double Escape with an empty editor. |
treeFilterMode |
"default" | "no-tools" | "user-only" | "labeled-only" | "all" |
"default" |
Initial filter used by /tree. |
defaultProjectTrust |
"ask" | "always" | "never" |
"ask" |
Fallback project-trust behavior. Can only be set in agent-directory settings. |
Tools
| Setting | Type | Default | Description |
|---|---|---|---|
defaultTools |
string[] |
read, bash, edit, write |
Built-in tools enabled at startup. An empty array disables all built-in tools but not extension or SDK tools. |
Available built-in tools are read, bash, powershell, edit, write, grep, find, and ls. CLI tool options override this setting for one invocation. See Command Line.
Sessions and context
| Setting | Type | Default | Description |
|---|---|---|---|
sessionDir |
string | Agent session directory | Session storage directory. Relative paths resolve from the working directory. PI_CODING_AGENT_SESSION_DIR and --session-dir override this setting. |
Compaction
| Setting | Type | Default | Description |
|---|---|---|---|
compaction.enabled |
boolean | true |
Enable automatic compaction. |
compaction.reserveTokens |
number | 16384 |
Tokens reserved for the model response. |
compaction.keepRecentTokens |
number | 20000 |
Recent tokens retained without summarization. |
compaction.modelOverrides |
object | None | Per-model token settings keyed by exact provider/modelId. |
Compaction token values must be non-negative safe integers. Each value resolves independently from the matching model override, then the ordinary compaction setting, then the built-in default. Project and user objects merge before model lookup.
See Compaction Reference for trigger, summarization, and validation behavior.
Branch summaries
| Setting | Type | Default | Description |
|---|---|---|---|
branchSummary.reserveTokens |
number | 16384 |
Tokens reserved when summarizing branch history. |
branchSummary.skipPrompt |
boolean | false |
Skip the branch-summary prompt and default to no summary. |
Terminal and display
| Setting | Type | Default | Description |
|---|---|---|---|
theme |
string | "system" |
Built-in or custom theme name. system derives colors from the terminal theme. |
quietStartup |
boolean | false |
Hide the startup header. |
tuiMode |
"regular" | "fullscreen" |
"regular" |
Interactive terminal UI mode. |
fullscreenExitOutput |
"transcript" | "resume-hint" |
"transcript" |
Output printed when fullscreen mode exits. |
fullscreenScrollbar |
"auto" | "always" | "hidden" |
"auto" |
Fullscreen transcript scrollbar behavior. |
fullscreenCopyOnSelect |
boolean | true |
Copy selected text automatically in fullscreen mode. |
editorPaddingX |
number | 0 |
Horizontal editor padding from 0 to 3 cells. |
outputPad |
0 | 1 |
1 |
Horizontal transcript padding. |
autocompleteMaxVisible |
number | 5 |
Visible autocomplete entries, from 3 to 20. |
showHardwareCursor |
boolean | false |
Show the terminal cursor while Pi positions it for input methods. |
terminal.showImages |
boolean | true |
Display inline images when supported. |
terminal.imageWidthCells |
number | 60 |
Preferred inline image width in terminal cells. |
terminal.clearOnShrink |
boolean | false |
Clear empty rows when rendered content shrinks. |
terminal.showTerminalProgress |
boolean | false |
Show OSC 9;4 progress in the terminal tab. |
terminal.hyperlinks |
boolean | "auto" |
"auto" |
Override OSC 8 hyperlink detection. |
terminal.images |
"kitty" | "iterm2" | "auto" | false |
"auto" |
Override inline-image protocol detection. |
terminal.trueColor |
boolean | "auto" |
"auto" |
Override true-color detection. |
images.autoResize |
boolean | true |
Resize images to at most 2000 by 2000 pixels before sending them to a model. |
images.blockImages |
boolean | false |
Prevent images from being sent to models. |
markdown.codeBlockIndent |
string | " " |
Prefix used to indent rendered code blocks. |
markdown.mermaid |
"off" | "final" | "streaming" |
"streaming" |
Mermaid rendering mode. |
See Themes and Terminal Setup for format and platform details.
Network and retries
| Setting | Type | Default | Description |
|---|---|---|---|
transport |
"auto" | "sse" | "websocket" | "websocket-cached" |
"auto" |
Preferred transport for AI providers that support multiple transports. |
httpProxy |
string | None | Proxy URL applied as HTTP_PROXY and HTTPS_PROXY for Pi-managed HTTP clients. Can only be set in agent-directory settings. |
httpIdleTimeoutMs |
number | 300000 |
HTTP header and body idle timeout in milliseconds. Set to 0 to disable. |
websocketConnectTimeoutMs |
number | 15000 |
WebSocket connection timeout in milliseconds. Set to 0 to disable. |
retry.enabled |
boolean | true |
Enable automatic agent-level retry for transient failures. |
retry.maxRetries |
number | 3 |
Maximum agent-level retry attempts. |
retry.baseDelayMs |
number | 2000 |
Initial exponential-backoff delay in milliseconds. |
retry.maxAgentDelayMs |
number | 60000 |
Maximum agent-level retry delay in milliseconds. |
retry.provider.timeoutMs |
number | httpIdleTimeoutMs |
Provider request timeout in milliseconds. |
retry.provider.maxRetries |
number | 0 |
Provider-level retry attempts. |
retry.provider.maxRetryDelayMs |
number | 60000 |
Maximum server-requested delay in milliseconds. Set to 0 to disable the limit. |
Keep retry.provider.maxRetries at 0 unless provider-level retries are required. Provider retries can delay Pi from handling quota and usage-limit errors itself.
Shell
| Setting | Type | Default | Description |
|---|---|---|---|
shellPath |
string | Platform default | Custom shell executable path. Supports a leading ~. |
shellCommandPrefix |
string | None | Prefix prepended to every shell command. |
npmCommand |
string[] |
npm |
Command and arguments used for npm package lookup and installation. |
See Shell aliases for shell setup and Pi Packages for package-manager behavior.
Resources
Resource paths in user settings resolve from the agent directory. Paths in project settings resolve from the project .pi directory. Absolute paths and ~ are supported.
| Setting | Type | Default | Description |
|---|---|---|---|
packages |
array | [] |
npm, git, or local Pi package sources. See Pi Packages. |
extensions |
string[] |
[] |
Extension files or directories. |
skills |
string[] |
[] |
Skill files or directories. |
prompts |
string[] |
[] |
Prompt-template files or directories. |
themes |
string[] |
[] |
Theme files or directories. |
enableSkillCommands |
boolean | true |
Register skills as /skill:name commands. |
Resource arrays support glob exclusions with !pattern, exact inclusion with +path, and exact exclusion with -path. Pi loads resources listed in both user-level and project settings.
Updates, telemetry, and warnings
| Setting | Type | Default | Description |
|---|---|---|---|
collapseChangelog |
boolean | false |
Show a condensed changelog after an update. |
enableInstallTelemetry |
boolean | true |
Enable anonymous install/update reporting and selected provider attribution headers. Does not control update checks. |
enableAnalytics |
boolean | false |
Opt in to analytics data sharing. Currently used only by the experimental first-run setup. |
warnings.anthropicExtraUsage |
boolean | true |
Warn when Anthropic subscription authentication may use paid extra usage. |