Peek, deck and panel

With a dozen tabs open you often want to know one thing about one of them: is the agent stuck, which branch is this, what is on its screen. kittymux gives you three ways to look without leaving the tab you are in.

Peek cardCopy Anchor Link

The peek card is a small overlay over your active pane. It answers "what is going on in that tab" in one glance.

Open it. Right-click a tab in the vertical bar, or press ctrl+alt+shift+q for a quick look at the agent that has waited on you longest.

It shows the tab's state and, for an agent that needs you, the question it is asking, the branch and folder, each pane of the tab, and the tail of the screen. It refreshes about once a second while it is open.

Selecting a pane changes its preview. The card moves focus only when you press ⏎. It reads the same state as the bar, so the two never disagree.

You can also open it by hand for a tab id from kitty @ ls:

kitten ~/kittymux/python/peek-kit.py 12

Quick look from the keyboardCopy Anchor Link

Press ctrl+alt+shift+q. The card opens over the pane you are in, about the agent in this kitty that has waited on you longest: the same order as kittymux pick and ctrl+alt+y. Read its question, then press ⏎ to go there or esc to stay where you are. Press the chord again to close the card. If nothing in this kitty needs you, it opens nothing and shows a short desktop notification.

For any other tab, run kittymux peek from a shell:

kittymux peek                # the tab of this pane
kittymux peek 12             # tab id 12 of this kitty (see kitty @ ls)
kittymux peek --waiting      # the agent that has waited longest, what the chord runs

The card can only show windows of the kitty it runs in, so --waiting looks at this kitty only. Use kittymux pick to find an agent in another kitty.

To look at a tab by choosing it from a list, open the deck instead. It previews whatever you select.

DeckCopy Anchor Link

Press ctrl+alt+b. The deck lists every tab across every session, grouped, each with its state, the agent's own message (such as "Approve: rm -rf node_modules?"), the pull request number and listening ports. A split tab lists each agent pane as an indented child line. The selection gets a live preview of its screen, beside the list in a wide deck and in a drawer under it in a narrow one.

a uses the same shape-keeping mover as join, run from the selected tab. t is the keyboard twin of dragging a pane's title bar onto the bar.

Docked panelCopy Anchor Link

Press ctrl+alt+shift+b. The deck becomes a persistent column: the compositor reserves its width, so tiled windows sit beside it. It stays open after a jump and uses about one percent of a CPU when idle. Press the chord again to remove it.

• Keys work as in the deck, except that esc does not close it. Press q to quit the panel.
• Summoned, then docked. Opening the panel with its chord (or kittymux panel summon) takes the keyboard at once, so j, k, / and the rest work without a click. esc, q, a jump, kittymux panel dock, or 12 seconds without a key hands the keyboard back; the panel stays on screen and takes keys again after a click or the next summon. While it is summoned, the chord removes it. The 30-second limit exists so a forgotten summon can never swallow your typing.
• Hover previews a tab or pane in a drawer under the list.
• Drag the panel's inner edge to resize it. The pointer turns into a resize cursor there, and the width is remembered.

Open it from anywhereCopy Anchor Link

The chords above work inside kitty. To open the panel from any app, bind kittymux panel toggle in your window manager. On Hyprland, with Super and N:

bind = SUPER, N, exec, kittymux panel toggle

# optional: slide in from the screen edge instead of the compositor's default layer animation
layerrule {
    name = kittymux-panel-slide
    match:namespace = kittymux-panel
    animation = slide left
}

Use slide right if you moved the panel with KITTYMUX_PANEL_EDGE=right. The panel's layer name is kittymux-panel, so the rule touches nothing else. The speed comes from your own layers animation line. The slide is the compositor's, not kittymux's: kittymux draws no animation of its own when the panel opens or closes, because a toggle you press many times a day should be instant. Check that your chord is free with hyprctl binds.

The panel needs wlr-layer-shell, so it works on Hyprland, and should on sway, river and niri. It is not available on GNOME or on X11. Its placement beside the bar is verified by hand on Hyprland only. See Platforms and compatibility.

Where is this pane?Copy Anchor Link

Separate from the cards above, ctrl+alt+i shows a small pill with the current folder and branch. Press it twice, or press ctrl+alt+shift+i, for a detail card that lets you copy the path or the branch.

Choosing between themCopy Anchor Link

• You are in the middle of something and want one fact about one tab: peek.
• You are hunting across many tabs, or want to act on one by keyboard: deck.
• You want agent states always in view on a wide screen: panel.
• You want a list that sorts by what needs you, from anywhere on the desktop: kittymux pick.

The panel's three viewsCopy Anchor Link

The panel has three views. A strip of three pills at the top switches between them: Agents, Usage (a dial) and Inbox (an envelope, with a count when something is unread). Click a pill, or press a, u or i. The picked pill carries its name and the others show an icon, so the strip stays one short row. esc returns to Agents. q or the global toggle closes the panel, so bind kittymux panel toggle to a key in your window manager to reach it from any app.

AgentsCopy Anchor Link

The list you look at most is built to stay calm until something needs you.

