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. User directories add ~/.claude/skills and ~/.stepcode/skills; project directories add .claude/skills within the trusted scan scope. Claude directories are discovered automatically and do not need to be repeated in the skills array; non-default directories such as ~/.codex/skills still require explicit configuration.

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
`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. See Configuration files for setting details.

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. Use --session-dir to select a directory; sessionDir and environment variables can also configure defaults. Check /session for the effective path. Records contain id / parentId, with the current position as the active leaf. Compaction summaries, branch summaries, calls, and output share one file. CLM maintains a working copy (mirror-*/LIVE_CONTEXT.md) and archive (archive/) under live-context/<session-ID>/ in the session directory. Without a session file it writes to a temporary directory. These are not the same files as the original session JSONL. Check related session data when backing up or cleaning, and do not treat the entire archive as short-term cache. 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 them before sharing. Model calls, MCP, plugins, and deployment access external services as needed. See Configuration files for telemetry, and Environment variables for proxies and directory overrides.

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 files; `STEP_CODING_AGENT_PLAN_DIR` selects another directory, with relative paths resolved from the working directory; existing sessions keep their saved plan paths and are not migrated automatically
`.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

Deleting a project’s .stepcode/ also deletes its configuration, tasks, and custom resources.

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

Get started

Guides

Configuration

Customization

Reference

Support and updates

Data root

Directory layout

Key files

Session data

Built-in tool cache

Logs

Project data

Cleaning up data

​Data root

​Directory layout

​Key files

​Session data

​Built-in tool cache

​Logs

​Project data

​Cleaning up data

Data root

Directory layout

Key files

Session data

Built-in tool cache

Logs

Project data

Cleaning up data