Data paths

Step Code stores configuration, credentials, sessions, and logs under ~/.stepcode/ by default. Understand the directory layout before backing up or cleaning data.

Data root

System	Default path
macOS	`/Users/<username>/.stepcode`
Linux	`/home/<username>/.stepcode`
Windows	`C:\Users\<username>\.stepcode`

~ means your home directory. Agent configuration lives under ~/.stepcode/agent. .step-harness is retired and no longer written; startup only reads old credentials for a one-time migration.

Directory layout

~/.stepcode/
├── config.toml
├── auth.json
├── models.json
├── .credentials.json
├── device-id
├── models-store.json
├── bin/
├── logs/
├── marketplaces/
├── telemetry/
└── agent/
    ├── AGENTS.md
    ├── prompts/
    ├── skills/
    ├── agents/
    ├── themes/
    ├── extensions/
    ├── sessions/
    ├── trust.json
    ├── bin/
    ├── npm/
    └── git/

Some directories are created only when their feature is first used. bin/ contains the main program and runtime resources; agent/bin/ contains managed search tools.

Key files

File	Content
`config.toml`	Global settings and MCP server declarations
`auth.json`	API keys and OAuth credentials; key values support `!command` and `$VAR` resolution
`models.json`	Custom models and overrides, reloaded when `/model` opens
`.credentials.json`	MCP OAuth tokens, keyed by server name plus a vertical bar, written atomically
`models-store.json`	Model catalog cache
`agent/trust.json`	Project trust records

Restrict credential files to the current user. POSIX systems use 0600; check account-level file permissions on Windows. Do not commit or publicly upload the entire data directory.

Session data

Sessions live in agent/sessions/<encoded-working-directory>/, one JSONL file per session, containing messages, tool calls, outputs, and summaries. Use /session for the exact current path. Directory precedence is --session-dir > sessionDir in config.toml. Records contain id / parentId, with the current position as the active leaf. Compaction summaries, branch summaries, calls, and output share one file. ↑ / ↓ with empty input browses the current session’s submitted messages. See Sessions and context. Do not edit internal records directly.

Built-in tool cache

rg (ripgrep) and fd are downloaded on demand to ~/.stepcode/agent/bin/, as rg.exe / fd.exe on Windows. Lookup order is an injected custom path > a downloaded local copy > system PATH. Content search falls back from ripgrep to git grep inside Git repositories, then POSIX grep. It reports an error when none are available. Deleting the cache may trigger another download. On restricted networks, check system PATH and download access first.

Logs

logs/: runtime logs; start here for startup, connection, and tool errors.
telemetry/: telemetry buffers, separate from session records.

Logs can include error details and environment information. Review before sharing; do not assume they contain no sensitive data. Local storage does not prevent outbound data transfer. Model calls, MCP, plugins, and deployment access external services as needed.

Project data

Location	Content
`.stepcode/config.toml`	Project settings; requires trust
`.stepcode/cron/tasks.json`	Durable scheduled tasks
`.stepcode/workflows/runs/`	Workflow run records
`.stepcode/agents/`, `skills/`, `themes/`, `plugins/`	Project resources
`.stepcode/plans/`	Plan-mode session files
`.stepcode/npm/`	Project-scoped npm packages

Share configuration and resources according to team conventions. Exclude runtime records, caches, private paths, and credentials; do not add the entire .stepcode/ directory blindly.

Cleaning up data

Exit Step Code and back up required configuration and sessions first.

Goal	Action
Reset configuration	Back up and remove `config.toml`
Clear sessions	Remove unneeded contents of `agent/sessions/`
Clear logs	Delete old files in `logs/`
Redownload search tools	Remove the corresponding tool from `agent/bin/`
Sign out of a model platform	Use `/logout`
Clear MCP authorization	`step mcp logout <name>`
Clear telemetry buffers	Delete `telemetry/`; this does not disable telemetry
Refresh the model cache	Back up and remove `models-store.json`
Remove all data	Back up, delete Step Code’s dedicated data directory, and clean up the installer’s PATH entry

Deleting a project’s .stepcode/ also deletes its configuration, tasks, and custom resources. It is not just a cache.

Guides

Configuration

Customization

Reference

Data root

Directory layout

Key files

Session data

Built-in tool cache

Logs

Project data

Cleaning up data

Next steps

​Data root

​Directory layout

​Key files

​Session data

​Built-in tool cache

​Logs

​Project data

​Cleaning up data

​Next steps

Data root

Directory layout

Key files

Session data

Built-in tool cache

Logs

Project data

Cleaning up data

Next steps