Settings & Config

Command Code stores configuration in two main kinds of JSON file: config.json for your personal preferences, and the settings.json family for how the agent behaves in a project. A few smaller files hold MCP servers, keybindings, credentials, and scheduled jobs. This page is the complete reference - every key, where it lives, how it's resolved, and its default.

The files at a glance

~/.commandcode/                        (user-level)
├── config.json          ← your preferences: model, theme, provider…
├── settings.json        ← your global hooks, permissions, MCP, skills, mods
├── auth.json            ← credentials (managed by login; don't hand-edit)
├── keybindings.json     ← keybinding overrides
├── mcp.json             ← user-scope MCP servers
├── cron/jobs.json       ← scheduled jobs (machine-managed)
└── projects/{project}/
    ├── config.json      ← per-project state (taste onboarding progress)
    └── mcp.json         ← local (per-project) MCP servers

<project>/.commandcode/                (project-level)
├── settings.json        ← shared with your team, commit this
└── settings.local.json  ← your personal overrides, don't commit this
<project>/.mcp.json      ← project-scope MCP servers, commit this

No file is created just by launching Command Code. Files appear the first time something is written - your first model or theme change creates config.json, and approving a command for a project creates settings.local.json. Until then, built-in defaults apply.

`config.json` - personal preferences

~/.commandcode/config.json is a single user-level file. It's yours: it never lives in a repository, and Command Code updates it for you as you use the CLI (for example when you pick a model with /model or switch themes with /theme). It's written with 0600 permissions.

Key	Type	What it does	Default
`provider`	string	Selected auth provider: `anthropic`, `github-copilot`, `codex`, or `command-code`	-
`model`	string	Default model for new sessions	Curated default model
`theme`	`dark` \| `light`	Terminal theme	`dark`
`compactMode`	`default` \| `fast`	Auto-compact aggressiveness	`default`
`reasoningEffort`	object	Per-model reasoning effort, keyed by model id. Values: `low`, `medium`, `high`, `xhigh`, `max`	Provider default
`featureModels`	object	Model overrides for background features, keyed by feature. Keys: `titleGeneration`, `compaction`, `toolDescription`, `tasteOnboarding`, `tasteLearning`, `branchSummarization`. Managed by `/configure-models`	Curated defaults
`collapsePastedText`	boolean	Collapse long pasted/dictated text (>300 chars) into a `[first words… +NL]` token	`true`
`tasteLearning`	boolean	Global toggle for taste learning	`true`
`ideContextEnabled`	boolean	IDE context integration	`true`
`autoInstallExtension`	boolean	Auto-install the IDE extension on startup	`true`
`forceOAuth`	boolean	Require OAuth, disallow API-key auth	`false`
`defaultExportFormat`	`html` \| `jsonl` \| `md`	Format a bare `/export` writes	`html`
`defaultShareGistFormat`	`html` \| `jsonl` \| `md`	Format a bare `/share gist` posts	`html`
`treeFilterMode`	string	Default `/tree` filter: `default`, `no-tools`, `user-only`, `labeled-only`, `all`	`default`
`branchSummarySkipPrompt`	boolean	Never prompt for a branch summary in `/tree`	`false`
`onDemandToolDescriptions`	boolean	Generate the permission prompt's command explanation only on `ctrl+e`	`true`
`installed`	boolean	First-install detection (machine-written)	-
`firstMessageSent`	boolean	First-message detection (machine-written)	-

You rarely need to edit this file directly - slash commands like /model, /theme, /effort, /config, and /configure-models manage it for you.

Note

The /config overlay surfaces a curated subset of these keys for point-and-click editing (theme, compact mode, force-OAuth, tree filter, on-demand tool descriptions, branch-summary prompt, export/share formats, taste learning, and the feature-model rows). The rest are still valid on disk - reasoning effort is managed by /effort, and the default permission mode is session-only.

`settings.json` - project behavior

Settings files hold the things that shape how the agent behaves: model, permissions, hooks, MCP servers, skills, and mods. Unlike config.json, they exist at multiple scopes and are deep-merged.

Scope	File	Use it for
Project local	`<project>/.commandcode/settings.local.json`	Personal overrides for one project. Approved permissions are saved here. Add it to `.gitignore`.
Project	`<project>/.commandcode/settings.json`	Team-shared rules. Commit it so everyone gets the same hooks and permissions.
User	`~/.commandcode/settings.json`	Your defaults across every project.

The legacy ~/.commandcode/config.json also feeds this layer as the lowest-precedence source for seven overlapping keys (model, theme, compactMode, forceOAuth, tasteLearning, featureModels, reasoningEffort).

Top-level keys

Key	Type	What it does	Default
`model`	string	Main model id for the session	Curated default
`effort`	string	Global reasoning effort	-
`reasoningEffort`	object	Per-model reasoning effort override	-
`permissions`	object	Permission rules and toggles (see below)	`{}`
`permissionMode`	string	Legacy default mode; superseded by `permissions.defaultMode`	`default`
`hooks`	object	Lifecycle hooks (see below)	-
`theme`	string	Terminal theme	-
`tasteLearning`	boolean	Taste-learning gate (per-project override)	`true`
`compactMode`	`default` \| `fast`	Auto-compact aggressiveness	`default`
`forceOAuth`	boolean	Require OAuth	-
`featureModels`	object	Per-feature model overrides	-
`providers`	object	Bring-your-own provider configuration	-
`plugins`	string[]	Plugin list	-
`skills`	string[]	Extra skill directories (`~/` expands; relative paths resolve to the project root)	-
`disableSkillShellExecution`	boolean	Disable dynamic !`…` shell placeholders in skill bodies	`false`
`disableScratchpad`	boolean	Disable the per-session scratchpad directory	`false`
`mcp`	object	Inline MCP servers: `{ "servers": [ … ] }`	-
`mods`	object	Declarative mod config: `{ sources?, paths?, disabled? }`	-
`disabledSkills`	string[]	Skill names to disable (unioned across layers)	-

permissions

Rules that allow, ask, or deny operations, plus a few related toggles. See Permissions for the rule syntax and matching behavior.

{
	"permissions": {
		"allow": ["Bash(npm test)", "Bash(pnpm build)"],
		"ask": ["Bash(git push:*)"],
		"deny": ["Bash(rm -rf:*)"],
		"defaultMode": "default",
		"additionalDirectories": ["../shared-lib"],
		"disableBypass": false
	}
}

Key	Type	What it does
`allow`	string[]	Rules that auto-approve matching operations
`ask`	string[]	Rules that always prompt
`deny`	string[]	Rules that always block
`defaultMode`	string	Default permission mode: `default`, `auto-accept`, `plan`, or `bypass`
`additionalDirectories`	string[]	Extra in-workspace directories (`~/` expands; relative paths resolve to the project root)
`disableBypass`	boolean \| string	`true` (or `"disable"`) makes bypass / `--yolo` mode unenterable

The four rule lists (allow, ask, deny, additionalDirectories) union across every scope rather than being overwritten, so a rule added at any level always applies. When you approve a command with "don't ask again for this project," it's written to settings.local.json.

hooks

Hooks run shell scripts at lifecycle events. Only four events are recognized: PreToolUse, PostToolUse, Stop, and SessionStart.

{
	"hooks": {
		"PreToolUse": [
			{
				"matcher": "shell",
				"hooks": [
					{ "type": "command", "command": "./scripts/guard.sh", "timeout": 30 }
				]
			}
		]
	}
}

Each handler must be { "type": "command", "command": "…" }, with an optional timeout (in seconds, 0–600), async, and failClosed. See Hooks for the full schema and event payloads.

MCP servers

MCP servers can be declared inline under mcp.servers in settings.json, but the dedicated files below are the usual home. See MCP for the entry schema.

Other configuration files

Path	Contents	Edit by hand?
`~/.commandcode/auth.json`	Command-provider API credentials, written `0600`	No - managed by `/login` and `/logout`
`~/.commandcode/keybindings.json`	Keybinding overrides, merged over the defaults (`id → key` or `id → key[]`)	Yes - see Keybindings
`~/.commandcode/mcp.json` (or `.mcp.json`)	User-scope MCP servers: `{ "mcpServers": { … } }`	Yes
`<project>/.mcp.json`	Project-scope MCP servers (commit this)	Yes
`~/.commandcode/projects/{project}/mcp.json`	Local (per-project) MCP servers	Via CLI
`~/.commandcode/cron/jobs.json`	Durable scheduled / cron jobs	No - machine-managed
`~/.commandcode/telemetry-install-id`	Anonymous per-machine telemetry id	No - machine-managed

MCP scope precedence (low → high): settings.json mcp.servers < user mcp.json < project .mcp.json < local projects/{project}/mcp.json.

Environment variables

Command Code also reads a handful of environment variables as configuration:

Variable	What it does
`COMMAND_CODE_API_KEY`	Command-provider API key; overrides `auth.json` when set
`CMD_ZDR`	`1` enables Zero-Data-Retention mode (pauses ZDR-incompatible feature models)
`COMMANDCODE_SKIP_UPDATES`	Skip the auto-updater
`COMMANDCODE_SCRATCHPAD` / `COMMANDCODE_SCRATCHPAD_BASE`	Override the per-session scratchpad location or base directory
`MCP_TOOL_TIMEOUT`	Per-request MCP tool timeout, in milliseconds
`MAX_MCP_OUTPUT_TOKENS`	Cap on MCP tool output tokens (default `25000`)
`DO_NOT_TRACK`	Standard opt-out that disables telemetry
`HOME` / `USERPROFILE`	Home directory used to resolve `~/.commandcode`

Precedence

When the same setting is defined in more than one place, the more specific scope wins:

<project>/.commandcode/settings.local.json - highest
<project>/.commandcode/settings.json
~/.commandcode/settings.json
~/.commandcode/config.json (legacy fields only) - lowest

Maps are deep-merged and scalars overwrite, except the permission rule lists (allow, ask, deny, additionalDirectories), which union across all layers.

The model for a session is resolved separately, since it can be set in more ways:

--model flag - highest
/model picked during the session
model in settings.json / config.json
Built-in default - lowest

A running session reads its default model from config.json once at startup. Changing the default in another terminal (or editing the file by hand) doesn't affect sessions that are already running - new sessions pick it up.

Best practices

Commit <project>/.commandcode/settings.json so your team shares hooks and permission rules, and code review sees changes to them.
Gitignore settings.local.json - it holds your personal approvals and overrides:

.commandcode/settings.local.json

Never commit ~/.commandcode files. They're user-level by design; auth.json holds credentials.
Let slash commands manage config.json rather than editing it by hand.

Per-project state

~/.commandcode/projects/{project}/config.json holds machine-written state for each project you use Command Code in - currently taste onboarding progress (tasteOnboarding: completed/skipped flags, learned and skipped sessions, last learning date). It lives in your home directory, not the repository, and Command Code manages it entirely - you never need to edit it.

Core Concepts

Settings & Config

Top-level keys

permissions

hooks

MCP servers