polygraph config

polygraph config

polygraph config opens an interactive two-pane editor for ~/.polygraph/config.json. The editor covers the most commonly configured settings: general settings, per-agent options, and per-repo options. The config file itself supports more than the editor exposes; see the config file reference below.

polygraph config is interactive and does not support --json.

Left pane — the editable tree, organized into three groups:

• General — session-wide settings: default agent, multiplexer, git protocol, and theme.
• Agents — one row per agent (Claude, Codex, OpenCode). The first item under each agent is the plugin item, which shows a status chip (plugin installed, plugin outdated, plugin not found, checking plugin..., installing plugin..., or plugin install failed). Press Enter (or i) on the plugin item to install or update the agent's plugin. Below it are the agent's trust, sandbox, and auto mode fields.
• Repositories — one row per configured repository, rendered as flat aligned rows: Create using, Trust, and Sandbox. Unset Trust and Sandbox values show (inherit); a worktree strategy shows its base inline (worktree · base: /path/to/clone). Press a to add a repo from your account and d to remove one. Before any repo is configured, the section is a single hint line: Press a to configure a repo.

Right pane — contextual help for the focused property. As you move the selection, the right pane updates to explain the focused field or plugin item, including its install location.

Keys

Key	Action
↑/k, ↓/j	Move the selection
Enter	The focused row's primary action: install or update the plugin on a plugin item, cycle the value everywhere else
Space	Cycle the value
←/h, →/l	Cycle the value backward / forward
c	Clear the field back to its default (unset)
i	Install or update the plugin (plugin items)
a	Add a repo from your account
d, Backspace	Remove the focused repo
s	Save and exit
q, Esc, Ctrl+C	Exit

Edits are staged until you save

Every change you make in the editor is staged in memory. Nothing is written to ~/.polygraph/config.json until you save. Saving only touches the keys you edited: clearing a value (c) deletes that key from the file, and keys you didn't touch in the editor are never modified by a save.

s saves and exits. q, Esc, and Ctrl+C exit, and when you have staged changes they first ask what to do with them: Save and exit (selected by default), Continue editing, or Exit without saving. With nothing staged, they exit right away.

General settings

Setting	Config key	Values	Unset behavior
Default agent	agentType	claude, codex, opencode	Each session prompts for an agent
Multiplexer	multiplexer	auto, none, tmux, iterm2, kitty, ghostty, cmux, zellij, herdr, windows-terminal	Session start asks before opening panes
Git protocol	gitProtocol	ssh, https	Auto-detected from your git and gh setup
Theme	theme	auto, light, dark	— (auto is the default)

• Default agent — the agent launched for new sessions. When set, commands that would prompt for an agent (polygraph session start, session reconstruction on resume) use it without asking; explicit agent flags still override it. When unset, each session prompts for an agent.
• Multiplexer — how Polygraph opens child agent panes. auto picks the first available multiplexer; none keeps everything in one terminal. When unset, session start asks before opening panes. The editor probes your terminal and notes which multiplexers it detects; if you stage one that isn't detected, session start will unset it and ask again.
• Git protocol — the protocol used to clone session repositories. When unset, Polygraph auto-detects it from your git and gh setup. The POLYGRAPH_GIT_PROTOCOL environment variable overrides this for a single run.
• Theme — the color theme for the Polygraph terminal UI. auto detects the terminal background; light or dark force it.

polygraph config validate

Validate the local Polygraph config file.

polygraph config validate

Schema violations are reported as warnings and don't fail the command. Invalid JSON is fatal: if the file can't be parsed, the command errors out.

Options

Flag	Type	Description
--help, -h	boolean	Show help for the current command
--version	boolean	Show the version number for the CLI

---

Config file reference

