mirror of
https://github.com/badlogic/pi-mono.git
synced 2026-10-19 15:34:05 +00:00
8562bcf66a
Some checks are pending
CI / build-check-test (push) Waiting to run
This adds codemode and MCP support to pi. Codemode (packages/codemode) runs model-written JavaScript in a QuickJS wasm VM inside a worker. From there the script calls pi's tools as async functions, uses a per-session store, and can read the model catalog and run classifiers. The codemode tool in coding-agent is compatible with Codex's exec tool, and codemode.mode works like Codex's tool modes (on or only). Large results are written to a JSON temp file. MCP (packages/mcp) is a standalone client for stdio and streamable HTTP servers, with OAuth. The core only gets general mechanisms; codemode, tool_search and MCP are built-in extensions that use them. Other extensions can replace these built-ins. Tools declare an exposure: direct, model-only, codemode, deferred or hidden. prepareLoadout() lets an orchestrating tool change which tool declarations the model sees. ctx.executeTool() runs nested calls through validation and the tool_call/tool_result hooks. Those calls emit events with parentToolCallId and are recorded as bounded nestedCalls on the parent result, which compaction and HTML export use. Tools can also return structuredContent with an outputSchema, and can report errors with isError instead of throwing. MCP servers come from mcp.json (global, or per project after the project is trusted) or from pi.registerMcpServer(). They are managed with /mcp and pi mcp list|login|logout, and their runtimes load on first use. Closes #10040
11 KiB
11 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. |
codemode.mode |
"on" | "only" |
"on" |
How the codemode tool presents tools while it is active. on: declared tools get their codemode declaration appended to their description, and codemode lists only tools that are not declared (MCP codemode exposure). only: codemode lists every tool scripts can call, and active built-in and extension tools are hidden from the model, so it reaches them through codemode. |
codemode.inlineBudget |
number | 3000 |
Estimated tokens (characters / 4) the codemode tool's description may spend on tool declarations. Tools that do not fit are left out and found with searchTools(). 0 lists only namespaces. |
Available built-in tools are read, bash, powershell, edit, write, grep, find, and ls. defaultTools can also name codemode and tool_search, which built-in extensions register inactive. 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. |