Kitty

Experimental

The kitty backend is new and experimental. Expect rough edges and potential issues.

kitty can be used as an alternative to tmux. Detected automatically via $KITTY_WINDOW_ID.

Differences from tmux

Feature	tmux	kitty
Agent status in tabs	Yes (window names)	Yes (custom tab title)
Tab ordering	Insert after current	Appends to end
Scope	tmux session	OS window

• Tab ordering: New tabs appear at the end of the tab bar (no "insert after" support like tmux)
• OS window isolation: workmux operates within the current OS window. Tabs in other OS windows are not affected.
• Terminology note: What workmux calls a "pane" is called a "window" in kitty, and what workmux calls a "window" (tab) is called a "tab" in kitty

Requirements

• kitty with remote control enabled (kitten @ must work)
• Unix-like OS (named pipes for handshakes)
• Windows is not supported
• Required kitty configuration (see below)

Required kitty configuration

workmux relies on kitty's remote control API. Add these settings to your kitty.conf:

# REQUIRED: Enable remote control
allow_remote_control yes

# REQUIRED: Set up socket for remote control
# The socket path can be customized, but using kitty_pid ensures uniqueness
listen_on unix:/tmp/kitty-{kitty_pid}

# RECOMMENDED: Enable splits layout for pane splitting
enabled_layouts splits,stack

Agent status display

workmux stores agent status in kitty user variables (workmux_status), which can be displayed in tab titles using kitty's {custom} template placeholder.

Agent setup

Copy this page as markdown and paste it to your coding agent to have it set up the configuration files for you.

Setup

1. Create ~/.config/kitty/tab_bar.py:

from kitty.fast_data_types import get_boss

def draw_title(data):
    tab = get_boss().tab_for_id(data['tab'].tab_id)
    if tab:
        for window in tab:
            status = window.user_vars.get('workmux_status', '')
            if status:
                return ' ' + status
    return ''

2. Create ~/.config/kitty/workmux_watcher.py for live status updates and auto-clear on focus:

from kitty.boss import Boss
from kitty.window import Window


def on_focus_change(boss: Boss, window: Window, data: dict) -> None:
    if not data.get('focused'):
        return
    if window.user_vars.get('workmux_auto_clear') == '1':
        boss.call_remote_control(window, (
            'set-user-vars', f'--match=id:{window.id}',
            'workmux_status=', 'workmux_auto_clear=',
        ))


def on_set_user_var(boss: Boss, window: Window, data: dict) -> None:
    if data.get('key') == 'workmux_status':
        tm = boss.os_window_map.get(window.os_window_id)
        if tm is not None:
            tm.update_tab_bar_data()
            tm.mark_tab_bar_dirty()

3. Add to your kitty.conf:

tab_title_template "{title}{custom}"
watcher workmux_watcher.py

The {custom} placeholder calls the draw_title function, which checks each window in the tab for a workmux_status user variable and appends it to the title. The watcher refreshes the tab bar when status changes and auto-clears "waiting" and "done" statuses when the tab receives focus.

Known limitations

• Windows is not supported (requires Unix-specific features)
• Agent status icons require a small config change (see above)
• Cross-OS-window operations are not supported
• Some edge cases may not be as thoroughly tested as the tmux backend
• Tab insertion ordering is not supported (new tabs always appear at the end)