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.

Complete example

Use this as a starting point; you do not need to fill in every optional setting:

theme = "step-blue"
defaultProvider = "step"
defaultModel = "step-3.7-flash"
permissionPreset = "bypass"
autoResume = true

[telemetry]
enabled = true

This example uses the default Bypass mode. Change permissionPreset to "ask" to require individual approvals.

Top-level fields

Models and thinking

Field	Description
`defaultProvider`, `defaultModel`	Default provider and model; save with Ctrl+S 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; not every model supports every level.

Interface

Field	Default	Description
`theme`	`step-blue`	Theme name
`statusTips`	`true`	Show working-line tips
`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`

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

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	Default	Description
`permissionPreset`	`bypass`	`ask`, `read-only`, `bypass`, or `autopilot`
`defaultProjectTrust`	`ask`	Resource-loading policy for untrusted projects; global-only
`enableAnalytics`	`false`	Optional usage analytics, separate from feedback and other services

Project trust controls loading configuration, extensions, and resources. It is not a filesystem sandbox.

Section settings

[compaction]
enabled = true
reserveTokens = 16384
keepRecentTokens = 20000
contextProjection = "off"

[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.
[branchSummary].skipPrompt = true skips the branch-switch prompt and does not generate a summary by default.
[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

Declare servers in the global configuration:

[mcp_servers.local-tools]
command = "node"
args = ["/absolute/path/to/mcp-server.js"]
env = { LOG_LEVEL = "info" }
startup_timeout_sec = 30
tool_timeout_sec = 300

Replace the path with your server script. See MCP for transports, authentication, and filtering.

Tool and resource arrays

Field	Purpose
`defaultTools`	Built-in allowlist: `read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, `ls`; an empty array leaves only extension tools
`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 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

Guides

Configuration

Customization

Reference

Configuration locations

Complete example

Top-level fields

Models and thinking

Interface

Sessions and networking

Shell and commands

Projects and permissions

Section settings

MCP servers

Tool and resource arrays

TUI settings

Deprecated settings

Next steps

​Configuration locations

​Complete example

​Top-level fields

​Models and thinking

​Interface

​Sessions and networking

​Shell and commands

​Projects and permissions

​Section settings

​MCP servers

​Tool and resource arrays

​TUI settings

​Deprecated settings

​Next steps

Configuration locations

Complete example

Top-level fields

Models and thinking

Interface

Sessions and networking

Shell and commands

Projects and permissions

Section settings

MCP servers

Tool and resource arrays

TUI settings

Deprecated settings

Next steps