Settings

pw code reads its configuration from a user 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 read from these files, lowest to highest precedence. A higher file overrides a lower one key by key:

• ~/.config/pw/code.json holds your own settings and is written with owner-only permissions (0600). Both user paths honor XDG_CONFIG_HOME and are the same on macOS and Linux. The first time pw code runs, code.json is created from the code section of an older ~/.config/pw/settings.json if one exists.
• .agents/settings.local.json lives at the repository root, so one file covers every subdirectory you start in. In a git worktree it is read from the main checkout. Adding a rule to it with /permissions also adds it to your global git excludes, so it is not committed.
• ~/.config/agents/settings.json is read for hooks only. Allow rules placed there are ignored with a warning; keep them in code.json.

User-only keys are read from ~/.config/pw/code.json alone. A workspace file that sets them has no effect, so a cloned repository cannot change them: sessionRetentionDays, remoteControl, trustedSkills, disabledSkills, agentsGrouping, agentsKeymap, disableAllHooks, allowedEnvVars, and workspaceSettingsTrust.

A few keys combine instead of overriding:

• permissions.allow rules from code.json, .agents/settings.json, .agents/settings.local.json, and the --allowedTools flag all apply together.
• hooks from every layer run; see Hooks.
• mcpServers is replaced wholesale, not merged: the highest-precedence file that defines it supplies the entire server set. See MCP Servers.
• disableSkillShellExecution can be turned on by a workspace file, but not turned back off when your user settings turn it on.

Workspace Trust

Workspace configuration only applies after you approve it. The first time pw code starts in a workspace whose configuration it has not seen before, it lists the files and asks whether to apply them. The prompt covers:

• .mcp.json MCP servers
• .agents/settings.json and the repository's .agents/settings.local.json
• Agent definitions in .agents/agents/
• Custom commands in .agents/commands/ and .pw/code/commands/
• Skills in .agents/skills/ of the workspace and each parent directory up to the repository root

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 user settings alone.

Project hooks are not enabled by this prompt. They have their own trust step, /hooks trust.

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 code.json under the workspaceSettingsTrust key, which is managed automatically.

Key Reference

All keys are optional.

Model and Permissions

remoteControl fields, all set from /settings:

Turns and Context

Interface

agentsKeymap actions: help, open, filter_next, filter_prev, group, search, new, new_worktree, resume, fork, rename, toggle_pin, stop, archive, hide, and delete. open_agents has no default and adds keys that open the agents list from the chat.

Sessions and Subagents

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

Integrations and Skills

Example

{
  "model": "Jake.Thayne:openai/gpt-5.2",
  "permissionMode": "accept-edits",
  "permissions": {
    "allow": ["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"]
    }
  }
}

Mode Precedence

A session starts in the mode from the first of these that is set:

1. The --permission-mode flag.
2. When resuming, the mode the session last ran in.
3. The permissionMode setting.
4. accept-edits.

When you start with --agent and that custom agent sets permissionMode, it can lower the mode but never raise it.

The /settings Menu

Run /settings in an interactive session to change 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 ~/.config/pw/code.json immediately.

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.

Environment Variables

Related Documentation

• pw code Overview: Feature overview and quick start
• Permissions: Permission modes and allow rules
• Hooks: The hooks key and hook trust
• MCP Servers: The mcpServers key and .mcp.json
• Remote Control: The remoteControl keys
• Subagents: Behavior behind the subagent keys
• Models & Allocations: Model IDs and budget allocations
• Sessions & Resume: Session storage and retention
• Slash Commands: /settings and other in-session commands