cockpit

name

cockpit

description

This skill should be used when managing the Kitty terminal cockpit session, controlling terminal panes and tabs, sending commands to specific panes, checking teammate status, launching or restarting the cockpit session, managing the Helm tab for multi-cell strategic views, or performing any terminal window management. Activate for "launch cockpit", "send to pane", "focus tab", "teammate status", "list panes", "manage windows", "terminal layout", "helm tab", "cell topology", "cell status" requests.

When to Use This Skill

• Launching or restarting the cockpit session
• Sending text/commands to specific kitty windows
• Switching focus between tabs or windows
• Querying the state of kitty windows/tabs
• Spawning agent panes in the Cockpit tab

Kitty Remote Control

Kitty remote control is the sole terminal control plane — there is no tmux. All commands go through the kitty socket, which is unique per instance. Always use the environment variable:

kitty @ --to "$KITTY_LISTEN_ON" <command>

If $KITTY_LISTEN_ON is not set, find the socket for this instance:

ls /tmp/kitty-kommander-*

List all windows and tabs

kitty @ --to "$KITTY_LISTEN_ON" ls

Returns JSON with all OS windows, tabs, and their windows.

Send text to a specific window

# By title match
kitty @ --to "$KITTY_LISTEN_ON" send-text --match "title:Events" "echo hello\n"

# By tab title
kitty @ --to "$KITTY_LISTEN_ON" send-text --match "title:Cockpit" "ls -la\n"

Focus a tab

# By index (0-based)
kitty @ --to "$KITTY_LISTEN_ON" focus-tab --match "index:0"

# By title
kitty @ --to "$KITTY_LISTEN_ON" focus-tab --match "title:Notebooks"

Set tab/window title

kitty @ --to "$KITTY_LISTEN_ON" set-tab-title --match "index:0" "Lead Agent"

Create new window in current tab

kitty @ --to "$KITTY_LISTEN_ON" launch --type=window --title "Monitor" htop

Agent Pane Management

The cell-leader spawns one kitty window per teammate into the Cockpit tab.

Spawn an agent window in the Cockpit tab

kitty @ --to "$KITTY_LISTEN_ON" launch --type=window \
  --tab-match title:Cockpit --title "builder"

Repeat per agent name. The --title doubles as a stable identifier for later send-text / focus-window / close-window commands against that agent's pane.

A batched kommander pane <name1> <name2> ... command is planned — see kitty-kommander-dh3 (cell-lifecycle). Until that ships, use the kitty @ launch invocation above.

List all agent windows in the Cockpit tab

kitty @ --to "$KITTY_LISTEN_ON" ls | \
  python3 -c "import json,sys; [print(w['title']) for osw in json.load(sys.stdin) for t in osw['tabs'] if t['title']=='Cockpit' for w in t['windows']]"

Send a command to an agent's pane

kitty @ --to "$KITTY_LISTEN_ON" send-text --match "title:builder" "echo status update\n"

Close an agent's pane

kitty @ --to "$KITTY_LISTEN_ON" close-window --match "title:builder"

Cockpit Session Lifecycle

Launch cockpit

kommander launch /path/to/project

Reads config/kommander.cue, derives the instance slug + socket path, and execs kitty with the declared tabs.

Check cockpit health

# Structural: kommander diffs CUE desired state against actual kitty state
kommander doctor

# Direct: kitty responding to remote control?
kitty @ --to "$KITTY_LISTEN_ON" ls > /dev/null 2>&1 && echo "kitty: ok" || echo "kitty: no socket"

Reconcile drift

kommander reload

Spawns missing windows, kills stale ones, restarts changed ones — all per CUE.

Tab Layout Reference

Index	Name	Purpose
0	Cockpit	Agent Teams canvas — kitty windows per teammate
1	Driver	Claude Code cell-leader session
2	Notebooks	euporie notebook editor
3	Dashboard	kommander-ui --sidebar Ink app
4	Graph	kommander-ui --dag Ink app (dependency DAG rendered via graphviz + kitty graphics protocol)

Helm Tab — Multi-Cell Strategic View (planned)

The Helm tab will appear when sub-cells deploy, providing the strategic inter-cell overview. Cell-lifecycle commands (kommander cell-spawn, kommander cell-teardown, kommander pane) and the Helm Ink apps (kommander-ui --helm-topology, kommander-ui --helm-status) are planned — see kitty-kommander-dh3 for the shipping bead. Single-cell operators never see it.

Data sources once it ships:

• bd federation list-peers --format=json — cell topology
• bd gate check --format=json — cross-cell blockers
• bd stats --format=json (per cell) — cell health summaries

Guidelines

• Always use $KITTY_LISTEN_ON for the kitty socket path — never hardcode
• The --match flag uses kitty's matching syntax: title:, index:, id:, env:
• When sending text, always append \n to execute the command
• Title agent windows with the teammate's name so later --match "title:<name>" works
• Multiple kitty-kommander instances can run in parallel (one per project directory), each with its own KITTY_LISTEN_ON socket