Settings and Configuration

Settings and Configuration

Two layers: the in-app Settings dialog (cosmetic / behavioral), and on-disk config files under <userData>/clusterspace-data/config/ (personas, skills, task templates, plugin tools).

---

Settings dialog

Open via:

• Status bar → gear icon
• Command palette → "settings"

Sections:

General

• App name — display only
• Confirm on close — show a dialog before exiting if there are unsaved workspaces
• Global bypass mode — toggles every approval gate at once (advanced; intended for automation rigs)

Appearance

• Theme (dark / light — currently dark-only, light is roadmap)
• Font family / size for terminals
• Cursor style and blink rate

Terminal

• Default shell command per OS
• Scrollback line count
• Bracketed-paste enabled (default ON)
• Terminal theme (foreground, background, ANSI palette)

Browser

• Default search engine
• Default user-agent override
• Clear browsing history / bookmarks

AI

• Active provider
• Discover providers (probe common ports)
• Per-provider config: endpoint, model, vision model, API key, temperature, max tokens, system prompt
• See AI-Providers for the deep dive

Workspaces

• Export current workspace as <name>.clusterspace.json
• Import a .clusterspace.json file as a new workspace

---

On-disk config

ClusterSpace reads user-authored config from:

<userData>/clusterspace-data/config/
├── personas/       # YAML-frontmatter markdown — see [[Writing-Personas]]
├── skills/         # Reference docs personas point to — see [[Skills]]
├── tasks/          # Task templates — see [[Writing-Task-Templates]]
└── tools/          # Plugin tools — see [[Plugin-Authoring]]

User files override the bundled defaults (resources/defaults/) with the same name. So to customize the builder persona, drop <userData>/clusterspace-data/config/personas/builder.md and edit it. Restart isn't required for tools (hot-reload via fs.watch); personas/skills/tasks are loaded on app launch.

<userData> paths

OS	Path
Windows	%APPDATA%\ClusterSpace\
macOS	~/Library/Application Support/ClusterSpace/
Linux	~/.config/ClusterSpace/

---

State files (electron-store)

Separate from config; these are runtime state ClusterSpace writes itself. Don't hand-edit unless you know what you're doing.

File	Contents
clusterspace-workspaces.json	Workspaces + grid + pane layouts
clusterspace-settings.json	Global app settings
clusterspace-window-state.json	Window bounds + maximized state
clusterspace-ssh-servers.json	SSH servers (passwords encrypted)
clusterspace-ai-providers.json	AI provider configs (API keys encrypted)
clusterspace-ai-memory.json	Conversation history
clusterspace-agents.json	Per-pane agent state
clusterspace-goals.json	Goal log (50-goal cap)
clusterspace-orchestration.json	Multi-pane orchestration goals + events
clusterspace-browser-pane-state.json	Browser tabs/bookmarks/history/downloads
clusterspace-browser-credentials.json	Saved logins (passwords encrypted)
clusterspace-recipes.json	Saved browser recipes

Full reference: Data-Storage-and-Migration.

---

Workspace export / import

Exported workspace JSON contains:

• Grid configuration
• Pane configurations (type, label, position, template references)
• (Optional) saved SSH server references (by name — not credentials)

Not exported:

• Running PTY state
• Browser cookies / saved logins
• Conversation history
• API keys
• Anything secret

Share .clusterspace.json files freely; they're safe.

---

Bypass mode

A global kill-switch for every approval gate (browser approval modal, goal policy prompts, etc.). Useful when running ClusterSpace headless in an automation rig.

Toggle from the status bar (right side) or Settings → General → Global bypass. The status bar shows a red border around the bypass chip when ON to remind you that prompts are suppressed.

⚠ With bypass on, the AI can submit forms, upload files, type passwords, and execute beyond the goal's risk ceiling without asking. Don't leave it on by accident.

---

See also

• AI-Providers — configure an LLM provider
• Writing-Personas — author a custom persona
• Data-Storage-and-Migration — every electron-store file
• Plugin-Authoring — drop a custom tool into config/tools/