# Claude Code Settings Reference

Complete reference for all Claude Code settings options. Updated for Claude Code 2.1.x (April 2026).

## Table of Contents

1. [Available Settings](#available-settings)
2. [Permission Settings](#permission-settings)
3. [Sandbox Settings](#sandbox-settings)
4. [Attribution Settings](#attribution-settings)
5. [Plugin Settings](#plugin-settings)
6. [Worktree Settings](#worktree-settings)
7. [Environment Variables](#environment-variables)

---

## Available Settings

| Key | Description | Example |
|-----|-------------|---------|
| `apiKeyHelper` | Script to generate auth value (executed in /bin/sh) | `/bin/generate_temp_api_key.sh` |
| `cleanupPeriodDays` | Days before inactive sessions/tasks/shell-snapshots/backups deleted (default: 30, 0 = immediate). 2026: now also covers `~/.claude/tasks/`, `~/.claude/shell-snapshots/`, `~/.claude/backups/`. | `20` |
| `companyAnnouncements` | Announcements displayed at startup (cycled randomly) | `["Welcome to Acme Corp!"]` |
| `env` | Environment variables for every session | `{"FOO": "bar"}` |
| `attribution` | Customize git commit/PR attribution | `{"commit": "...", "pr": ""}` |
| `permissions` | Permission rules (see Permission Settings) | |
| `hooks` | Custom commands before/after tool executions | `{"PreToolUse": {...}}` |
| `disableAllHooks` | Disable all hooks | `true` |
| `model` | Override default model | `"claude-opus-4-7"` |
| `effort` | Default effort level (low/medium/high/xhigh/max). API/Bedrock/Vertex/Foundry/Team/Enterprise default to `high` since 2026. | `"high"` |
| `statusLine` | Custom status line configuration | `{"type": "command", "command": "..."}` |
| `fileSuggestion` | Custom @ file autocomplete script | `{"type": "command", "command": "..."}` |
| `respectGitignore` | Whether @ picker respects .gitignore (default: true) | `false` |
| `outputStyle` | Adjust system prompt style | `"Explanatory"` |
| `forceLoginMethod` | Restrict login to `claudeai` or `console` | `"claudeai"` |
| `forceLoginOrgUUID` | Auto-select organization UUID during login | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` |
| `enableAllProjectMcpServers` | Auto-approve all project MCP servers | `true` |
| `enabledMcpjsonServers` | Specific MCP servers to approve | `["memory", "github"]` |
| `disabledMcpjsonServers` | Specific MCP servers to reject | `["filesystem"]` |
| `alwaysThinkingEnabled` | Enable extended thinking by default | `true` |
| `plansDirectory` | Where plan files are stored (default: `~/.claude/plans`) | `"./plans"` |
| `showTurnDuration` | Show turn duration messages | `true` |
| `language` | Claude's preferred response language | `"japanese"` |
| `autoUpdatesChannel` | Update channel: `"stable"` or `"latest"` (default) | `"stable"` |
| `disableSkillShellExecution` | **(2026)** Disable inline `` !`shell` `` execution in skills, custom slash commands, and plugin commands. Useful in managed settings. | `true` |
| `prUrlTemplate` | **(2026)** Custom code-review URL template for footer PR badge instead of github.com | `"https://gitlab.example.com/{repo}/-/merge_requests/{number}"` |
| `disableDeepLinkRegistration` | **(2026)** Prevent `claude-cli://` protocol handler registration | `true` |
| `autoScrollEnabled` | **(2026)** Disable conversation auto-scroll in fullscreen | `false` |
| `showClearContextOnPlanAccept` | **(2026)** Control plan-mode behavior on accept | `true` |
| `wslInheritsWindowsSettings` | **(2026)** WSL on Windows inherits Windows-side managed settings via this policy key | `true` |
| `enableAwaySummary` | **(2026)** Session recap when returning (also `CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0` env to opt out) | `true` |
| `tui` | UI rendering mode (alt-screen flicker-free vs scrollback). Run `/tui fullscreen` to switch live. | `"fullscreen"` |
| `worktree` | Worktree behavior config object (see [Worktree Settings](#worktree-settings)) | `{"sparsePaths": ["src/"]}` |
| `pluginConfigs` | Per-plugin user-config values (`pluginConfigs[<plugin-id>].options`) | |
| `enabledPlugins` | List of plugins enabled in this scope | |
| `extraKnownMarketplaces` | Marketplaces required by the project; auto-installed on trust | |
| `blockedMarketplaces` | **(2026)** Managed-only. Blocks marketplaces by `hostPattern`/`pathPattern` | |
| `strictKnownMarketplaces` | **(2026)** Managed-only. Enforce only `extraKnownMarketplaces` | `true` |
| `allowedChannelPlugins` | **(2026)** Managed-only. Channel plugin allowlist (Slack/Telegram/Discord) | |
| `forceRemoteSettingsRefresh` | **(2026)** Managed-only. Fail-closed if remote settings can't be refreshed | `true` |

---

## Permission Settings

| Key | Description | Example |
|-----|-------------|---------|
| `allow` | Rules to allow tool use (Bash uses prefix matching) | `["Bash(git diff:*)"]` |
| `ask` | Rules requiring confirmation | `["Bash(git push:*)"]` |
| `deny` | Rules to deny tool use | `["WebFetch", "Read(./.env)"]` |
| `additionalDirectories` | Extra working directories Claude can access. **(2026)** Now applies mid-session. | `["../docs/"]` |
| `defaultMode` | Default permission mode (`default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`) | `"acceptEdits"` |
| `disableBypassPermissionsMode` | Disable `--dangerously-skip-permissions` | `"disable"` |
| `autoMode.allow` | **(2026)** Custom rules added to Auto-mode classifier allowlist (use `$defaults` to extend built-ins) | |
| `autoMode.soft_deny` | **(2026)** Custom rules for Auto-mode soft-deny | |
| `autoMode.environment` | **(2026)** Environment context flags for the classifier | |

### Permission Modes (2026)

| Mode | Behavior |
|------|----------|
| `default` | Standard prompts; reads always allowed |
| `acceptEdits` | Auto-approves file edits + benign filesystem Bash (`mkdir`, `touch`, `rm`, `rmdir`, `mv`, `cp`, `sed`) |
| `plan` | Read-only exploration |
| `auto` | **NEW (March 2026)** — Sonnet/Opus classifier auto-approves safe ops, denies dangerous (mass deletion, exfiltration, malware). Triggers `PermissionDenied` hook. Requires Team/Enterprise/Max plan + Sonnet 4.6 / Opus 4.6+. |
| `dontAsk` | Auto-deny anything not explicitly allowed (CI/CD lockdown) |
| `bypassPermissions` | All checks off. **`.git/`, `.claude/`, `.claude/skills/` remain protected (since v2.1.78–v2.1.81).** |

Cycle live with **Shift+Tab** (default → acceptEdits → plan).

### Protected Paths (2026)

Even with `bypassPermissions`, writes to `.git/`, `.claude/`, `.claude/skills/`, and `.husky/` (in `acceptEdits` mode) trigger an approval prompt.

### Permission Rule Syntax

```
Tool(pattern)
```

Examples:
- `Bash(npm run:*)` - Allow any npm run command
- `Bash(git:*)` - Allow any git command
- `Read(./.env)` - Match .env file
- `Read(./.env.*)` - Match .env.local, .env.production, etc.
- `Read(./secrets/**)` - Match all files under secrets/

---

## Sandbox Settings

| Key | Description | Example |
|-----|-------------|---------|
| `enabled` | Enable bash sandboxing (macOS/Linux only) | `true` |
| `autoAllowBashIfSandboxed` | Auto-approve bash when sandboxed (default: true) | `true` |
| `excludedCommands` | Commands to run outside sandbox | `["git", "docker"]` |
| `allowUnsandboxedCommands` | Allow `dangerouslyDisableSandbox` parameter (default: true) | `false` |
| `network.allowUnixSockets` | Unix socket paths accessible in sandbox | `["~/.ssh/agent-socket"]` |
| `network.allowLocalBinding` | Allow binding to localhost (macOS only) | `true` |
| `network.httpProxyPort` | HTTP proxy port for custom proxy | `8080` |
| `network.socksProxyPort` | SOCKS5 proxy port for custom proxy | `8081` |
| `network.deniedDomains` | **(2026)** Block specific domains even when broader `allowedDomains` permits them | `["analytics.example.com"]` |
| `network.allowMachLookup` | **(2026)** macOS-specific Mach socket lookup | `true` |
| `enableWeakerNestedSandbox` | Enable weaker sandbox for Docker (Linux, reduces security) | `true` |
| `failIfUnavailable` | **(2026)** Exit with error when sandbox cannot start (CI safety) | `true` |

### Sandbox Example

```json
{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"],
    "network": {
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowLocalBinding": true
    }
  }
}
```

---

## Attribution Settings

| Key | Description |
|-----|-------------|
| `commit` | Attribution for git commits (including trailers). Empty string hides it |
| `pr` | Attribution for PR descriptions. Empty string hides it |

### Default Attribution

**Commit:**
```
🤖 Generated with [Claude Code](https://claude.com/claude-code)

   Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
```

**PR:**
```
🤖 Generated with [Claude Code](https://claude.com/claude-code)
```

---

## Plugin Settings

Plugin-related fields in `settings.json`:

| Key | Description |
|-----|-------------|
| `enabledPlugins` | Plugins enabled in this scope |
| `pluginConfigs` | Per-plugin user-config values; non-sensitive values stored here, sensitive ones in keychain |
| `extraKnownMarketplaces` | Marketplaces required by the project; auto-installed when the user trusts the repo folder |
| `blockedMarketplaces` | (managed) Block marketplaces by `hostPattern`/`pathPattern` |
| `strictKnownMarketplaces` | (managed) Restrict to declared marketplaces only |
| `allowedChannelPlugins` | (managed) Channel-plugin allowlist |

Plugins now ship `package.json` and lockfile dependencies that auto-install at enable time. `claude plugin tag` cuts release tags. `/plugin install` on an already-installed plugin resolves missing dependencies.

---

## Worktree Settings

```json
{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"],
    "sparsePaths": ["src/", "packages/my-service/"]
  }
}
```

| Field | Description |
|-------|-------------|
| `symlinkDirectories` | Dirs to symlink (not copy) into each worktree |
| `sparsePaths` | **(2026)** `git sparse-checkout` paths for `claude --worktree` in large monorepos |

Subagents declare worktree isolation via frontmatter `isolation: "worktree"`. The `WorktreeCreate`/`WorktreeRemove` hooks fire around lifecycle events and can override the path or block creation.

---

## Environment Variables

### Core Configuration

| Variable | Purpose |
|----------|---------|
| `ANTHROPIC_API_KEY` | API key for Claude SDK |
| `ANTHROPIC_AUTH_TOKEN` | Custom Authorization header value |
| `ANTHROPIC_MODEL` | Model setting to use |
| `ANTHROPIC_CUSTOM_HEADERS` | Custom headers (Name: Value format) |

### Model Overrides

| Variable | Purpose |
|----------|---------|
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Override Haiku model |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Override Opus model |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Override Sonnet model |
| `CLAUDE_CODE_SUBAGENT_MODEL` | Model for subagents |

### Behavior Settings

| Variable | Purpose |
|----------|---------|
| `BASH_DEFAULT_TIMEOUT_MS` | Default timeout for bash commands |
| `BASH_MAX_TIMEOUT_MS` | Maximum timeout for bash commands |
| `BASH_MAX_OUTPUT_LENGTH` | Max characters before truncation |
| `MAX_THINKING_TOKENS` | Extended thinking budget (0 to disable) |
| `MAX_MCP_OUTPUT_TOKENS` | Max tokens in MCP responses (default: 25000) |

### Disable Features

| Variable | Purpose |
|----------|---------|
| `DISABLE_AUTOUPDATER` | Disable automatic updates |
| `DISABLE_UPDATES` | **(2026)** Block ALL update paths including manual `claude update` (stricter than `DISABLE_AUTOUPDATER`) |
| `DISABLE_TELEMETRY` | Opt out of Statsig telemetry |
| `DISABLE_ERROR_REPORTING` | Opt out of Sentry error reporting |
| `DISABLE_COST_WARNINGS` | Disable cost warning messages |
| `DISABLE_PROMPT_CACHING` | Disable prompt caching for all models |
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Disable autoupdater, bug command, error reporting, and telemetry |
| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | Set to `0` to opt out of session-recap summaries |

### Provider-Specific

| Variable | Purpose |
|----------|---------|
| `CLAUDE_CODE_USE_BEDROCK` | Use Amazon Bedrock |
| `CLAUDE_CODE_USE_VERTEX` | Use Google Vertex AI |
| `CLAUDE_CODE_USE_FOUNDRY` | Use Microsoft Foundry |
| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Skip AWS auth (for LLM gateways) |
| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Skip Google auth (for LLM gateways) |
| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Skip Azure auth (for LLM gateways) |

### Directories and Paths

| Variable | Purpose |
|----------|---------|
| `CLAUDE_CONFIG_DIR` | Custom config/data directory |
| `CLAUDE_CODE_TMPDIR` | Override temp directory |
| `CLAUDE_CODE_SHELL` | Override shell detection |
| `CLAUDE_CODE_HIDE_CWD` | **(2026)** Hide working directory in startup logo |
| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | Load `CLAUDE.md` from `--add-dir` directories |

### New 2026 Environment Variables

| Variable | Purpose |
|----------|---------|
| `CLAUDE_CODE_FORK_SUBAGENT` | Enable forked subagents on external builds |
| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | Enable PowerShell tool (Windows opt-in; manual on macOS/Linux) |
| `CLAUDE_CODE_PERFORCE_MODE` | Hint for Perforce `p4 edit` workflow |
| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Strip credentials from subprocess environments; enables PID-namespace isolation on Linux |
| `CLAUDE_CODE_SCRIPT_CAPS` | Limit per-session script invocations |
| `CLAUDE_CODE_NO_FLICKER` | Flicker-free alt-screen rendering |
| `CLAUDE_CODE_CERT_STORE` | `bundled` (use only bundled CAs) — default uses OS store |
| `CLAUDE_CODE_OAUTH_TOKEN` | Pre-set OAuth token (cleared on `/login`) |
| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | Keep marketplace cache when `git pull` fails (offline support) |
| `CLAUDE_CODE_USE_MANTLE` | Use Amazon Bedrock powered by Mantle |
| `CLAUDE_CODE_USE_BEDROCK` / `CLAUDE_CODE_USE_VERTEX` / `CLAUDE_CODE_USE_FOUNDRY` | Provider routing |
| `ENABLE_PROMPT_CACHING_1H` | 1-hour prompt cache TTL (API/Bedrock/Vertex/Foundry) |
| `FORCE_PROMPT_CACHING_5M` | Force 5-minute TTL |
| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | Streaming idle watchdog (default 90_000) |
| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Raise the skill-listing description character budget (default ≈1% of context, fallback 8000) |
| `OTEL_LOG_RAW_API_BODIES` / `OTEL_LOG_USER_PROMPTS` / `OTEL_LOG_TOOL_DETAILS` / `OTEL_LOG_TOOL_CONTENT` | Telemetry granularity |
| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` / `_DESCRIPTION` (etc) | Customize displayed model labels |

### Proxy Settings

| Variable | Purpose |
|----------|---------|
| `HTTP_PROXY` | HTTP proxy server |
| `HTTPS_PROXY` | HTTPS proxy server |
| `NO_PROXY` | Domains/IPs to bypass proxy |

---

## Other Configuration Files

| Feature | User Location | Project Location |
|---------|---------------|------------------|
| **MCP servers** | `~/.claude.json` | `.mcp.json` |
| **Subagents** | `~/.claude/agents/` | `.claude/agents/` |
| **CLAUDE.md** | `~/.claude/CLAUDE.md` | `CLAUDE.md` or `.claude/CLAUDE.md` |
| **Local CLAUDE.md** | — | `CLAUDE.local.md` |

# Codex CLI Settings Reference

Configuration for [OpenAI Codex CLI](https://github.com/openai/codex) using TOML format. Reflects CLI v0.124.0 (April 2026) and the configuration schema published at [developers.openai.com/codex/config-reference](https://developers.openai.com/codex/config-reference).

## Contents

- [Config File Locations](#config-file-locations)
- [Core Settings](#core-settings)
- [Approval Policies](#approval-policies)
- [Sandbox Modes](#sandbox-modes)
- [Profiles](#profiles)
- [Feature Flags](#feature-flags)
- [Agents (Subagents) Block](#agents-subagents-block)
- [Skills Block](#skills-block)
- [Hooks Block](#hooks-block)
- [Rules](#rules)
- [Custom Model Providers](#custom-model-providers)
- [Admin Enforcement](#admin-enforcement)
- [CLI Override Examples](#cli-override-examples)

## Config File Locations

Precedence (highest to lowest):

| Priority | Location | Description |
|----------|----------|-------------|
| 1 | CLI flags / `-c` overrides | Per-invocation |
| 2 | Profile values (`--profile`) | Named presets |
| 3 | `.codex/config.toml` (CWD → project root) | Project config; trusted projects only; closest wins |
| 4 | `~/.codex/config.toml` | User config |
| 5 | `/etc/codex/config.toml` | System config |
| 6 | Built-in defaults | Codex defaults |

Override `CODEX_HOME` env var to change the home directory (default: `~/.codex`).

**Schema support** for editor autocompletion:
```toml
#:schema https://developers.openai.com/codex/config-schema.json
```

The generated JSON Schema lives at [`codex-rs/core/config.schema.json`](https://github.com/openai/codex/blob/main/codex-rs/core/config.schema.json).

## Core Settings

```toml
# Model — defaults to a recommended model when unset.
# As of April 2026, gpt-5.5 is recommended for complex coding/agentic work.
# gpt-5.4 remains a valid fallback during rollout. gpt-5.3-codex-spark is a
# fast text-only research preview for ChatGPT Pro users.
model = "gpt-5.5"
model_provider = "openai"
model_reasoning_effort = "medium"       # minimal | low | medium | high | xhigh
model_reasoning_summary = "auto"        # auto | concise | detailed | none
model_verbosity = "medium"              # low | medium | high
model_context_window = 128000           # Manual override
model_auto_compact_token_limit = 0      # Auto-compact trigger (0 = default)

# Approval and sandbox
approval_policy = "on-request"          # untrusted | on-request | never | { granular = { ... } }
                                         # NOTE: "on-failure" is DEPRECATED in 2026 — use
                                         # "on-request" for interactive or "never" for non-interactive.
sandbox_mode = "workspace-write"        # read-only | workspace-write | danger-full-access

# Instructions
developer_instructions = "Always use TypeScript."
model_instructions_file = "/path/to/instructions.md"
# (renamed from experimental_instructions_file; old key is deprecated)

# Project docs
project_doc_max_bytes = 32768
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_root_markers = [".git"]         # Set [] to skip parent search

# Credentials
cli_auth_credentials_store = "auto"     # file | keyring | auto

# Notification
notify = ["notify-send", "Codex"]

# Default profile
profile = "default"
```

## Approval Policies

```toml
approval_policy = "on-request"
```

| Policy | Behavior |
|--------|----------|
| `untrusted` | Only known-safe read-only commands auto-run; all others prompt |
| `on-request` | Model decides when to ask (default; recommended for interactive use) |
| `never` | Never prompt (recommended for non-interactive runs and CI) |
| `on-failure` | **DEPRECATED.** Auto-run in sandbox; prompt on failure. Migrate to `on-request` or `never`. |

### Granular approval (advanced)

```toml
[approval_policy.granular]
mcp_elicitations   = true
request_permissions = false
rules               = true
sandbox_approval    = true
skill_approval      = false
```

Each flag toggles whether Codex prompts for that class of action independently. CLI flag: `codex --ask-for-approval on-request` (or `-a on-request`).

## Sandbox Modes

```toml
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
writable_roots = ["~/.pyenv/shims"]
network_access = false                 # On macOS this is silently ignored (Seatbelt limitation)
exclude_tmpdir_env_var = false
exclude_slash_tmp = false
```

| Mode | Read | Write | Network | Use Case |
|------|------|-------|---------|----------|
| `read-only` | All files | None | Controlled | Safe exploration |
| `workspace-write` | All files | CWD + writable_roots + `/tmp` | Controlled | Normal development (default) |
| `danger-full-access` | All | All | All | No sandbox (risky; use only inside an externally hardened VM/container) |

**Platform implementations:**
- macOS: Seatbelt (`sandbox-exec`)
- Linux: Landlock + seccomp (default), or **bwrap** (vendored and compiled in since v0.100.0; `use_linux_sandbox_bwrap = true` to force it)
- WSL: Linux sandbox via WSL2 only. **WSL1 is unsupported since v0.115** (sandbox moved to bwrap).
- Windows native: Windows-specific sandbox implementation (gated by `enable_experimental_windows_sandbox` / `experimental_windows_sandbox`)

> **macOS gotcha:** `network_access = true` in `[sandbox_workspace_write]` is silently ignored by Seatbelt ([openai/codex#10390](https://github.com/openai/codex/issues/10390)). Linux respects it.

> **v0.116.0 regression:** Some container environments hit repeated approval prompts under workspace-write. Workaround: `codex --enable use_legacy_landlock --sandbox workspace-write`.

Helper commands: `codex sandbox seatbelt`, `codex sandbox landlock`, `codex debug ...`.

## Profiles

Define named presets for different workflows:

```toml
profile = "default"

[profiles.deep-review]
model = "gpt-5.5"
model_reasoning_effort = "high"
approval_policy = "never"

[profiles.lightweight]
model = "gpt-5.4"
approval_policy = "untrusted"

[profiles.offline]
model = "qwen2.5-coder"
model_provider = "ollama"
```

Usage: `codex --profile deep-review`. When `--profile X` is set, `codex features enable/disable` writes to that profile rather than the root.

## Feature Flags

```toml
[features]
# Stable, on by default in 2026
codex_hooks = true                # Lifecycle hooks (PreToolUse/PostToolUse/...). STABLE in v0.124
shell_tool = true                 # Shell command execution
multi_agent = true                # Subagent spawning
collaboration_modes = true        # Plan mode etc.
request_rule = true               # Smart approvals — Codex suggests rules from approvals
search_tool = true                # Web search tool
image_generation = true           # On by default since v0.122
tool_search = true                # Tool discovery (on by default since v0.122)

# Experimental / opt-in
shell_snapshot = false            # Speed up repeated commands (Beta)
unified_exec = false              # PTY-backed exec tool (Beta)
apply_patch_freeform = false      # Freeform patch tool
js_repl = false                   # JavaScript REPL (added v0.121)
in_app_browser = false            # Computer-use browser (Beta on macOS)
memories = false                  # Persistent memory tool
remote_models = false             # Remote model support
runtime_metrics = false           # Runtime summaries
skill_mcp_dependency_install = false   # Auto-install MCP deps declared by skills
fast_mode = false                 # Fast service tier (default for eligible plans)
plugins = false                   # Plugin system
remote_plugin = false             # Remote plugin marketplaces

# Sandbox-related
use_legacy_landlock = false       # Force pre-bwrap Landlock path
use_linux_sandbox_bwrap = false   # Force bwrap on Linux
enable_experimental_windows_sandbox = false
elevated_windows_sandbox = false

# Deprecated — do NOT set
# web_search          (use `search_tool` instead)
# web_search_cached
# web_search_request
# child_agents_md     (folded into multi_agent)
```

CLI management:
```bash
codex features list
codex features enable <feature>
codex features disable <feature>
codex --enable <feature>          # Per-invocation
codex --disable <feature>
```

When `--profile X` is active, `enable`/`disable` write to that profile.

For the canonical, exhaustive list of feature keys see the JSON schema linked above — the `[features]` table grows quickly.

## Agents (Subagents) Block

Codex went generally available with subagents in **March 2026**. Configure orchestration in `[agents]`:

```toml
[agents]
max_threads = 6                   # Concurrently open agent threads (default 6)
max_depth = 1                     # Maximum nesting depth; root = 0 (default 1)
job_max_runtime_seconds = 1800    # Per-worker timeout for spawn_agents_on_csv (default 1800)
interrupt_message = true          # Allow interrupting child agents (default true)

# Define / override custom agents
[agents.frontend]
config_file = "~/.codex/agents/frontend.toml"
description = "Frontend specialist for React/Next.js work."
nickname_candidates = ["fe", "ui"]
```

Custom agent files in `~/.codex/agents/*.toml` may include any standard config keys: `model`, `model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, `skills.config`, etc. If the name matches a built-in agent (`explorer`, `worker`, `default`), the custom file overrides the built-in.

Subagents inherit the parent's interactive runtime overrides (e.g., `/approvals` changes, `--yolo`).

## Skills Block

Skills are stable in 2026. Codex auto-discovers skills from these locations (highest priority first):

| Scope | Path |
|-------|------|
| Project (CWD) | `$CWD/.agents/skills/` |
| Project (intermediate dirs) | `$CWD/../.agents/skills/` |
| Project (repo root) | `$REPO_ROOT/.agents/skills/` |
| User | `$HOME/.codex/skills/` (alias: `$HOME/.agents/skills/`) |
| Admin | `/etc/codex/skills/` |
| System | Bundled with Codex (e.g., `~/.codex/skills/.system/`) |

Per-skill overrides:

```toml
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false
```

Skills are always-on as of CLI v0.124. (Earlier versions required `codex --enable skills`; the flag is still accepted for back-compat.)

## Hooks Block

Inline lifecycle hooks. Fully documented in the hooks-management skill — see `references/codex-hooks.md`.

```toml
[features]
codex_hooks = true

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 ~/.codex/hooks/policy.py'
timeout = 30
statusMessage = "Checking Bash command"
```

Events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PostToolUse`, `Stop`. Block via exit code `2` or `permissionDecision: "deny"` JSON.

## Rules

Starlark-based command execution policies in `.codex/rules/` or `~/.codex/rules/`:

```starlark
# Allow viewing PRs
prefix_rule(
    pattern = ["gh", "pr", "view"],
    decision = "allow",
    justification = "Viewing PRs is safe",
)

# Block destructive rm
prefix_rule(
    pattern = ["rm", ["-rf", "-r"]],
    decision = "forbidden",
    justification = "Use git clean -fd instead.",
)

# Prompt before docker operations
prefix_rule(
    pattern = ["docker"],
    decision = "prompt",
    justification = "Docker commands need review.",
)
```

Decisions: `allow`, `prompt`, `forbidden`. Most restrictive wins when multiple match. Compound commands (`a && b`) are split and evaluated per-segment.

Test rules:
```bash
codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- gh pr view 7888
```

## Custom Model Providers

Built-in providers in 2026: `openai`, `ollama`, `lmstudio`, plus `amazon-bedrock` (added v0.123).

```toml
[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
wire_api = "responses"                  # responses | chat
query_params = { api-version = "2025-04-01-preview" }
http_headers = { X-Org = "MyOrg" }
request_max_retries = 3
stream_max_retries = 3
stream_idle_timeout_ms = 30000

[model_providers.ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

# Bedrock (built-in v0.123+, configurable)
[model_providers.amazon-bedrock]
aws_profile = "my-profile"
# uses AWS SigV4 signing automatically
```

Usage: `codex --model-provider ollama --model qwen2.5-coder`
Or: `codex --oss` (uses `oss_provider` from config).

## Admin Enforcement

Non-overridable constraints in `requirements.toml`:

```toml
allowed_approval_policies = ["untrusted", "on-request"]
allowed_sandbox_modes = ["read-only", "workspace-write"]
allowed_web_search_modes = ["cached"]

[features]
codex_hooks = true                       # Pin feature flags

[rules]
prefix_rules = [
  { pattern = [{ token = "rm" }], decision = "forbidden", justification = "Use git clean." },
]

# Inline managed hooks
[[hooks.PreToolUse]]
matcher = "^Bash$"
[[hooks.PreToolUse.hooks]]
type = "command"
command = "/enterprise/hooks/policy.py"

[hooks]
managed_dir = "/enterprise/hooks"
windows_managed_dir = 'C:\enterprise\hooks'

# Filesystem deny-read globs (added v0.122)
deny_read_globs = ["**/.env", "**/secrets/**"]

[mcp_servers.docs]
identity = { command = "codex-mcp" }
```

Precedence: macOS MDM > Cloud (Enterprise) > `/etc/codex/requirements.toml` > `managed_config.toml` > user `config.toml`.

## CLI Override Examples

```bash
codex --model gpt-5.5
codex -m gpt-5.4                         # short form for --model
codex --config model='"gpt-5.5"'
codex --config sandbox_workspace_write.network_access=true
codex -c mcp_servers.context7.enabled=false
codex -c approval_policy='"never"'
codex --profile deep-review
codex --enable codex_hooks --enable multi_agent
codex --add-dir /extra/path             # extend writable roots without leaving sandbox
codex exec --isolated ...               # ignore user config & rules (added v0.122)
```

## Sources

- [Codex configuration reference](https://developers.openai.com/codex/config-reference)
- [Codex config sample](https://developers.openai.com/codex/config-sample)
- [Advanced configuration](https://developers.openai.com/codex/config-advanced)
- [Codex changelog](https://developers.openai.com/codex/changelog)
- [GPT-5.5 announcement](https://openai.com/index/introducing-gpt-5-5/)
- [JSON schema source](https://github.com/openai/codex/blob/main/codex-rs/core/config.schema.json)

# Devin CLI / Desktop settings

Devin CLI (and Devin Desktop, which embeds it) uses JSON config. The same
`config.json` schema applies on every surface.

## File locations

| Scope | Path | Shared? |
|-------|------|---------|
| User | `~/.config/devin/config.json` (`%APPDATA%\devin\config.json` on Windows) | No |
| Project | `.devin/config.json` | Yes (committed) |
| Project local | `.devin/config.local.json` | No (gitignored) |
| MCP (user) | `~/.config/devin/mcp_config.json` (`%APPDATA%\devin\mcp_config.json`) | No |
| MCP (project) | `.devin/mcp_config.json`, `.devin/mcp_config.local.json` | mixed |

**Precedence** (lowest → highest): user → project → project-local → env/CLI
flags. `permissions`, `read_config_from`, and `hooks` are the only keys allowed
in project configs; everything else is user-only.

## Key options (user config)

| Key | Type | Notes |
|-----|------|-------|
| `agent.model` | string | Default model (e.g. `"swe-2-high"`) |
| `agent.show_history_on_continue` | bool | Replay transcript on resume |
| `theme_mode` | string | `null`/`light`/`dark`/`terminal-dark`/`terminal-light`/`nocolor` |
| `permissions` | object | `allow`/`deny`/`ask` lists, e.g. `"Exec(git)"`, `"Write(**/.env*)"` |
| `hooks` | object | Lifecycle hooks (prefer `.devin/hooks.v1.json` for projects) |
| `read_config_from` | object | Import rules/hooks/subagents from `cursor`, `windsurf`, `claude` (all default `true`) |
| `notify` | object | Desktop/terminal notifications |
| `proxy` | object | Outbound HTTP/HTTPS proxy for CLI traffic |
| `sandbox` | object | `allowed_domains`, `denied_domains`, `network_mode` (`full`/`limited`) |
| `subagents_enabled` | bool | Toggle subagent support |
| `auto_update`, `keymap`, `show_path`, `show_hints`, `unicode_mode`, `include_gitignored_files`, `respect_gitignore`, `attribution` | misc UI/workspace toggles |

## Related locations

- Skills: `.agents/skills/` and `.devin/skills/` and `.windsurf/skills/` (project); `~/.agents/skills/`, `~/.config/devin/skills/` (`%APPDATA%\devin\skills\`), `~/.codeium/<channel>/skills/` (global)
- Subagents: `.devin/agents/<name>.md` or `.devin/agents/<name>/AGENT.md`, `.agents/agents/`, `~/.config/devin/agents/`
- Rules: `AGENTS.md` at project root; user-level `~/.config/devin/AGENTS.md`
- Hooks: `.devin/hooks.v1.json` (recommended) or `"hooks"` in config files
- Plugins: `.devin-plugin/plugin.json` manifest inside a plugin source; `devin plugins` CLI

Restart the CLI/Desktop session after config changes — settings load at startup.

# OpenCode Settings Reference

Configuration for [anomalyco/opencode](https://github.com/anomalyco/opencode) (v1.14.x, Go-based, npm/Bun runtime).

## Contents

- [Config File Locations](#config-file-locations)
- [File Format and Schema](#file-format-and-schema)
- [Top-Level Keys](#top-level-keys)
- [Core Settings Examples](#core-settings-examples)
- [Permissions](#permissions)
- [Provider Configuration](#provider-configuration)
- [TUI Settings (tui.json)](#tui-settings-tuijson)
- [Variable Substitution](#variable-substitution)
- [Environment Variables](#environment-variables)

## Config File Locations

OpenCode loads configuration files in this order (later overrides earlier; objects are deep-merged, arrays like `instructions` are concatenated):

| Priority | Location | Purpose |
|----------|----------|---------|
| 1 (lowest) | Remote `.well-known/opencode` | Organizational defaults |
| 2 | `~/.config/opencode/opencode.json` | User-global config |
| 3 | `$OPENCODE_CONFIG` (env var) | Custom override path |
| 4 | `<project>/opencode.json` (or `.json5`/`.jsonc`) | Project config |
| 5 | `<project>/.opencode/` directory | Project sub-config |
| 6 | `$OPENCODE_CONFIG_CONTENT` (env var) | Inline JSON content |
| 7 | Managed config (system dirs) | IT-deployed |
| 8 (highest) | macOS managed preferences | MDM |

**System managed paths:**
- macOS: `/Library/Application Support/opencode/`
- Linux: `/etc/opencode/`
- Windows: `%ProgramData%\opencode`

**Subdirectory conventions** (plural names; singulars also accepted for backwards compatibility): `agents/`, `commands/`, `tools/`, `themes/`, `plugins/`, `skills/`, `modes/`.

## File Format and Schema

OpenCode accepts both **JSON** and **JSONC** (JSON with comments). Reference the schema for editor autocompletion:

```json
{
  "$schema": "https://opencode.ai/config.json"
}
```

TUI-specific settings (theme, keybinds) live in a separate `tui.json` file with its own schema: `https://opencode.ai/tui.json`.

The schema is enforced via Zod in `packages/opencode/src/config/config.ts`. Legacy keys (e.g., `theme`, `tui` keys placed inside `opencode.json`) are stripped with a warning.

## Top-Level Keys

| Key | Type | Purpose |
|-----|------|---------|
| `$schema` | string | Schema URL (recommended for IDE autocomplete) |
| `model` | string | Default LLM in `provider/model-id` format |
| `small_model` | string | Lightweight model (titles, summaries) |
| `provider` | object | Provider credentials/options/custom registrations |
| `agent` | object | Custom agents and subagents |
| `default_agent` | string | Which agent loads by default |
| `command` | object | Custom slash commands |
| `mcp` | object | MCP servers |
| `plugin` | array of string | npm plugin packages |
| `tools` | object | Disable specific built-in tools |
| `permission` | object | Per-tool allow/ask/deny rules |
| `instructions` | array of string | Extra instruction file paths/globs/URLs |
| `formatter` | object | Code formatters per language |
| `share` | string | Conversation sharing: `manual` / `auto` / `disabled` |
| `server` | object | Headless server: port, hostname, mDNS, CORS |
| `snapshot` | boolean | Track file changes for undo (default: true) |
| `autoupdate` | boolean / string | `true` / `false` / `"notify"` |
| `compaction` | object | Context compaction tuning |
| `watcher` | object | File watcher ignore patterns |
| `disabled_providers` | array of string | Providers to exclude |
| `enabled_providers` | array of string | Allowlist of providers |
| `experimental` | object | Development/preview features |

## Core Settings Examples

### Basic config (`~/.config/opencode/opencode.json`)

```json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4",
  "share": "manual",
  "autoupdate": "notify",
  "instructions": [
    "AGENTS.md",
    "CONTRIBUTING.md",
    "docs/style-guide.md"
  ]
}
```

### Disable specific tools

```json
{
  "tools": {
    "write": false,
    "bash": false,
    "websearch": false
  }
}
```

The 13 built-in tools: `bash`, `edit`, `write`, `read`, `grep`, `glob`, `lsp`, `apply_patch`, `skill`, `todowrite`, `webfetch`, `websearch`, `question`.

### Server / headless mode

```json
{
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": false,
    "cors": ["http://localhost:3000"]
  }
}
```

## Permissions

OpenCode uses a `permission` key with three outcomes per rule: `"allow"`, `"ask"`, `"deny"`.

```json
{
  "permission": {
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status *": "allow",
      "git log *": "allow",
      "rm -rf *": "deny"
    },
    "webfetch": "allow",
    "external_directory": "ask"
  }
}
```

**Permission keys:** `read`, `edit`, `bash`, `webfetch`, `external_directory`, `task`, `skill`, `lsp`, `question`, `websearch`, `codesearch`, `glob`, `grep`, `doom_loop`.

**Pattern matching:** `*` matches any chars, `?` matches one char, `~`/`$HOME` expands.

**Defaults:** Most permissions default to `"allow"`. `doom_loop` and `external_directory` default to `"ask"`. `.env` files are denied by default.

## Provider Configuration

```json
{
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000
      }
    },
    "azure-openai": {
      "npm": "@ai-sdk/azure",
      "name": "Azure OpenAI",
      "options": {
        "baseURL": "https://YOUR.openai.azure.com/openai",
        "apiVersion": "2024-10-21"
      },
      "models": {
        "gpt-4o": { "name": "GPT-4o (Azure)" }
      }
    },
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama3.3": { "name": "Llama 3.3", "limit": { "context": 128000 } }
      }
    }
  }
}
```

**Authenticate via CLI:** `opencode auth login` → stored in `~/.local/share/opencode/auth.json`.
**List providers:** `opencode auth list` (alias `ls`).

OpenCode supports 75+ providers including OpenAI, Anthropic, Vertex AI, Bedrock, Groq, OpenRouter, DeepSeek, Moonshot, xAI, Ollama, LM Studio, llama.cpp, Hugging Face.

## TUI Settings (tui.json)

Theme and keybinds live in a separate file:

**Locations** (in priority order):
- User: `~/.config/opencode/tui.json` (or `$XDG_CONFIG_HOME/opencode/tui.json`)
- Project: `<project>/.opencode/tui.json`
- Working dir: `./.opencode/tui.json`

```json
{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight",
  "keybinds": {
    "leader": "ctrl+x",
    "session_new": "<leader>n",
    "session_compact": "none",
    "agent_cycle": "tab"
  }
}
```

Built-in themes include: `tokyonight`, `everforest`, `catppuccin`, `gruvbox`, `nord`, `matrix`, and more. Custom themes go in `~/.config/opencode/themes/*.json` (truecolor required).

Set any keybind value to `"none"` to disable. The default leader key is `ctrl+x`.

## Variable Substitution

In any string value:

| Pattern | Resolves to |
|---------|-------------|
| `{env:VAR_NAME}` | Environment variable |
| `{file:path/to/file}` | File contents (relative, absolute, or `~` paths) |

```json
{
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  },
  "agent": {
    "reviewer": {
      "prompt": "{file:./prompts/reviewer.md}"
    }
  }
}
```

## Environment Variables

| Variable | Purpose |
|----------|---------|
| `OPENCODE_CONFIG` | Path to a custom config file (added to load order) |
| `OPENCODE_CONFIG_CONTENT` | Inline JSON config (highest user priority) |
| `OPENCODE_ENABLE_EXA` | Enable `websearch` tool (`=1`) |
| `XDG_CONFIG_HOME` | Override config directory base |

Auth credentials live in `~/.local/share/opencode/auth.json`.

## Comparison with Claude Code

| Feature | Claude Code | OpenCode |
|---------|------------|----------|
| Config format | JSON (`settings.json`) | JSON / JSONC (`opencode.json`) |
| Global path | `~/.claude/settings.json` | `~/.config/opencode/opencode.json` |
| Project path | `.claude/settings.json` | `opencode.json` (or `.opencode/`) |
| Schema | implicit | `https://opencode.ai/config.json` |
| Permissions | `permissions.allow/ask/deny` arrays | `permission` object with allow/ask/deny |
| Theme | n/a | Separate `tui.json` |
| Provider routing | Anthropic-only by default | 75+ providers, switch via `model` string |
| Instructions file | `CLAUDE.md` | `AGENTS.md` (with `CLAUDE.md` fallback) |
| Custom commands | `.claude/commands/*.md` | `.opencode/commands/*.md` or `command` key |
| Plugin packages | `.claude-plugin/` (Anthropic plugins) | `plugin: []` array (npm packages) |

## Sources

- https://opencode.ai/docs/config/
- https://opencode.ai/docs/permissions/
- https://opencode.ai/docs/providers/
- https://opencode.ai/docs/themes/
- https://opencode.ai/docs/keybinds/
- https://opencode.ai/docs/tools/
- https://github.com/anomalyco/opencode