All Polygraph settings live in ~/.polygraph/config.json. The interactive editor manages the most commonly configured keys: the General settings (agentType, multiplexer, gitProtocol, theme), agentOptions, and repoOptions. Everything else is edited directly in the file. The complete schema is written to ~/.polygraph/schema.json and referenced from the file's $schema key, so editors with JSON-schema support can provide completion and validation for every setting.

Key	Managed by	Description
agentType	polygraph config	Default agent for new sessions.
multiplexer	polygraph config	Terminal multiplexer used for session panes.
gitProtocol	polygraph config	Preferred clone protocol (ssh or https).
theme	polygraph config	Color theme for the Polygraph terminal UI.
agentOptions	polygraph config	Per-agent settings: trust, sandbox, autoMode, extraArgs, env.
repoOptions	polygraph config	Per-repo settings: createUsing, trust, sandbox.
repoStrategy	hand-edited	Default creation strategy and per-repo overrides.
setupScripts	hand-edited	Local overrides for repo setup scripts.
globalRoot	hand-edited	Where session folders are created.
selectedUrl	Polygraph CLI	Selected Polygraph environment URL.
$schema	Polygraph CLI	Points at the generated schema.json.

Annotated sample

{
  "agentType": "claude",   // Default agent for new sessions. Unset: prompt each session.
  "multiplexer": "tmux",   // Multiplexer for session panes. Unset: ask at session start.
  "gitProtocol": "ssh",    // Clone protocol. Unset: auto-detect from git/gh.
  "theme": "auto",         // TUI color theme: auto, light, or dark.
  "agentOptions": {
    // Per-agent settings. Valid keys: "claude", "codex", "opencode".
    "claude": {
      "trust": true,      // Skips per-action permission gating for this agent.
      "sandbox": true,    // Runs the agent inside a sandbox.
      "extraArgs": ["--verbose"],  // Extra CLI args for the agent process.
      "env": {
        "HTTP_PROXY": "http://localhost:8080"  // Extra env vars injected into the agent process.
      }
    },
    "codex": {
      "trust": true,
      "sandbox": true
    },
    "opencode": {
      "trust": false,
      "autoMode": true    // Uses the agent's own approval automation instead of trust.
    }
  },
  "repoOptions": {
    // Per-repo settings. Keyed by full repo name (org/repo).
    "acme/api": {
      "createUsing": "worktree",  // How Polygraph creates the working copy.
      "trust": false,             // Per-repo trust override (overrides agentOptions value).
      "sandbox": true             // Per-repo sandbox override.
    },
    "acme/frontend": {
      "createUsing": "clone"
    }
  }
}

agentOptions

Keyed by agent name. Valid keys are claude, codex, and opencode.

Field	Type	Description
trust	boolean	Whether the agent runs trusted (skips per-action permission gating) by default.
sandbox	boolean	Whether the agent runs inside a sandbox by default.
autoMode	boolean	Whether the agent uses its own approval automation. See auto mode.
extraArgs	string[]	Extra command-line arguments passed to the agent process.
env	object (string → string)	Extra environment variables injected into the agent process.

extraArgs and env are not exposed in the interactive editor and have to be edited directly in the file.

Per-agent defaults

When an agent has no entry in agentOptions (or omits a field), its effective trust, sandbox, and autoMode fall back to these built-in defaults:

Agent	Default trust	Default sandbox	Default autoMode
Claude	✓ on	✓ on	✗ off
Codex	✓ on	✓ on	✗ off
OpenCode	✗ off	not supported	✗ off

Auto mode

autoMode hands approval decisions to the agent's own automation instead of Polygraph's trust setting. Each agent has its own name for it: Claude and OpenCode call it Auto mode, and Codex calls it Approve for me, which routes on-request approvals to automatic review. OpenCode approves any request it does not explicitly deny.

trust and autoMode are two answers to the same question, so the editor keeps them mutually exclusive: turning one on turns the other off. Auto mode is available for every agent on every platform.

The sandbox is configured separately and is unaffected by autoMode. An agent can run in auto mode inside the sandbox.

