Configuration¶

Global configuration¶

Global defaults are shared across workspaces in ~/.config/pcode/preferences.json (or $XDG_CONFIG_HOME/pcode/preferences.json). Inspect and edit them without opening a terminal UI or connecting a model:

pcode config                     # List effective startup defaults as JSON
pcode config diff                # List only settings that differ from defaults
pcode config path                # Print the resolved config path
pcode config get theme
pcode config set theme light
pcode config set autocompact on
pcode config set effort high
pcode config set model openai-codex:gpt-5.6-luna
pcode config unset model          # Remove saved model; return to offline preview
pcode config unset theme          # Restore automatic theme detection
pcode config reset                # Remove every saved default at once

Inside pcode, /config opens a full-screen, searchable settings editor. Its layout stays fixed as you browse, filter, and edit; only resizing the terminal changes the pane sizes. Type to search setting names and descriptions, use ↑/↓ to select a setting, and press Enter to edit it. Choose from the available options or enter a value; Enter saves and keeps the browser open. Escape cancels the current edit, or closes the browser when you are not editing. Invalid values stay in the editor with an explanation. Tab switches focus to the details so you can scroll long descriptions and values; Shift+Tab returns to the search or value editor.

Each setting shows its built-in default, saved effective value, and whether that value comes from the user or project configuration. These are saved defaults, not a snapshot of the running conversation. The detail area identifies layout settings that apply immediately and warns when a project override takes precedence over a user edit.

The scope control shows the shortcut for switching between user and project settings. Project scope is available when a workspace is selected and omits user-only settings. Toggle Overrides only to see just the values saved in the selected scope, including explicit overrides equal to the built-in default. Removing an override clears that scope's saved value, letting the underlying user value or built-in default take over. The scope, filter, and reset shortcuts are shown in the browser and follow your configured key prefix; Keys opens the complete keyboard help.

Explicit commands remain available with tab completion: /config list prints JSON, and /config set theme light, /config get autocompact, /config unset effort, and /config diff work without opening the browser. Most config edits affect the next launch, not the running conversation. To change an active setting and save its default immediately, use /theme, /effort, /model, or /autocompact instead. The layout settings attach_tasks, tasks_max_height, tasks_min_rows, tasks_min_columns, task_style, tool_glyphs, tool_max_lines and tool_linger_seconds apply immediately through /config. CLI overrides such as --theme and --model do not rewrite global defaults, and resumed sessions retain their own model.

Model provider filter¶

Limit the /model selector to specific providers:

pcode config set model_providers openai-codex,anthropic
pcode config unset model_providers # Restore automatic detection of all active providers

Or run /config set model_providers openai-codex,anthropic inside pcode. This setting is read each time the selector opens, without a restart. In preferences.json it is a string: "model_providers": "openai-codex,anthropic". Names match exactly: openai-codex does not include openai, openai-chat, or openai-responses. Unknown provider names are rejected.

An unset or empty value shows all automatically detected active providers. A nonempty list filters those providers; it does not configure credentials or force inactive providers to appear. The current provider is also hidden if it is excluded. This only filters the selector, not explicit /model PROVIDER:MODEL commands, CLI model overrides, or resumed sessions.

Keybindings¶

Use /bind and /unbind to customize main-prompt action keys. Mappings are user-only and stored in bindings.json, separate from preferences.json: $PCODE_CONFIG_DIR/bindings.json when set, otherwise $XDG_CONFIG_HOME/pcode/bindings.json, defaulting to ~/.config/pcode/bindings.json. There is no project binding file or project configuration override. Writes are locked and atomic.

Binding edits apply immediately in the current terminal. Other running terminals pick them up on their next start or a binding management edit, not automatically. The editor and prefix preferences (editing_mode, vi_escape_sequence, vi_key_prefix, and key_prefix) still require restarting the prompt; see Keybindings for their setup and how global shortcuts and the optional vi leader share mappings.

Independent instances¶

PCODE_CONFIG_DIR points pcode at a different config directory without moving the rest of your XDG_CONFIG_HOME. Everything pcode keeps there follows it: preferences.json, codex-credentials.json and mcp-credentials.json (so each instance has its own /login openai-codex and MCP sign-ins), mcp.json, bindings.json, extensions/, and worktree-setup. Sessions and other state still live under XDG_STATE_HOME; set PCODE_SESSION_DIR too if those should be separate.

PCODE_CONFIG_DIR=~/.config/pcode-work pcode      # separate login and settings

PCODE_CODEX_CREDENTIALS_FILE and PCODE_MCP_CONFIG still win over the directory for their single file.

Per-repository overrides¶

A workspace's .pcode/preferences.json is layered over the user file at launch, so a setting can hold for one repository and be committed for everyone who clones it. config list and config get show the merged result; config project edits the repository file (from -C DIR or the current directory):

pcode config project set worktree on    # this repo only; writes .pcode/preferences.json
pcode config project list               # the raw overlay
pcode config project unset worktree
pcode config project reset              # Drop the whole overlay

