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