Configuration Reference

cc-deck uses XDG-compliant paths for configuration and data storage.

Config File

Location: $XDG_CONFIG_HOME/cc-deck/config.yaml (typically ~/.config/cc-deck/config.yaml)

The config file is optional. All settings have sensible defaults and can be overridden via CLI flags.

# Default namespace for Kubernetes commands
namespace: cc-deck

# Default credential profile
profile: default

# Verbose output
verbose: false

# Voice relay defaults
defaults:
  voice:
    threshold: 45    # VAD sensitivity (0-100, logarithmic)
    commands:         # Custom command words (optional)
      submit:
        - send
        - done
        - enter
      attend:
        - next

The defaults.voice.threshold setting controls how sensitive voice activity detection is. Lower values capture quieter speech but pick up more background noise. A value between 30 and 50 works well for most indoor environments. This value can be overridden per invocation with --threshold.

The defaults.voice.commands setting maps action names to trigger words. Two actions are available by default:

Action Default Word Description

submit

send

Sends a carriage return to the attended pane (same as pressing Enter)

attend

next

Cycles to the next session needing attention (same as Alt+a)

When the entire transcribed utterance, after stripping filler words, matches a trigger word, the corresponding action fires. Words embedded in longer sentences are treated as normal dictation.

When you set commands in the config, it replaces the defaults entirely. Each action can have multiple trigger words, and you can change the defaults to avoid conflicts with your natural speech patterns.

Environment Variables

Variable Description

XDG_CONFIG_HOME

Base directory for config files. Default: ~/.config

XDG_DATA_HOME

Base directory for data files. Default: ~/.local/share

XDG_CACHE_HOME

Base directory for cache files. Default: ~/.cache

KUBECONFIG

Path to kubeconfig file. Default: ~/.kube/config

ZELLIJ_CONFIG_DIR

Zellij configuration directory. Default: ~/.config/zellij

File Locations

Path Purpose

~/.config/cc-deck/config.yaml

CLI configuration

~/.config/zellij/plugins/cc_deck.wasm

Sidebar plugin binary

~/.config/zellij/layouts/cc-deck.kdl

Default layout (symlink to chosen variant)

~/.config/zellij/layouts/cc-deck-standard.kdl

Standard layout variant

~/.config/zellij/layouts/cc-deck-minimal.kdl

Minimal layout variant

~/.config/zellij/layouts/cc-deck-clean.kdl

Clean layout variant

~/.config/zellij/layouts/cc-deck-personal.kdl

Personal layout (never overwritten by install)

~/.claude/settings.json

Claude Code settings (hooks registered here)

~/.config/cc-deck/domains.yaml

User-defined domain groups for network filtering

~/.config/cc-deck/sessions/

Snapshot storage

~/.cache/cc-deck/models/

Whisper model files for voice relay

~/.local/state/cc-deck/voice.log

Voice relay diagnostic log (created with --verbose)

/tmp/cc-deck-pane-map.json

Hook pane ID cache (ephemeral)

Plugin Configuration

Plugin settings are specified in the layout file’s plugin block:

plugin location="file:~/.config/zellij/plugins/cc_deck.wasm" {
    navigate_key "Alt s"      // Key to toggle navigation mode
    attend_key "Alt a"        // Key for smart attend
    voice_key "Alt m"         // Key for voice mute toggle
}
Setting Default Description

navigate_key

Alt s

Global shortcut for navigation mode

attend_key

Alt a

Global shortcut for smart attend

voice_key

Alt m

Global shortcut for voice mute toggle

Key format follows Zellij conventions: Alt, Ctrl, Super (Cmd on macOS) as modifiers, followed by the key name.

Domain Groups Configuration

Location: $XDG_CONFIG_HOME/cc-deck/domains.yaml (typically ~/.config/cc-deck/domains.yaml)

This file defines custom domain groups for network filtering in containerized sessions. Create it with cc-deck config domains init to get a commented template, or write it manually.

The file is a YAML mapping where each top-level key is a group name and the value defines its domains and resolution behavior.

Custom Groups

Define a new group with a domains list:

internal-registry:
  domains:
    - registry.internal.corp
    - artifacts.internal.corp

Extending Built-in Groups

Use extends: builtin to merge additional domains with a built-in group of the same name. The user-defined domains are appended to the built-in domains rather than replacing them.

python:
  extends: builtin
  domains:
    - pypi.internal.corp

This produces a python group containing all built-in Python domains plus pypi.internal.corp. Without extends: builtin, the user-defined group replaces the built-in group entirely.

Including Other Groups

Use includes to compose a group from other groups. Included groups are resolved recursively.

dev-stack:
  includes:
    - python
    - golang
    - github
  domains:
    - artifacts.internal.corp

This produces a group containing all domains from python, golang, and github, plus the literal domain artifacts.internal.corp.

Resolution Rules

  • Groups defined in domains.yaml take precedence over built-in groups of the same name.

  • If extends: builtin is set, the built-in domains are included as a base.

  • Circular includes are detected and reported as errors.

  • Source labels in cc-deck config domains list reflect the resolution: builtin, user (override or new), or extended (extends builtin).