Configuration

cc-deck installs with sensible defaults that work out of the box. This page covers how to customize keybindings, choose layout variants, and integrate with your terminal emulator.

Layout Variants

cc-deck ships with three layout variants that control what appears alongside the sidebar:

Variant Description

standard

Sidebar + tab-bar at top + status-bar at bottom. The most informative layout, recommended for users new to Zellij. This is the default.

minimal

Sidebar + compact-bar at bottom. Less visual clutter while still showing tab names.

clean

Sidebar only, no bars at all. Maximum terminal space. For experienced users who navigate entirely by keyboard.

All three variants are installed as separate layout files. The --layout flag during install sets which one becomes the default cc-deck.kdl:

cc-deck config plugin install --layout minimal

You can always try a different variant without changing the default:

zellij --layout cc-deck-standard
zellij --layout cc-deck-minimal
zellij --layout cc-deck-clean

Custom Keybindings

The three global shortcuts (Alt+s for navigation, Alt+a for attend, Alt+w for working) can be changed.

Using the Personal Layout

The recommended approach is to create a personal layout file that is never overwritten by cc-deck config plugin install:

  1. Copy the default layout:

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

  2. Edit the plugin configuration block to change the key bindings:

    plugin location="file:~/.config/zellij/plugins/cc_deck.wasm" {
    navigate_key "Super s"
    attend_key "Super n"
    working_key "Alt w"
}

  3. Set the personal layout as your default in ~/.config/zellij/config.kdl:

    default_layout "cc-deck-personal"

The personal layout is never modified by cc-deck config plugin install, so your custom keybindings are preserved across updates.

Ghostty Integration

If you use Ghostty as your terminal emulator, you can pass Cmd (Super) keys through to Zellij for a macOS-native feel.

In your Ghostty config, unbind the keys you want to pass through:

keybind = cmd+t=unbind
keybind = cmd+s=unbind
keybind = cmd+n=unbind

Then bind them in your Zellij config:

keybinds {
    shared {
        bind "Super t" { NewTab; }
    }
}

And configure cc-deck to use Super keys in your personal layout:

plugin location="file:~/.config/zellij/plugins/cc_deck.wasm" {
    navigate_key "Super s"
    attend_key "Super n"
    working_key "Alt w"
}

This gives you Cmd+S for navigation and Cmd+N for smart attend, matching the macOS convention of using Cmd for app-level shortcuts.

Session Timing

The plugin controls session lifecycle transitions through configurable timeouts. These determine how long a session stays in each state before advancing to the next.

The full lifecycle is:

Working ──[done_timeout]──> Done ──[done_timeout]──> Idle ──[auto_pause_secs]──> Paused

Configure these in the plugin block of your layout file:

plugin location="file:~/.config/zellij/plugins/cc_deck.wasm" {
    done_timeout "300"        // seconds before Working→Done and Done→Idle (default: 300)
    idle_fade_secs "3600"     // idle indicator fade duration in seconds (default: 3600)
    auto_pause_secs "3600"    // auto-pause after idle for this many seconds (default: 3600, 0 to disable)
    attend_cycle_ms "2000"    // rapid-cycle window for attend/working in ms (default: 2000, 0 to disable)
}
Key Default Description

done_timeout

300

Seconds of inactivity before a Working session transitions to Done (green checkmark), and again before Done transitions to Idle.

idle_fade_secs

3600

Duration in seconds over which the Idle indicator fades from light grey to dark grey, providing a visual sense of staleness.

auto_pause_secs

3600

Seconds an Idle session waits before auto-pausing. Paused sessions are excluded from attend cycling and hook processing. Set to 0 to disable auto-pause.

attend_cycle_ms

2000

When pressing Alt+a or Alt+w repeatedly within this window (in milliseconds), each press skips already-visited sessions. After the window expires, the next press resets to the most recent candidate. Set to 0 to disable rapid-cycle behavior.

Auto-paused sessions unpause automatically when you switch to them (via click, navigate, or attend).

Setting cc-deck as Default

To start Zellij with cc-deck automatically, add to ~/.config/zellij/config.kdl:

default_layout "cc-deck"

Then simply running zellij will start with the cc-deck sidebar.

Plugin Installation

The plugin is installed via the cc-deck CLI:

# Install with defaults (standard layout)
cc-deck config plugin install

# Install with minimal layout as default
cc-deck config plugin install --layout minimal

# Force overwrite without prompts
cc-deck config plugin install --force

# Check installation status
cc-deck config plugin status

# Remove the plugin, layouts, and hooks
cc-deck config plugin remove

When layout files have local changes, the installer shows a colored diff and offers three options: overwrite, skip, or backup and overwrite.