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 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

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 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 for provider setup and model selection.

​

Interface

Field	Default	Description
theme	step-blue	Theme name; see Custom themes 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:

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 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 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 for project resource loading and tool approval.

​

Section settings

[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 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 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 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:

[telemetry]
enabled = false

This setting controls telemetry. Model requests, MCP calls, and manual feedback are managed separately. See Permissions and safety for data handling and sharing.