• A tab is called by what it is about. The agent's own conversation title when it has a real one, cleaned up (no markdown, no quotes, no trailing full stop, and no | folder that an agent appended when it is exactly the tab's own project) and cut at a word, not in the middle of one. When an agent has no title of its own (it shows only its product name, "Claude Code") or has set a sentence of its reply as the title ("I can't do that. I don't have access…"), the tab is called by its project instead, the repo or folder it is in. The text you type into a tab name is never touched. kittymux features off titles turns this off and shows the raw title again. The / search still matches the raw title.
• One bright thing per row: the title. A state is a mark at the right edge (a spinner, !, ⊘, ✓), not a sentence.
• What needs you is findable without reading. A row that is asking for you has a stripe on its left edge, a faint warm tint across it, and how long it has waited (needs you 4m; when the panel is narrow the words shorten to needs 4m, then 4m, before they take room from the branch). A tab at its limit is tinted red and says limit hit 1h. A finished run says done 3m in a quiet tone.
• Detail appears where you point. The branch (or folder) is always there. The pull request and listening ports show on the picked or hovered row, in a neutral tone: a PR number never wears a state colour.
• A split tab starts closed. Its context line shows ▸ 3 panes. Click the ▸ (or press → or o on the picked row) to list its panes under it, and ▾ / ← / o to close them again. The tab you are in is open the first time the panel draws. Hovering never opens a tab, and an agent starting to ask in a closed split does not either: the list never moves under your pointer by itself.
• Sessions. With only unnamed tabs there is no header. Next to a named session they are grouped under OTHER TABS. A header shows how many of its tabs ask for you (! 2) and how many tabs it has.
• Buttons look like buttons. Under the list a row of keycaps does what its key does when you click it: ⏎ jump, / find, a join, t detach. The one under the pointer lights up in your accent colour. A narrow panel drops buttons from the right, so the most useful stay. A ? keycap at the right edge of every footer opens a card with the keys of the view you are in, inside the panel; any key or click closes it.
• Empty states say why. No tabs yet, or no tab matching your search (and esc clears the search).

Every view has the same kind of button row at the bottom: Usage has r refresh and d details, Inbox has ⏎ jump, x dismiss and tab filter. Greyed-out hints such as j k move are labels, not buttons.

The preview drawer under the list shows the last lines of the hovered tab's screen without the terminal chrome around them: no blank lines, box borders or hint footers such as "? for shortcuts".

UsageCopy Anchor Link

A row of tiles, one per provider. Each tile shows the provider's logo and its worst share of a limit, or a dot when it has no limit to measure. The tile you pick opens as a card underneath, drawn by what the provider reports:

• Limits are thin gauges: green below 80 %, amber from 80 %, red at 100 %. A chip shows the time to reset, and a bright notch on the bar marks where an even spend would be by now. A gauge that has passed its tick is using the window faster than it lasts.
• Counters (tokens, sessions, lines) are a big number, with a week of bars where kittymux keeps daily history.
• State is a chip: the plan, a closed five-hour window, a cap hit last week.

Below the card, a seven-day strip shows tokens per day for providers that have history. Only exact daily numbers are drawn, so an old rolling total is never shown as one day. A provider kittymux has never heard of still gets a card, drawn from the same four kinds of meter, and a provider that is loading, failed or not installed says so instead of showing an empty box.

A provider's own report is dated when it is older than ten minutes (sample 3h ago, in amber after an hour), so a quiet agent does not look fresh. A quota window that has already ended is shown as window reset · no newer sample, never as the percentage it had. d shows source notes and how to turn on live quotas, and a live fetch that failed or went stale says so on the card.

Pick a provider with ← → (or h l, or the digits 1 to 9), or click its tile. ↑ ↓ scroll and r refreshes. A narrow panel drops the countdown before it drops the share. Network requests remain opt-in.

InboxCopy Anchor Link

Every event from the inbox is a card, with what needs you first and the newest first inside each group: a badge for its kind, the agent and its tab, how long ago, what it said, and for a limit a full gauge with the time to reset. Read events stay under the unread ones, dimmed, for a day (kittymux inbox --all lists the rest). Four chips filter the list: All, Needs you, Done and Limits.

Jump focuses the agent's window and marks that window's events read. Nothing in the inbox ever types into an agent: dismissing only hides the card, and z brings it back. Right after a dismissal the footer swaps its hints for z undo and takes it away after 8 seconds, or as soon as you use it. One step only: a second dismissal replaces the first offer.

Hover a tab or its pane row for a preview. Requests wait briefly while the pointer crosses rows and stale results are discarded. The preview identifies its pane and shows a numbered layout from kitty's real geometry. In Peek, press a digit or click a pane row to change the preview without moving focus; Enter jumps to that pane. Long titles and paths wrap, and arrows / Page Up / Page Down scroll the card.

Kitty 0.49.2's native tab bar receives no idle hover events. Right-click opens Peek there. Its native resize cursor also requires two visible panes; a single or zoomed pane uses the bar-side grab zone with a hand pointer. The docked panel can show its own resize cursor because it receives motion events.

Reading the Usage graphsCopy Anchor Link

A quota sparkline shows the first quota row's recorded hourly samples over 48 hours on a fixed 0–100% scale. Daily token bars show seven calendar days of exact local Claude counters relative to their peak. Dots mean unrecorded, not zero; today's tokens are partial. A new installation starts collecting quota history rather than inventing a trend. An elapsed local usage window is labeled elapsed, never remaining quota.

The view reports local refresh age and each live provider’s last-success age. Stale live data and failed fetches remain visible in the overview. History uses the original live observation timestamp, so a failed refresh does not create a fresh quota sample. It reads cached usage on the existing background worker and skips agent, PR and port scans while Usage is visible. Colours follow your kitty theme. Live provider requests remain opt-in.