Data Storage and Migration

Data Storage and Migration

Every persistent file ClusterSpace writes, where it lives, what's in it, and how the fleet-term → clusterspace rename migration runs.

---

Where data lives

<userData>/clusterspace-data/
├── *.json                          # electron-store state files (see below)
├── config/
│   ├── personas/<id>.md            # user-authored personas (overrides defaults)
│   ├── skills/<id>.md              # user-authored skills
│   ├── tasks/<category>/<id>.md    # user-authored task templates
│   └── tools/<name>.js             # user plugin tools (hot-reload)
└── browser-screenshots/            # vision tool screenshots (auto-cleanup roadmap)

<userData> paths:

• Windows: %APPDATA%\ClusterSpace\
• macOS: ~/Library/Application Support/ClusterSpace/
• Linux: ~/.config/ClusterSpace/

---

State files (electron-store JSON)

All written by electron-store. JSON only — no binary blobs, no DB.

File	Owner	Contents
clusterspace-workspaces.json	workspace-store.ts	Array of workspaces. Each has grid config, pane list, settings
clusterspace-settings.json	workspace-store.ts	Global app settings + active workspace ID + window bounds reference
clusterspace-window-state.json	workspace-store.ts	Window x/y/width/height + maximized flag
clusterspace-ssh-servers.json	credentials-store.ts	SSH server list (passwords safeStorage-encrypted)
clusterspace-ai-providers.json	ai-store.ts	AI provider configs (API keys safeStorage-encrypted)
clusterspace-ai-memory.json	ai-memory-store.ts	Conversations (per provider × workspace × pane, max 50, max 100 msgs each)
clusterspace-agents.json	agent-store.ts	Per-pane agent state
clusterspace-goals.json	goal-store.ts	Goal checkpoints (max 50, in-flight always kept)
clusterspace-orchestration.json	orchestration-store.ts	Multi-pane orchestration goals + event log (last 500)
clusterspace-browser-pane-state.json	browser-store.ts	Browser tabs, bookmarks, history, downloads, find-in-page
clusterspace-browser-credentials.json	browser-credentials-store.ts	Saved logins (passwords safeStorage-encrypted)
clusterspace-recipes.json	browser-recipes.ts	Saved browser recipes

Each is independent — corrupt one and the others still load. Default values fill in if a file is missing.

---

Encryption

Three classes of secret material:

Secret	Where	Encryption
SSH passwords	clusterspace-ssh-servers.json	safeStorage (OS keychain), base64 fallback with warning
AI provider API keys	clusterspace-ai-providers.json	safeStorage
Browser saved logins	clusterspace-browser-credentials.json	safeStorage

Conversation history, bookmarks, history, goal logs, agent state — not encrypted. Treat the userData dir as sensitive even though only the keychained values are encrypted.

---

Capacity caps

Store	Cap	Trim policy
AI conversations	50 × 100 msgs	Oldest first; current always kept
Goal log	50 goals	Finished oldest dropped first; in-flight always kept
Goal step log	500 steps per goal	head 50 + tail 450 (middle dropped)
Orchestration events	500	Oldest first
Browser action log	500 (in-memory ring)	Oldest first; not persisted
Browser history	500 entries	Oldest first

These are constants in the respective store files; edit and rebuild to change.

---

Fleet Term → ClusterSpace rename migration

The app was originally Fleet Term. On the first launch after the rename, src/main/legacy-rename.ts runs a one-time migration:

1. Check for <userData>/fleet-term-data/ (the legacy directory)
2. If found and <userData>/clusterspace-data/ doesn't exist:
   • Copy the entire directory tree to clusterspace-data/
   • Rename fleet-term-*.json files to clusterspace-*.json (in place inside the new dir)
   • Do not delete the legacy dir — keep it as a backup
3. If clusterspace-data/ already exists, skip (avoid overwriting user data)

User-authored config files (personas, skills, tasks, tools) under config/ are copied as-is; their names don't include the app name.

Caveat: remote tmux sessions

The rename does not touch tmux sessions on remote hosts. Sessions named fleet-term-pane-<short> continue to exist on remote hosts; ClusterSpace creates new sessions with clusterspace-pane-<short> names. The SSH-and-tmux surfaces a "Legacy suggestion" chip to recover old sessions one-click.

To migrate a remote session name yourself:

ssh user@host tmux rename-session -t fleet-term-pane-abc clusterspace-pane-abc

---

Backups

Recommended backup scope:

Priority	Path	Why
Critical	<userData>/clusterspace-data/ (whole dir)	Workspaces, providers, agents, goals, all secrets
Critical	<userData>/clusterspace-data/config/	Your custom personas / skills / templates / plugins
Optional	<userData>/clusterspace-data/browser-screenshots/	Vision tool outputs; usually not worth backing up
Don't bother	dist/, node_modules/, the app installer	Reproducible from source

⚠ Encryption portability: safeStorage-encrypted blobs are tied to your OS user's keychain key. If you restore the userData dir on a different machine or user, encrypted fields (SSH passwords, API keys, saved logins) won't decrypt. You'll need to re-enter them manually.

---

Wiping data

To start fresh:

# Quit ClusterSpace first.

# Linux/macOS
rm -rf ~/.config/ClusterSpace/clusterspace-data/      # Linux
rm -rf "~/Library/Application Support/ClusterSpace/clusterspace-data/"  # macOS

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:APPDATA\ClusterSpace\clusterspace-data\"

Launching ClusterSpace again recreates everything at defaults.

To wipe specific subsets:

# Just AI providers (re-add them)
rm clusterspace-ai-providers.json

# Just conversation history
rm clusterspace-ai-memory.json

# Just goal log
rm clusterspace-goals.json

# Just browser saved logins
rm clusterspace-browser-credentials.json

ClusterSpace silently regenerates each on next launch.

---

Inspecting a state file

All state files are plain JSON. Open in any editor:

cat ~/.config/ClusterSpace/clusterspace-data/clusterspace-workspaces.json | jq .

Encrypted fields look like base64 blobs (e.g., "apiKey": "AQAAAAA..."). The non-encrypted JSON structure around them is browsable.

⚠ Don't hand-edit while the app is running — electron-store caches values in memory; your edits will be overwritten on next save. Quit first, edit, relaunch.

---

See also

• Saved-Logins — browser credential storage in detail
• AI-Providers — API key storage
• SSH-and-tmux — SSH server passwords
• Architecture-Overview — which class owns which file
• Troubleshooting — when state files get corrupted