keeptabs

Keep tabs on your AI coding agents.

🤖 Overview

keeptabs shows which of your Claude Code and Codex sessions are busy, finished, or waiting on you, and jumps straight to the one you pick.

https://github.com/user-attachments/assets/fd34f99f-05ff-4174-b0f9-0d9b328759b1

For Hyprland: supports kitty windows, tmux panes, or nvim terminal buffers.

✨ Features

• Waybar module: shows an icon per state with a count: when busy the icon bobs up and down, pulses when waiting on you, and hides automatically when no agents are running.
• Jump to an Agent, Anywhere: a rofi list of every session with its state, title, project, location, and age. Picking one directly focuses the pane/buffer within a window, a lone session skips rofi.
• Seen tracking: statuses update whenever you look at the window, however you get there. So, statuses clear automatically and only new actionable information is displayed.

📌 Requirements

🚀 Install

git clone https://github.com/uhs-robert/keeptabs
cd keeptabs
make install            # copies into ~/.local; PREFIX=/usr/local to change
# make link             # symlinks instead, for hacking on it

[!IMPORTANT] Make sure ~/.local/bin is on your PATH, including for the shells your agents run hooks in.

📦 Setup

Every file below is in examples/.

🚀 Required

Agent hooks

• Merge claude-settings.json into ~/.claude/settings.json, keeping any hooks you already have
• Merge codex-hooks.json to ~/.codex/hooks.json. In Codex, run /hooks to trust them.

Waybar

The status indicator on your bar to show agent state and activate picker with click.

• Add waybar-module.jsonc to your config and put custom/keeptabs in a bar's modules list
• Append waybar-style.css to your stylesheet and reload.

🍭 Optional

Hyprland Keybind

Keyboard shortcut to the keeptabs picker to pick an active agent session.

• Bind SUPER CTRL + A to the picker with hyprland.lua, or hyprland.conf on a classic config.

kitty

Allows keeptabs to focus an agent inside a kitty window or inside NeoVim.

• Add kitty.conf and restart it.
• All kitty windows share one process, and its remote control socket is how keeptabs tells them apart.

tmux

Allows keeptabs to focus an ai agent pane in tmux.

• Add tmux.conf so tmux reports which client has focus.
• Use ~/.config/tmux/tmux.conf instead if that is where yours lives.

🎨 Configuration

Colors are optional. Copy config.ini to ~/.config/keeptabs/config.ini and change any of them:

[colors]
waiting = #FFA0A0
done    = #A3E39A
running = #7FA3C9
idle    = #717A84
muted   = #717A84

The picker reads it each time it opens, and the Waybar module picks up changes within a couple of seconds. Colors must be #RRGGBB; anything else falls back to the default. Keys and section names are case-insensitive, and comments start with # or ;, on their own line or after a value. The module's .waiting, .done, and similar classes are still there for CSS if you want to style the whole module.

🔌 Other frontends

keeptabs-pick supports two flags for building a picker other than rofi:

• keeptabs-pick --json prints the session list as a JSON array, each session's state-file fields plus project (its cwd's basename), where (the same location string the rofi row shows), and context_used/context_window/context_pct (tokens used, the model's context window, and the percent used, all null until the transcript has usage to report).
• keeptabs-pick --focus <id> jumps straight to the session with that id, running the same seen hook, tmux, window, and nvim focus steps rofi would.
• keeptabs-status prints one Waybar JSON line per frame. Besides text, class, and tooltip, it emits a finished_seq field: a counter that goes up by the number of sessions that just went from running to done. A frontend other than Waybar can watch for it changing instead of diffing tooltip counts. For a few seconds after that transition, class also becomes an array with finished added (e.g. ["done", "finished"]) so Waybar CSS can animate the change; see .finished in waybar-style.css. A waiting_seq field works the same way for sessions that just started waiting on you, pairing with a transient waiting-started class entry (e.g. ["waiting", "waiting-started"], or ["waiting", "finished", "waiting-started"] if both fire at once); see .waiting-started and .waiting in waybar-style.css.

🚩 Caveats

• Window focusing is Hyprland only.
• Claude Code has no hook for Esc during a reply, so keeptabs reads Claude's own session status file in ~/.claude/sessions/. That file is undocumented and may change between Claude Code releases.