> ## Documentation Index
> Fetch the complete documentation index at: https://platform.stepfun.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration files

Use `config.toml` for default models, permissions, context compaction, the interface, and MCP servers. Temporary launch options do not automatically rewrite the file.

## Configuration locations

| Scope | Default location | Purpose |
| - | - | - |
| Global | `~/.stepcode/config.toml` | Applies across projects |
| Project | `<project>/.stepcode/config.toml` | Overrides global settings; requires project trust |

Project configuration merges nested objects key by key and replaces arrays as a whole. Settings marked global-only, such as the proxy and default project trust, cannot be overridden by a project.

The global file is created on first run. Writes use an atomic temporary-file-and-rename operation and preserve the leading comment block. TOML does not support `null`; unsupported expressions are stripped. Remove an optional key to unset it.

See [Data paths](https://platform.stepfun.ai/docs/en/step-code/configuration/data-paths.md) for other local data locations.

### External JSON configuration

`STEPCODE_CONFIG_PATH` points to external JSON configuration. Saving model and permission preferences writes back to that JSON file rather than `models.json`; do not treat it as a read-only temporary model catalog.

## Configuration example

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
theme = "step-blue"
defaultProvider = "step"
defaultModel = "step-3.7-flash"
permissionPreset = "approve-for-me"
autoResume = true

[telemetry]
enabled = true
```

This example uses the Approve for Me permission mode. To require confirmation before file changes and commands, set `permissionPreset` to `"ask"`. See [Permissions and safety](https://platform.stepfun.ai/docs/en/step-code/guides/permissions.md) for mode behavior.

## Top-level fields

### Models and thinking

| Field | Description |
| - | - |
| `defaultProvider`, `defaultModel` | Default provider and model; save with Enter in `/model` |
| `defaultThinkingLevel` | Default thinking level |
| `modelThinkingLevels` | Per-model thinking levels keyed by `provider/modelId` |
| `thinkingBudgets` | Token budgets for thinking levels |
| `hideThinkingBlock` | Hide thinking-block display; default `false` |
| `showCacheMissNotices` | Show cache-miss and compaction-cost notices; default `false` |

Client levels are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Available levels and their effective behavior depend on the provider and model.

See [Authentication and models](https://platform.stepfun.ai/docs/en/step-code/configuration/models.md) for provider setup and model selection.

### Interface

| Field | Default | Description |
| - | - | - |
| `theme` | `step-blue` | Theme name; see [Custom themes](https://platform.stepfun.ai/docs/en/step-code/customization/themes.md) for selection and creation |
| `statusTips` | `true` | Show one working-line tip per turn; set to `false` to disable |
| `quietStartup` | `false` | Reduce startup output |
| `collapseChangelog` | `false` | Collapse the changelog |
| `doubleEscapeAction` | `tree` | Double-Esc action with empty input: `tree`, `fork`, `none` |
| `treeFilterMode` | `default` | `default`, `no-tools`, `user-only`, `labeled-only`, `all` |
| `editorPaddingX` | `0` | Horizontal input padding, 0–3 |
| `outputPad` | `1` | Horizontal output padding, 0 or 1 |
| `autocompleteMaxVisible` | `5` | Visible completion items, 3–20 |
| `showHardwareCursor` | `false` | Show the terminal hardware cursor |
| `externalEditor` | Unset | External editor; otherwise checks `VISUAL`, then `EDITOR` |

Disable working-line tips:

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
statusTips = false
```

### Sessions and networking

| Field | Default | Description |
| - | - | - |
| `sessionDir` | Unset | Custom session directory |
| `transport` | `auto` | Model transport: `auto`, `sse`, `websocket`, `websocket-cached`; requires provider support |
| `steeringMode`, `followUpMode` | `one-at-a-time` | Message delivery during streaming |
| `httpProxy` | Unset | Outbound proxy; global-only |
| `httpIdleTimeoutMs` | 300,000 | HTTP idle timeout in milliseconds; 0 disables |
| `websocketConnectTimeoutMs` | 15,000 | WebSocket connection timeout in milliseconds; 0 disables |

See [Environment variables](https://platform.stepfun.ai/docs/en/step-code/configuration/environment.md) for environment-based configuration.

### Shell and commands

| Field | Default | Description |
| - | - | - |
| `shellPath` | Unset | Custom shell path with `~` expansion, useful for environments such as Cygwin |
| `shellCommandPrefix` | Unset | Content prepended to each shell command, such as alias setup |
| `npmCommand` | Unset | npm command as argv, such as `["mise", "exec", "node@20", "--", "npm"]` |

### Projects and permissions

| Field | Description |
| - | - |
| `permissionPreset` | Defaults to `approve-for-me`; accepts `ask`, `approve-for-me`, or `full-access`. Saved legacy permission modes reset to Ask. Select modes through `/permissions`; see [Permissions and safety](https://platform.stepfun.ai/docs/en/step-code/guides/permissions.md) for behavior |
| `defaultProjectTrust` | Resource-loading policy for untrusted projects; default `ask`, global-only |
| `enableAnalytics` | Optional usage analytics; default `false`, managed separately from feedback and other services |

See [Permissions and safety](https://platform.stepfun.ai/docs/en/step-code/guides/permissions.md) for project resource loading and tool approval.

## Section settings

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
[compaction]
enabled = true
reserveTokens = 16384
keepRecentTokens = 20000
contextProjection = "clm-v1"

[subagent]
background = false

[branchSummary]
reserveTokens = 16384
skipPrompt = false

[retry]
enabled = true
maxRetries = 3
baseDelayMs = 2000

[thinkingBudgets]
minimal = 1024
low = 4096
medium = 10240
high = 32768

[images]
autoResize = true
blockImages = false

[terminal]
showImages = true
imageWidthCells = 60
clearOnShrink = false
showTerminalProgress = false
hyperlinks = "auto"
images = "auto"
trueColor = "auto"

[markdown]
codeBlockIndent = "  "
mermaid = "streaming"
```

* `[compaction].enabled = false` only disables automatic compaction. `reserveTokens` reserves window space; `keepRecentTokens` controls recent messages retained.
* `[compaction].contextProjection` defaults to `clm-v1` when unset and automatic compaction is enabled; `off` keeps summary compaction only and does not enable CLM; `lightweight-v1` is a lightweight projection. Disabling automatic compaction also disables implicit CLM.
* `[branchSummary].skipPrompt = true` skips the branch-switch prompt and does not generate a summary by default.
* `[subagent].background = false` runs every subagent task in the foreground. Background execution is allowed by default, with up to 8 concurrent tasks and automatic stop after 10 minutes idle.
* `[retry].baseDelayMs = 2000` uses exponential backoff: 2, 4, and 8 seconds. Keep `provider.maxRetries` at its default `0`; positive values let SDK retries precede Step's quota handling and may wait until quota resets. `provider.timeoutMs` sets a per-request timeout.
* `[thinkingBudgets]` sets token budgets for thinking levels.
* `[images].autoResize = true` resizes images to within 2,000 px.
* `[images].blockImages = true` prevents sending images to models; `[terminal].showImages` only controls display.
* `[terminal].images` accepts `kitty`, `iterm2`, `auto`, or `false`; match it to terminal capabilities.
* `[terminal].imageWidthCells` measures inline width in terminal columns. `clearOnShrink` controls clearing after content shrinks, `showTerminalProgress` controls OSC 9;4 progress, and `hyperlinks` accepts `true`, `false`, or `"auto"`.
* `[markdown].mermaid` accepts `streaming`, `final`, or `off`.
* `[warnings].anthropicExtraUsage` defaults to `true` and controls Claude Pro/Max extra-usage notices.

## MCP servers

`[mcp_servers.<name>]` declares a global MCP server. See [MCP](https://platform.stepfun.ai/docs/en/step-code/customization/mcp.md) for setup, transports, authentication, and fields.

## Tool and resource arrays

| Field | Purpose |
| - | - |
| `defaultTools` | Native built-in tool set, such as `read`, `bash`, `edit`, `write`, `grep`, `find`, and `ls`; see [Built-in tools](https://platform.stepfun.ai/docs/en/step-code/reference/tools.md) for Step and extension tool selection |
| `enabledModels` | Models cycled with Ctrl+P; supports glob patterns such as `["claude-*", "gpt-4o"]` |
| `packages` | Resource packages to install and load |
| `extensions`, `skills`, `prompts`, `themes` | Extra resource paths with glob, exclusion, and exact selection support |
| `enableSkillCommands` | Register Skills as `/skill:<name>`; default `true` |

Resource arrays accept files or directories, glob patterns, `!` exclusions, and exact `+path` / `-path` controls. Global relative paths resolve from `~/.stepcode/agent`; project paths resolve from `.stepcode`. See [Built-in tools](https://platform.stepfun.ai/docs/en/step-code/reference/tools.md) for launch options.

## TUI settings

| Field | Default | Description |
| - | - | - |
| `tuiMode` | `regular` | Also accepts experimental `fullscreen` |
| `fullscreenExitOutput` | `transcript` | Show the transcript on exit, or use `resume-hint` |
| `fullscreenScrollbar` | `auto` | Also accepts `always`, `hidden` |
| `fullscreenCopyOnSelect` | `true` | Copy on selection; use Ctrl+X when disabled |

## Deprecated settings

| Item | Status |
| - | - |
| `~/.stepcode/agent/settings.json` | Retired and no longer read or written; migrate settings manually to `config.toml` |
| `~/.stepcode/agent/step-settings.json` | Retired |
| `~/.stepcode/agent/auth.json`, `agent/models.json` | Old locations; now at the `~/.stepcode` root |
| `.step-harness` | Retired and no longer written; old credentials are read once during startup migration |

## Telemetry

Disable telemetry in global `config.toml`:

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
[telemetry]
enabled = false
```

This setting controls telemetry. Model requests, MCP calls, and manual feedback are managed separately. See [Permissions and safety](https://platform.stepfun.ai/docs/en/step-code/guides/permissions.md) for data handling and sharing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.