> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clideck.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> All CliDeck settings and how to configure them

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.

## Command-Line Flags

| Flag               | Description                  | Default                      |
| ------------------ | ---------------------------- | ---------------------------- |
| `--host <address>` | Network interface to bind to | `127.0.0.1` (localhost only) |

Use `--host 0.0.0.0` to make CliDeck accessible from other devices on your network (LAN, Wireguard, etc.), or `--host <ip>` to bind to a specific interface. Running `--host` without a value defaults to `0.0.0.0`.

## 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)                      |
| `autopilot/`         | Autopilot routing history, token usage, and debug logs |
| `custom-themes.json` | User-defined terminal themes (optional)                |

This directory is created automatically on first run. It's separate from the CliDeck installation, so your data is preserved when you update CliDeck.

### 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.

<Note>
  You don't need to edit `agent-presets.json`. It's managed by CliDeck and updated when you install new versions.
</Note>