Skip to main content
Step Code saves sessions automatically and supports restoring, navigating branches, forking, and exporting. Compact context as it approaches the model’s window to retain important information and continue working.

​
Session storage

Sessions are grouped by working directory under ~/.stepcode/agent/sessions/. Each JSONL file is a tree whose records are linked by id and parentId.
Use --session-dir <directory> to override the location, or --no-session for a temporary session that is not saved. Session files use an internal format; do not edit them manually.

​
Starting and restoring sessions

​
Switching sessions in the TUI

Type to search in the session picker. Ctrl+S changes sorting, Ctrl+N filters named sessions, Ctrl+R renames, and Ctrl+D deletes. Confirm that you no longer need a record before deleting it.

​
Context compaction

Automatic compaction runs at safe points, such as after a tool batch, when context exceeds contextWindow - reserveTokens. You can also specify what to preserve manually:
Compaction retains approximately keepRecentTokens of recent messages and summarizes older content into eight structured sections, including goals, changed files, verified conclusions, and failed attempts. Subsequent requests contain system instructions, the summary, and retained messages. Also record important agreements and acceptance results in project files. Configure in config.toml:
enabled = false disables automatic compaction but leaves /compact available. Choose reserve and recent-message sizes appropriate for the model’s context window.

​
Session trees and forks

In /tree, navigate with arrow keys, select with Enter, cycle filters with Ctrl+O, and edit labels with Shift+L. Filters include default, no tools, user messages only, and labeled only. Selecting a user message can restore its text to the input box; edit and resend to form a branch. When switching branches, you can generate a summary of the branch you are leaving. Configure this under [branchSummary].
Session branches separate conversation records. They do not undo disk changes or create Git branches. Use Git branches or worktrees to isolate code experiments. Summaries and subsequent model calls may still consume tokens.

​
Exporting and sharing

You can also export from the command line:
/export [file] defaults to HTML; a .jsonl extension exports JSONL. /import <file> restores it as the current session. Exports can contain code, command output, and paths; review them before sharing.

​
Next steps