Parallel Works
View as Markdown
Share:

Settings

pw code reads its configuration from a global settings file in your home directory, with optional per-workspace files you can check into a project. Common settings can also be changed from inside a session with the interactive /settings menu.

Settings Files

Settings are merged from four places, in order, with later files overriding earlier ones key by key:

  1. ~/.config/pw/code.json: your global settings.
  2. <workspace>/.mcp.json: MCP servers in the cross-tool standard format.
  3. <workspace>/.agents/settings.json: project settings, typically checked in.
  4. <workspace>/.agents/settings.local.json: personal overrides for one workspace, not meant to be checked in.

All four files accept the same JSON keys. The global path honors XDG_CONFIG_HOME and is the same on macOS and Linux. A mcpServers map is replaced wholesale, not merged: the highest-precedence file that defines it supplies the entire server set. See MCP Servers.

Workspace Trust

Workspace configuration only applies after you approve it. The first time pw code starts in a workspace whose configuration files it has not seen before, it lists them and asks whether to apply them. The gate covers everything a workspace can contribute: settings files, .mcp.json MCP servers, and the .agents agent definitions and custom commands.

Your answer is remembered for that exact content: if any of the files change, you are asked again at the next launch. Until you approve, none of the workspace files apply and the session runs on your global settings alone.

Non-interactive runs never prompt. Unapproved workspace configuration is ignored with a notice on stderr, so launch pw code interactively once in a workspace you want scripts to use. Approvals are stored in your global settings file under the workspaceSettingsTrust key, which is managed automatically.

Key Reference

All keys are optional.

KeyTypeDefaultDescription
modelstringnoneModel ID to start with (e.g. Jake.Thayne:openai/gpt-5.2). Updated automatically to the model you last used.
allocationstringnoneBudget allocation for org: provider models. Updated to the one you last used.
permissionModestringaccept-editsStartup permission mode: read-only, accept-edits, bypass-permissions, or plan.
allowedToolsstring[][]Allow rules that pre-approve tool calls, e.g. "Bash(git status:*)".
maxTurnTokensnumber0Per-turn token budget; the turn stops when it is exceeded. 0 = unlimited. See Usage & Costs.
compactAtnumber0Live context size, in tokens, at which the conversation is automatically compacted. 0 = default (100,000). See Usage & Costs.
includeCoAuthoredBybooleantrueAttribution on commits and pull requests the agent creates. See below.
mcpServersobject{}MCP server definitions.
autoScrollbooleantrueKeep the transcript pinned to the bottom as output streams.
reduceMotionbooleanfalseDisable the working-spinner animation.
mouseClicksbooleanfalseLet mouse clicks act on the interface (select picker rows, toggle blocks, drag-select). Wheel scrolling always works.
sessionRetentionDaysnumber0A positive number sweeps sessions untouched for that many days at startup; resuming a session resets its clock. 0 (the default) or a negative value keeps sessions forever. See Sessions & Resume.
disableSubagentsbooleanfalseWithhold the delegation tool entirely, so the agent cannot spawn subagents.
subagentConcurrencynumber0How many subagent tasks may run at once. 0 = default (10).
subagentDepthnumber0How deep subagents may nest. 0 or 1 = subagents cannot spawn their own subagents.
subagentModelstringnoneDefault model for delegated tasks. Empty = inherit the session's model.

For what the subagent keys control in practice, see Subagents.

Example

{
  "model": "Jake.Thayne:openai/gpt-5.2",
  "permissionMode": "accept-edits",
  "allowedTools": ["Bash(git status:*)", "Bash(go test:*)"],
  "compactAt": 80000,
  "includeCoAuthoredBy": false,
  "sessionRetentionDays": 90,
  "subagentConcurrency": 4,
  "subagentModel": "Jake.Thayne:openai/gpt-5.2-mini",
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "docs-mcp-server"]
    }
  }
}

The /settings Menu

Run /settings in an interactive session to change the most common settings without editing files. Type to filter the rows, move with the arrow keys, and press Enter to change the highlighted row; Esc closes the menu. Changes are saved to your global settings immediately.

RowWhat it does
Permission modeCycles read-only → accept-edits → bypass-permissions → plan. See Permissions.
Co-authored-by trailerToggles commit and pull request attribution on or off.
Auto-scrollToggles following the transcript as output streams.
Reduce motionToggles the working-spinner animation.
Mouse clicksToggles click interaction with the interface; scrolling and text selection always work.
SubagentsEnables or disables delegating tasks to subagents.
Subagent concurrencyOpens a number box for the parallel-task limit. Enter applies, Esc cancels; leaving it empty keeps the current value.
Subagent nesting depthOpens a number box; 1 means subagents cannot spawn their own subagents.
Subagent modelOpens a model picker for the default delegated-task model. Shows (inherit session) when unset.
Session retentionOpens a number box for the sweep window in days; 0 keeps sessions forever. See Sessions & Resume.
ModelOpens the model picker to change the session's model.
AllocationOpens the allocation picker (org providers). See Models & Allocations.

Commit and PR Attribution

When includeCoAuthoredBy is enabled (the default), the agent ends every commit message it creates with an attribution line and a Co-Authored-By: pw code <noreply@parallelworks.com> trailer, and ends the pull requests it opens with the same attribution line. Turning it off with the Co-authored-by trailer row in /settings applies to the current session's future commits, not just the next launch.

Related Documentation