Resetting settings and state

If Solo is behaving unexpectedly, you don't need to nuke everything. Start by resetting only the part that's likely broken.

Reset hotkeys only#

1. Open Settings > Hotkeys.
2. Click Reset all to defaults.
3. In the Reset all shortcuts? dialog, click Reset all.

That's all you need if only your key bindings are messed up.

Reset all core app data#

Solo's core app-data directory defaults to:

~/.config/soloterm/

If SOLOTERM_APP_DATA_DIR is set, that override is used instead. Only one copy of Solo can use a data directory at a time (see Solo won't start because another copy is running). This core directory contains the primary solo.db database plus agent-channels.db, which stores scratchpads, todos, comments, coordination records, and related agent-channel state.

To fully reset core state:

1. Quit Solo completely.
2. Move the directory aside so you have a backup:

mv ~/.config/soloterm ~/.config/soloterm.backup

3. Launch Solo again. It creates fresh core databases.

This resets projects, command records, trust state, agent-channel state, and other data in that core directory.

Solo won't start because another copy is running#

If Solo shows Solo cannot start because another Solo runtime owns this data directory, another copy of Solo is already using the same app-data directory. This can happen if you launch the AppImage or installer build twice, or run two different builds side by side.

Close the other Solo process and launch again. To run two copies at once, give the second one its own data directory with SOLOTERM_APP_DATA_DIR.

Reset window placement files#

Solo does not currently expose a supported built-in window reset, and window state is not all stored in the core directory above:

• Solo's window-state layer resolves its state file through the platform-managed application-config directory for bundle identifier com.soloterm.solo.
• .display-snapshot.json resolves through the platform-managed application-data directory for the same bundle. Separate startup compatibility code also looks for .window-state.json in that application-data scope.
• Main and workspace-window position and size are stored in the workspace_window_groups setting in solo.db.

Do not treat ~/.config/soloterm/.window-state.json and ~/.config/soloterm/.display-snapshot.json as a standalone window reset. Deleting auxiliary JSON files does not reset main/workspace geometry. With the source-backed procedures documented here, resetting that geometry requires the full core-state reset above, which resets all solo.db state; move the directory aside first.

Reset only the primary database#

To isolate the primary database without moving the full core directory:

mv ~/.config/soloterm/solo.db ~/.config/soloterm/solo.db.backup

Then relaunch Solo. This isolates solo.db only; it does not replace agent-channels.db, browser-persisted UI preferences, or platform window-state files. If Solo starts, the previous primary database was likely damaged.

Notes#

• There aren't any built-in command-palette actions today for full reset or window reset.
• UI-only preferences such as theme, sidebar widths, and terminal font settings are persisted in browser storage under solo-ui-storage, so deleting only solo.db isn't always a full visual reset.