Sandbox

Claude and Codex agents run inside an OS-level filesystem sandbox by default. The sandbox belongs to the agent harness — Claude Code uses Seatbelt on macOS or bubblewrap on Linux; Codex uses its own workspace-write sandbox. Polygraph configures the sandbox through each harness's settings.

Platform support differs by harness:

• Claude Code — macOS, Linux, and WSL2. The sandbox cannot engage on native Windows, so Polygraph disables it there.
• Codex — macOS, Linux, and Windows. Codex's sandbox works on Windows using a restricted-token boundary.

The sandbox restricts where the agent can write. Only these paths are writable:

• ~/.npm
• ~/.polygraph/logs
• ~/.polygraph/bundles
• The system temp directory
• The current session root (~/.polygraph/sessions/<session-id>/)
• The repository working tree

The repository working tree is in the allowlist, so the agent can edit source files, run builds, run tests, and run git commands normally. But the sandbox keeps the agent's own configuration directory read-only — .claude/ for Claude, .codex/ for Codex.

This means a git rebase or git checkout can fail if it needs to update files under the agent's configuration directory (for example, .claude/skills/ checked into the repo). In practice this is rare — the agent can still commit, push, and create branches normally.

Note

Polygraph's own push-time git pull --rebase runs outside the agent sandbox, so pushing a branch still works. The limitation is only when the agent itself runs a rebase or checkout inside the session.

Configuration

Disable the sandbox globally for an agent type:

{
  "agentOptions": {
    "claude": {
      "sandbox": false
    }
  }
}

Disable it for a single repository:

{
  "repoOptions": {
    "nrwl/ocean": {
      "sandbox": false
    }
  }
}

With the sandbox on (the default), the agent is more constrained but you get maximum isolation. Polygraph's push command handles pre-push pull-rebase for you, so pushes still work even with the sandbox enabled.

Configuring the sandbox through the agent harness

The sandbox boolean above is a convenience on/off toggle. Because the sandbox belongs to the agent harness, you can also configure it in detail through each harness's own settings. Polygraph generates its own settings on every launch (Claude's --settings flag, or Codex's -c overrides and --sandbox/--add-dir flags) that enable the sandbox and set the writable roots.

Claude Code

Sandbox settings live in Claude Code's settings files: ~/.claude/settings.json (user), or the project's .claude/settings.json / .claude/settings.local.json. The relevant keys are under the sandbox object:

Key	Type	Description
sandbox.enabled	boolean	Whether the sandbox is enabled (macOS, Linux, WSL2)
sandbox.filesystem.allowWrite	string[]	Additional writable paths
sandbox.filesystem.denyWrite	string[]	Paths denied for writes
sandbox.filesystem.denyRead	string[]	Paths denied for reads

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.cache"],
      "denyWrite": ["./secrets"]
    }
  }
}

Array settings (allowWrite, denyWrite, denyRead) are merged across all settings scopes — paths you add are combined with Polygraph's generated list, not replaced. Scalar values like sandbox.enabled follow normal precedence, where Polygraph's --settings takes priority. See Claude Code's sandbox settings documentation for the full schema.

Codex

