CliDeck is configured through the Settings panel in the UI. Settings are stored in ~/.clideck/config.json.
You rarely need to edit config.json directly — the Settings UI covers everything. This page documents all available options for reference.
General Settings
| Setting | Description | Default |
|---|
| Default working directory | Starting directory for new sessions | ~/Documents |
| Confirm before closing | Show a confirmation dialog when closing sessions | Enabled |
CLI Agent Settings
Each agent in the command list has these properties:
| Property | Description |
|---|
| Label | Display name in the session launcher |
| Command | CLI command to run (e.g., claude, codex, gemini) |
| Enabled | Whether the agent appears in the session launcher |
| Icon | Agent icon (from presets or custom) |
| AI Agent | Whether this is an AI agent (enables resume features) |
| Supports resume | Whether session resume is available |
| Resume command | Command template with {{sessionId}} placeholder |
| CliDeck integration | Enable/disable live status and resume for this agent |
Notification Settings
| Setting | Description | Default |
|---|
| Notify when agent finishes | Enable idle transition notifications | Enabled |
| Play sound | Play a sound on notification | Enabled |
| Notification sound | Which sound to play | Default Beep |
| Minimum working time | How long an agent must work before notifying | 10 seconds |
Appearance Settings
| Setting | Description | Default |
|---|
| Default theme | Terminal color theme for new sessions | Catppuccin Mocha |
| Color mode | Light or dark UI mode | Dark |
Projects
Projects are stored in the config as an array:
| Property | Description |
|---|
| id | Unique identifier (UUID) |
| name | Project display name |
| path | Default working directory for the project |
| color | Accent color (one of 8 preset colors) |
Data Directory
All CliDeck data lives in ~/.clideck/:
| File | Purpose |
|---|
config.json | Your settings and agent configuration |
sessions.json | Saved sessions for resume (written on shutdown) |
transcripts/ | Per-session transcript files for search |
plugins/ | Plugin folders (bundled + custom) |
custom-themes.json | User-defined terminal themes (optional) |
Migrations
CliDeck automatically migrates your config when the format changes between versions. Old settings are preserved — you won’t lose your configuration when updating.
Agent Presets
Built-in agent definitions are stored in agent-presets.json. These provide defaults for each supported agent (command, icon, resume command, telemetry settings, etc.). When CliDeck loads, it syncs your configured agents with the latest preset data — ensuring you always get updated icons, resume commands, and telemetry configurations.
You don’t need to edit agent-presets.json. It’s managed by CliDeck and updated when you install new versions.
