Reference

settings.json

Every setting, where the files live, and which one wins.

Two files, both optional:

File	Applies to
`~/.contextcode/settings.json`	Every project
`<project>/.contextcode/settings.json`	That project

The project file wins where they overlap. Environment variables win over both.

A complete example

JSON

{
  "permissions": {
    "mode": "default",                    // plan | default | auto | bypass
    "allow": ["run_bash(go *)", "run_bash(git *)"],
    "deny":  ["run_bash(sudo *)"]         // deny always wins, in every mode
  },

  "mcp": {
    "servers": {
      "github":     { "url": "https://api.githubcopilot.com/mcp/",
                      "headers": { "authorization": "Bearer …" } },
      "filesystem": { "command": "npx",
                      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] }
    }
  },

  "providers": {                          // optional — bring your own keys
    "anthropic": { "api_key_env": "ANTHROPIC_API_KEY" },
    "groq":      { "api_key_env": "GROQ_API_KEY", "model": "llama-4-maverick" },
    "ollama":    { "base_url": "http://localhost:11434", "model": "qwen3-coder" },
    "my-vllm":   { "base_url": "http://gpu-box:8000", "api_key": "…",
                   "model": "qwen3-coder-32b" }
  },

  "anthropic_fallback_key": "sk-ant-…",   // or anthropic_fallback_key_env

  "agents": { "worktrees": true },        // isolate background coders

  "hooks": { "turn_end": ["afplay /System/Library/Sounds/Glass.aiff"] }
}

The settings

permissions

Key	Values	Meaning
`mode`	`plan`, `default`, `auto`, `bypass`	How much runs without asking
`allow`	patterns	Never prompt for these
`deny`	patterns	Always refuse, in every mode

Patterns match a command shape: run_bash(git *) covers every git command. See Deciding what runs without asking.

mcp.servers

One entry per tool server. Either url (with optional headers) for a remote server, or command plus args for one you launch locally. /mcp reload applies changes without a restart. See Connecting other tools.

providers

Key	Meaning
`api_key`	The key, inline. Avoid in a committed file.
`api_key_env`	Name of an environment variable holding the key. Prefer this.
`base_url`	Required for self-hosted and custom endpoints
`api`	Endpoint shape, when it isn't inferable
`model`	Default model for this provider

See Using your own API keys.

agents

worktrees (default true) isolates each background coder in its own git worktree. Turn it off only if your build can't run from a secondary checkout — and then run one agent at a time.

hooks

Event name to a list of shell commands. turn_end is the one most people use. Hooks run through your shell; use absolute paths.

Environment variables

Variable	Effect
`CONTEXTCODE_AGENT_DAEMON_AUTOSTART=off`	Don't start the shared agent daemon on demand
`CONTEXTCODE_ANTHROPIC_FALLBACK_KEY`	Wins over both fallback-key settings

Checking what actually resolved

Terminal

csc doctor

Reports the effective configuration — which file each value came from, and what failed to resolve. Faster than reasoning about precedence.

If it doesn't work

A setting has no effect. Precedence: environment, then project file, then global file. csc doctor shows the winner.

Invalid JSON. The file is JSON with comments (jsonc) — // is fine, trailing commas are not.

A provider key isn't picked up. api_key_env names a variable that must be exported in the environment csc runs in, not just in an interactive shell profile.