A cloned repository must not be able to run code or pick credentials on your behalf, so project_extensions, trusted_projects, extension_dirs, extensions_off, and extensions_on are user-only: the project file cannot set them, and pcode says so at launch if it tries. model and subagent_models can be set, but only choose among the providers you are signed in to. When the repository sets subagent_models, /subagents shows that list, says it comes from the repository, and refuses to change it; edit it with pcode config project set or unset instead. The overlay is read from the launch workspace before any worktree is created, so worktree on in a repository's file is what starts each of its sessions in a worktree.

Trusting a repository's own code¶

A repository can ship code that runs at launch with your permissions: .pcode/extensions/*.py (see /extensions, which lists every extension and its state, and turns one on or off) and .pcode/worktree-setup. Neither runs until you trust that repository. The first interactive launch inside one that ships either asks:

pcode: /path/to/repo ships code that runs at launch with your permissions: .pcode/worktree-setup
Trust this repository? [y/N]

y records the repository's primary checkout in trusted_projects (so all of its worktrees are covered) and never asks again; n skips the code for this launch and asks next time. --print has nobody to ask, so it skips and says so. Revoke with pcode config unset trusted_projects (or edit the :-separated list). pcode config set project_extensions on trusts every repository, which is only sensible on a machine where you wrote all of them.

Settings reference¶

Every key works with pcode config set KEY VALUE and /config set KEY VALUE.

Models and providers¶

Editor and keys¶

Scrollback and display¶

Tools and sub-agents¶

Context¶

Sessions and worktrees¶

Email remote control¶

Settings for pcode --email-listen. All of them are user-only: a repository's .pcode/preferences.json cannot set them.

Repository instructions, skills and extensions¶

Diagnostics¶

Code highlighting styles¶

Each palette gets its own setting: syntax_dark applies whenever the resolved theme is dark, syntax_light whenever it is light. /syntax NAME changes the setting for the palette in use and saves it as that palette's default; /syntax alone reports the current one. Tab completion lists the choices, and an unknown name is rejected with the full list.

Both default to terminal, which is not a Pygments style: it hands every color to the terminal's own ANSI palette. Scrollback uses named colors, fenced code uses ansi_dark / ansi_light with no painted background, and the prompt, task rows and completion popup use ANSI names too (the selected popup row is reversed). pcode then looks right in whatever scheme the terminal runs.

/theme-preview draws a sample of every style on one line, marks the one in use, and repeats the commands below, so a style can be chosen by eye rather than by name. The terminal row is drawn with the palette's ANSI style.

Any other value is a Pygments style. The completion menu and the prompt chrome (the chevron, plan rows, the frame, @file references) are painted from it, so the screen matches the code on it. A Pygments style only colors code, though, so any color it leaves out or that would be unreadable falls back to the palette's own. The two are judged against different backgrounds: the menu brings the style's own surface with it, while chrome lands on the terminal's background, so a light style chosen while the dark palette is active keeps its popup but leaves the chrome on the palette. Picking any Pygments style also switches scrollback headings, links, quotes and tables from ANSI names to the palette's own colors.

These are the styles that come with Pygments; installing a Pygments style plugin package adds to the list automatically.

Darker backgrounds: coffee, dracula, fruity, github-dark, gruvbox-dark, inkpot, lightbulb, material, monokai, native, night-owl, nord, nord-darker, one-dark, paraiso-dark, rrt, solarized-dark, stata-dark, vim, zenburn.

Lighter backgrounds: abap, algol, algol_nu, arduino, autumn, borland, bw, colorful, default, emacs, friendly, friendly_grayscale, gruvbox-light, igor, lilypond, lovelace, manni, murphy, paraiso-light, pastie, perldoc, rainbow_dash, sas, solarized-light, staroffice, stata-light, tango, trac, vs, xcode.

Styles differ in how much they color: some leave plain identifiers and punctuation at the default foreground, so a snippet that is mostly names can look unhighlighted even though the lexer ran. Compare a few against your own terminal background before settling on one.

Outside the editor, pcode config set syntax_dark NAME and pcode config set syntax_light NAME save the same two settings.

Notes¶

Automatic compaction still requires a known context window; setting its global preference does not validate a particular model or trigger a compaction. For custom deployments, use PCODE_CONTEXT_WINDOW as described in context compaction. MCP configuration and credentials are separate from these non-secret defaults.

Writes are atomic and serialized across terminals. Unknown JSON keys are preserved; invalid setting values fall back to built-in defaults. Normal startup tolerates a malformed file, but config commands report it and refuse to overwrite it: use pcode config path to find and repair it first. Invalid commands exit nonzero.

At startup pcode looks up the latest release on PyPI, at most once a day and without delaying the session, and shows a warning with the upgrade command for your install (Homebrew, uv, pipx or pip) when a newer version is out. Development and editable installs skip it; set PCODE_NO_UPDATE_CHECK=1 to turn it off.

PCODE_CONFIG_DIR overrides the user config directory for preferences, extensions, MCP configuration, keybindings, worktree setup, and stored logins. Otherwise pcode uses $XDG_CONFIG_HOME/pcode, defaulting to ~/.config/pcode. Per-file overrides (PCODE_CODEX_CREDENTIALS_FILE, PCODE_MCP_CONFIG) take precedence.