# Settings

> Source: https://parallelworks.com/docs/ai/code/settings

# 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](/docs/ai/code/mcp).

## 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](/docs/ai/code/mcp), and the `.agents` [agent definitions](/docs/ai/code/custom-agents) and [custom commands](/docs/ai/code/slash-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](/docs/ai/code/non-interactive) 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.

| Key | Type | Default | Description |
| --- | --- | --- | --- |
| `model` | string | none | Model ID to start with (e.g. `Jake.Thayne:openai/gpt-5.2`). Updated automatically to the model you last used. |
| `allocation` | string | none | Budget allocation for `org:` provider models. Updated to the one you last used. |
| `permissionMode` | string | `accept-edits` | Startup [permission mode](/docs/ai/code/permissions): `read-only`, `accept-edits`, `bypass-permissions`, or `plan`. |
| `allowedTools` | string[] | `[]` | [Allow rules](/docs/ai/code/permissions) that pre-approve tool calls, e.g. `"Bash(git status:*)"`. |
| `maxTurnTokens` | number | `0` | Per-turn token budget; the turn stops when it is exceeded. `0` = unlimited. See [Usage & Costs](/docs/ai/code/usage-and-costs). |
| `compactAt` | number | `0` | Live context size, in tokens, at which the conversation is automatically compacted. `0` = default (100,000). See [Usage & Costs](/docs/ai/code/usage-and-costs). |
| `includeCoAuthoredBy` | boolean | `true` | Attribution on commits and pull requests the agent creates. See [below](#commit-and-pr-attribution). |
| `mcpServers` | object | `{}` | [MCP server](/docs/ai/code/mcp) definitions. |
| `autoScroll` | boolean | `true` | Keep the transcript pinned to the bottom as output streams. |
| `reduceMotion` | boolean | `false` | Disable the working-spinner animation. |
| `mouseClicks` | boolean | `false` | Let mouse clicks act on the interface (select picker rows, toggle blocks, drag-select). Wheel scrolling always works. |
| `sessionRetentionDays` | number | `0` | A 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](/docs/ai/code/sessions). |
| `disableSubagents` | boolean | `false` | Withhold the delegation tool entirely, so the agent cannot spawn [subagents](/docs/ai/code/subagents). |
| `subagentConcurrency` | number | `0` | How many subagent tasks may run at once. `0` = default (10). |
| `subagentDepth` | number | `0` | How deep subagents may nest. `0` or `1` = subagents cannot spawn their own subagents. |
| `subagentModel` | string | none | Default model for delegated tasks. Empty = inherit the session's model. |

For what the subagent keys control in practice, see [Subagents](/docs/ai/code/subagents).

## Example

```json
{
  "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 <kbd>Enter</kbd> to change the highlighted row; <kbd>Esc</kbd> closes the menu. Changes are saved to your global settings immediately.

| Row | What it does |
| --- | --- |
| **Permission mode** | Cycles `read-only` → `accept-edits` → `bypass-permissions` → `plan`. See [Permissions](/docs/ai/code/permissions). |
| **Co-authored-by trailer** | Toggles commit and pull request attribution on or off. |
| **Auto-scroll** | Toggles following the transcript as output streams. |
| **Reduce motion** | Toggles the working-spinner animation. |
| **Mouse clicks** | Toggles click interaction with the interface; scrolling and text selection always work. |
| **Subagents** | Enables or disables delegating tasks to subagents. |
| **Subagent concurrency** | Opens a number box for the parallel-task limit. <kbd>Enter</kbd> applies, <kbd>Esc</kbd> cancels; leaving it empty keeps the current value. |
| **Subagent nesting depth** | Opens a number box; `1` means subagents cannot spawn their own subagents. |
| **Subagent model** | Opens a model picker for the default delegated-task model. Shows `(inherit session)` when unset. |
| **Session retention** | Opens a number box for the sweep window in days; `0` keeps sessions forever. See [Sessions & Resume](/docs/ai/code/sessions). |
| **Model** | Opens the model picker to change the session's model. |
| **Allocation** | Opens the allocation picker (org providers). See [Models & Allocations](/docs/ai/code/models). |

## 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

- [pw code Overview](/docs/ai/code): Feature overview and quick start
- [Permissions](/docs/ai/code/permissions): Permission modes and allow rules
- [MCP Servers](/docs/ai/code/mcp): The `mcpServers` key and `.mcp.json`
- [Subagents](/docs/ai/code/subagents): Behavior behind the subagent keys
- [Models & Allocations](/docs/ai/code/models): Model IDs and budget allocations
- [Sessions & Resume](/docs/ai/code/sessions): Session storage and retention
- [Slash Commands](/docs/ai/code/slash-commands): `/settings` and other in-session commands