/harness-settings

Manage provider-specific configuration — permissions, model selection, sandboxing, environment variables, and feature flags — through the harness settings entity.

What is the settings entity?

The settings entity lets you commit provider-specific configuration into .harness/src/settings/ and have harness write it to the correct provider config file on apply. Unlike entities such as prompt, skill, or mcp, settings are inherently per-provider: each file targets exactly one provider and is written to that provider's native config location.

Source files:

Per-provider override sidecars (.overrides.<provider>.yaml) are not applicable to settings entities — the file is already provider-specific.

Important: The hooks key in .claude/settings.json is managed by the hook entity. Do not set hooks inside claude.json — it will be merged in from your hook sources at apply time. Similarly, for Codex, mcp_servers, agents, and notify entries are merged in from their respective entity types; set only the keys your settings entity owns.

CLI commands

# Scaffold a settings source file
npx harness add settings claude
npx harness add settings codex
npx harness add settings copilot

# Preview what will be written
npx harness plan

# Write settings to provider config files
npx harness apply

# Remove a settings entity (keeps source by default)
npx harness remove settings claude
npx harness remove settings claude --no-delete-source

Claude Code (claude.json)

Written to .claude/settings.json. This is the project-scoped settings file committed to git and shared with your team.

Common fields

Permissions

The permissions object lives inside the settings.json root. Rules are evaluated: deny first, then ask, then allow. First match wins.

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": ["Bash(npm run *)", "Bash(git *)", "Read(~/.zshrc)"],
    "ask":   ["Bash(git push *)"],
    "deny":  ["Bash(curl *)", "Read(./.env)", "Read(./secrets/**)"],
    "additionalDirectories": ["../docs/"]
  }
}

defaultMode options:

Rule syntax: Tool or Tool(specifier). Examples:

• "Bash" — all Bash commands
• "Bash(npm run *)" — commands starting with npm run
• "Read(./.env)" — reading the .env file
• "WebFetch(domain:example.com)" — fetches to example.com
• "mcp__*" — all MCP tool calls

Managed-only permission keys (for enterprise managed-settings.json):

• disableBypassPermissionsMode: "disable" — prevent --dangerously-skip-permissions
• allowManagedPermissionRulesOnly: true — block user/project allow/deny rules
• allowManagedMcpServersOnly: true — enforce MCP allowlist from managed settings

Sandbox settings

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker", "git"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead":   ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

Copy-paste example

This is a typical project-level claude.json for a team repo:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-6",
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Bash(npm run *)",
      "Bash(pnpm *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git status)",
      "Read",
      "Edit",
      "Write",
      "mcp__*"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Bash(curl *)",
      "Bash(wget *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "includeGitInstructions": true,
  "autoUpdatesChannel": "stable",
  "companyAnnouncements": [
    "Run pnpm check:write before committing."
  ]
}

OpenAI Codex CLI (codex.json)

Written to .codex/config.toml and merged with MCP server entries, agent definitions, and hook notify commands from their respective entities. Only set the keys your settings entity owns — do not duplicate mcp_servers, agents.<name>, or notify.

Common fields

Copy-paste example

{
  "model": "gpt-5-codex",
  "model_reasoning_effort": "medium",
  "approval_policy": "on-request",
  "sandbox_mode": "workspace-write",
  "web_search": "cached",
  "features": {
    "shell_tool": true,
    "multi_agent": true
  },
  "agents": {
    "max_threads": 4
  }
}

GitHub Copilot (copilot.json)

GitHub Copilot's primary customization surface is .github/copilot-instructions.md (managed by the prompt entity) and .vscode/mcp.json (managed by the mcp entity). The copilot.json settings entity handles remaining provider-level configuration written to .github/copilot-settings.json.

Copilot's custom instructions, agent skills, and MCP servers are all managed by their respective harness entities — not by the settings entity.

Entity interactions

Typical workflow

npx harness add settings claude
# Edit .harness/src/settings/claude.json
npx harness plan          # verify what will be written
npx harness apply         # write .claude/settings.json

To manage settings alongside other entities in a single apply:

npx harness add settings claude
npx harness add mcp my-server
npx harness add hook guard
# Edit source files
npx harness apply         # writes all provider artifacts at once

Official documentation

• Claude Code settings reference: https://code.claude.com/docs/en/settings
• Claude Code permissions: https://code.claude.com/docs/en/permissions
• Claude Code sandboxing: https://code.claude.com/docs/en/sandboxing
• OpenAI Codex CLI config reference: https://developers.openai.com/codex/config-reference
• OpenAI Codex CLI sample config: https://developers.openai.com/codex/config-sample
• GitHub Copilot custom instructions: https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot
• GitHub Copilot VS Code settings: https://code.visualstudio.com/docs/copilot/reference/copilot-settings