Codex sandbox is configured in ~/.codex/config.toml (or the project's .codex/config.toml) and via CLI flags (--sandbox, --add-dir). The sandbox mode is set with sandbox_mode; Polygraph uses workspace-write when the sandbox is on. The available modes are read-only, workspace-write, and danger-full-access. The relevant config keys are under the [sandbox_workspace_write] table:

Key	Type	Description
sandbox_mode	string	Sandbox mode: read-only, workspace-write, or danger-full-access
sandbox_workspace_write.writable_roots	string[]	Additional writable paths
sandbox_workspace_write.network_access	boolean	Whether outbound network access is allowed

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true
writable_roots = ["/Users/YOU/.cache"]

In workspace-write mode, .codex/ is kept read-only even when the rest of the workspace is writable. See Codex's advanced configuration documentation for the full schema.

Turning the sandbox off removes filesystem isolation

Without the sandbox, the agent can write anywhere its OS user can. Only disable it when you understand and accept the risk.

Environment inheritance

Child agents inherit the environment of the shell where you started the Polygraph session. Provider-routing variables like ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN reach child agents this way.

agentOptions.<agent>.env entries override inherited values with the same key. Use env to pin a value for a specific agent type regardless of what the shell provides.

extraArgs semantics

extraArgs are appended to the child agent's command line after Polygraph's own flags. Repeated flags resolve last-wins, so extraArgs can override Polygraph's defaults. For example, adding ["--model", "claude-opus-4-5"] to a Claude entry overrides the model Polygraph would otherwise use.

Model selection

Polygraph never forces a model on child agents. Each child resolves its model from that agent's own configuration, as if you launched the agent yourself.

Default resolution by agent:

• claude: its own settings, the ANTHROPIC_MODEL environment variable, or the CLI default.
• codex: the model setting in ~/.codex/config.toml.
• opencode: the model setting in opencode.json (provider/model format).

To pin a model for all children of a given agent type, add it to agentOptions:

• claude: "extraArgs": ["--model", "<model-id>"] (repeated flags resolve last-wins) or "env": {"ANTHROPIC_MODEL": "<model-id>"}.
• codex: "extraArgs": ["-c", "model=<model-id>"] (Codex accepts -c key=value config overrides on the command line).
• opencode: set the model in your OpenCode configuration file.

Proxy-backed environments

When Claude is routed through an Anthropic-compatible proxy, such as a GitHub Copilot-backed endpoint, set ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN in your shell. Child agents inherit those variables automatically. No env entry is needed for them.

If the proxy's model catalog uses different identifiers than Anthropic's, pin the model in agentOptions. A complete example combining agentOptions and repoOptions:

{
  "$schema": "~/.polygraph/schema.json",
  "agentOptions": {
    "claude": {
      "trust": true,
      "sandbox": true,
      "env": {
        "ANTHROPIC_MODEL": "<provider-model-id>"
      }
    },
    "codex": {
      "trust": true,
      "sandbox": true
    }
  },
  "repoOptions": {
    "acme/api": {
      "trust": false
    },
    "acme/frontend": {
      "createUsing": "worktree"
    }
  }
}

ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN are inherited from the shell and don't need to appear in env. You'd only add them here to override what the shell provides for a specific agent type. env and extraArgs are agent-level only. There's no per-repo override for them.

repoOptions

Keyed by repository full name (for example acme/api).

Field	Type	Description
createUsing	strategy	How Polygraph creates the repository working copy for the session.
trust	boolean	Per-repo override of the effective trust for any agent operating in this repo.
sandbox	boolean	Per-repo override of the effective sandbox for any agent operating in this repo.

createUsing strategies

createUsing accepts one of three strategies as a bare string:

Value	Description
clone	Polygraph clones the repo into the session folder.
worktree	Polygraph creates a git worktree from an existing local clone.
superset	Polygraph uses a superset working copy shared across repos.

Most repos only need the bare string form:

{ "createUsing": "worktree" }

Each strategy also accepts an object form with a type discriminator and per-strategy options:

• worktree accepts an optional base (path to the local clone).
• superset accepts an optional include (string array of repos to group) and sectionName.

{ "createUsing": { "type": "worktree", "base": "/path/to/local/clone" } }

Resolution rules

The effective trust and sandbox for an agent working in a repo is resolved along this chain, where the most specific value wins:

built-in per-agent default  →  agentOptions[<agent>]  →  repoOptions[<repo>]

A repoOptions[<repo>] value overrides the agent-level value, which overrides the built-in default. A field that isn't set inherits from the previous layer. An explicit false does not fall through: setting trust: false at the repo or agent level turns it off. extraArgs and env are agent-only and have no per-repo override.

Some examples:

• Claude's built-in trust default is true. In a repo with "trust": false under repoOptions["acme/api"], Claude runs untrusted because the per-repo value wins.
• A repo with no trust field in repoOptions inherits the agent's value: true for Claude, and OpenCode's built-in default of false for OpenCode.
• Setting agentOptions.opencode.trust = true makes OpenCode trusted in every repo that doesn't override it, since the agent layer beats the built-in default.

repoStrategy

The default creation strategy for repositories that do not set their own createUsing, plus per-repo overrides:

{
  "repoStrategy": {
    "default": "worktree",
    "overrides": {
      "acme/api": "clone"
    }
  }
}

Both default and each override accept the same values as createUsing. When a session creates a working copy for a repo, the strategy resolves in this order:

repoOptions[<repo>].createUsing  →  repoStrategy.overrides[<repo>]  →  repoStrategy.default

The built-in default is clone. The repo a session is started from is always used in place and ignores these settings.

setupScripts

Local overrides for the setup script that runs after a repo working copy is created in a session. Keyed by repo full name; * wildcards are supported:

{
  "setupScripts": {
    "acme/api": "pnpm install",
    "acme/*": { "script": "./scripts/setup.sh", "mode": "replace" }
  }
}

A bare string is shorthand for { "script": "...", "mode": "after" }.

• after runs after the repo's server-configured setup script.
• replace replaces the server-configured setup entirely. When several replace patterns match the same repo, the most specific one wins; a literal repo name beats a wildcard.

Malformed entries are skipped with a warning.

Running steps only during indexing runs

The repo's server-configured setup script also runs when Polygraph indexes the repository in an ephemeral container. During an indexing run the POLYGRAPH_REPOSITORY_ID environment variable is set. It is not set in interactive sessions, so the script can check it to run steps only while indexing, or invert the check (-z) to skip steps during indexing runs (for example, skipping dev-server startup in the container):

if [ -n "${POLYGRAPH_REPOSITORY_ID:-}" ]; then
  # Indexing run: NPM_TOKEN is provided to the container's environment.
  npm config set -L project @scope:registry=https://npm.pkg.github.com
  npm config set -L project //npm.pkg.github.com/:_authToken="${NPM_TOKEN}"
fi

Local overrides from this key apply only to interactive sessions on your machine and are never used during indexing, so indexing-only steps belong in the repo's server-configured setup script.

agentType

The default agent for new sessions: claude, codex, or opencode. When set, commands that would prompt for an agent — polygraph session start and session reconstruction on resume — use it without asking; explicit agent flags like --agent still override it. When unset, each session prompts for an agent.

Values are matched case-insensitively and surrounding whitespace is ignored, so a hand-edited "Claude " still resolves to claude.

multiplexer

Which terminal multiplexer Polygraph uses to open session panes. One of auto, none, tmux, iterm2, kitty, ghostty, cmux, zellij, herdr, or windows-terminal. auto picks the first available multiplexer; none keeps everything in one terminal. When unset, session start asks before opening panes.

gitProtocol

Preferred git clone protocol for Polygraph repositories: ssh or https. Applies everywhere Polygraph clones repos, including session reconstruction on resume. It overrides git/gh auto-detection, and is itself overridden by the POLYGRAPH_GIT_PROTOCOL environment variable. When unset, Polygraph auto-detects the protocol from your git and gh setup.

theme

The color theme for the Polygraph terminal UI: auto, light, or dark. auto detects the terminal background; light and dark force it.

globalRoot

The directory where Polygraph creates session folders. Defaults to ~/.polygraph/sessions. The POLYGRAPH_ROOT environment variable takes precedence.

CLI-managed keys

Polygraph writes these itself and they rarely need to be edited by hand:

• selectedUrl is the Polygraph environment URL the CLI is signed into.
• $schema points at the generated schema.json next to the config file.