Session

English · Русский

Kitten for kitty: a full-screen overlay for browsing and managing Claude Code sessions — right from the terminal, on a hotkey.

Called from a directory that is not a Claude project, it opens on the projects screen — every project from ~/.claude/projects with its session count and live activity; the current one (by window cwd) is marked (here). Called from a project folder, it goes straight to that project's sessions, and Esc steps back to the projects screen; called from a window that is already running a session, it lands on that very session — the cursor sits on its row:

Enter opens the project's sessions. Running ones show their real status — busy (green), waiting (yellow), ◆ bg busy for a background agent — plus the git branch and message count; a renamed session keeps its custom title:

p (or →) previews the conversation as a Claude Code-style transcript: the prompt, tool calls with their output, file edits as coloured diffs, errors in red, markdown answers with highlighted code:

What it does

• Projects → sessions navigation. A list of projects (~/.claude/projects), and inside it — the sessions of the selected project. The current project (by window cwd) is marked (here). Opened from a window that is running a session, the kitten starts on that session: kitty passes it the pid of the window's process, and the session is found through the process tree — so a project with several live sessions still resolves to the right one.
• Live activity. Shows which sessions are running right now and their status (busy / idle / waiting) — the data source is reliable, from the registry of live processes, not from file timestamps. waiting means the session is waiting for an answer — a permission prompt, for instance. Background agents are marked separately (◆, bg idle): they cannot be resumed while they run — see How activity is determined.
• Resume / fork. o (or Enter) — claude --resume <id> in the project folder, over the current window (an overlay; a split beside it if the window is already running claude); f — the same, but --fork-session (fork the conversation without touching the original session).
• New session / continue. n — a new claude in the folder (the project, or the session's project); c (on the projects screen) — claude --continue (resume the project's last session). If the project window is already busy with a running claude, the new session opens beside it in a split — that needs the splits layout from the terminal config; on a stock kitty it just opens as a separate window instead (either way the running session isn't covered, and nothing breaks). A free window is taken over by the session itself (an overlay), and the session reports its working directory to kitty, so splits made from it (Cmd+D / Cmd+Shift+D) open in the project folder. The session's window is titled claude · <project>, the kitten's own window — Session.
• Worktree. w — claude --worktree <name>: create an isolated git worktree and start a session in it (parallel work without touching the main working tree). The name is asked for in the input line; if empty, Claude generates it itself.
• Conversation preview as a Claude Code-style transcript: turns (> / ⏺), tool calls with their argument (⏺ Bash(git status)) and output (⎿), errors in red. File edits show as ⏺ Update(tests/x.py) with a summary and a coloured diff, a file read as ⎿ Read 402 lines, and leaving plan mode as ⏺ Updated plan with the plan in a frame. A background agent reads as ⎿ Running in background, and its report — which arrives long after the call — says whose task it was and how it ended: ⎿ Agent(Audit moon phase rounding) finished with the agent's summary under it. Background commands and monitors report the same way. A call the user refused shows as ⎿ Rejected by user, an interrupted turn as ⎿ Interrupted by user, and MCP tools keep Claude Code's naming (tinkerwell - evaluate-remote-php-code). Claude's answers render markdown (bold, italic, inline code, headings, lists, tables) with syntax-highlighted code blocks. Long output is folded (… +N lines); Ctrl+o expands all of it. Exploration calls — searching, reading, listing — collapse into a summary line (Searched for 2 patterns, read 1 file); commands, file edits, plans and failed calls always stay visible. Plus text search (/, jump with n / N, highlighted).
• Renaming a session (r). Writes a custom-title entry into the session file — the same thing the /rename command does in Claude Code, so the name shows up both there and here.
• List filter by name (/ in the list).
• Hides noise: sdk sessions (entrypoint: sdk-cli) and internal ~/.claude/… folders are hidden by default; toggle with a.
• Shortcuts also work on a Russian keyboard layout (by key position).

Setup

familiar enable session

Reload the config with Cmd+Ctrl+, (macOS) or restart kitty. Open with: cmd+shift+s.

Minimal fallback — a manual map in ~/.config/kitty/kitty.conf (or a separate include file):

map cmd+shift+s kitten /path/to/familiar/plugins/session.py

Unlike familiar enable, this bare map lacks the toggle-to-close behavior, the guard against re-opening the overlay on top of itself, the full-screen open from a split (the stack-layout switch), and the Cyrillic key duplicates for the Russian layout.

Keys

Mouse: click a row — select; click the selected row again — open (enter the project / resume the session).

Lists (projects / sessions)

Key	Screen	Action
↑/↓, PgUp/PgDn	both	navigation
g / G, Home/End	both	to start / end
mouse click	both	select row · click again — open
Enter	both	open project / resume session
→	sessions	preview (on projects — open)
n	both	new session (claude) in the directory
w	both	worktree (claude --worktree) + new session
c	projects	continue (claude --continue)
a	projects	show all sessions / cli only
o	sessions	resume — claude --resume over the current window (a split if it is busy)
f	sessions	fork — resume with --fork-session
p	sessions	preview conversation (same as →)
r	sessions	rename session
/	both	search (filter) the list
Esc	both	back (or clear the filter); at the project list — ask to close the overlay
q ⌃c	both	quit

Esc at the bottom of the cascade (the project list, no filter applied) doesn't close the overlay silently: a centered kitty-style dialog asks first — y / Enter / a click on Yes closes, n / Esc / No keeps it open, ←/→/Tab switch the buttons. ⌃c quits at once even over the dialog; q works only while the dialog isn't shown.

Preview

Key	Action
↑/↓, PgUp/PgDn, mouse wheel	scroll
g / Home, G / End	jump to the start / end of the history
[ / ]	jump to the previous / next user turn
click a folded line	expand / collapse it (output, plan, file contents, tool summary)
Ctrl+o	expand all folded output (press again to collapse)
drag with the mouse	select: within a line — a span, across lines — whole lines
⌘c	copy the selection
/	search the conversation text
n / N	next / previous match
o	resume
f	fork (resume with --fork-session)
Esc ←	back
q	quit

While typing (filter / search / rename / worktree name)

Key	Action
← →, Home / End	move the caret — insertion happens at the caret
Backspace / Delete	erase before / after the caret

How activity is determined

Claude Code keeps a registry of live processes in ~/.claude/sessions/<pid>.json (sessionId, cwd, status, waitingFor, kind). The plugin reads it and checks that the pid is alive — so active sessions are detected precisely, with a real status, not by mtime.

Entries with kind: bg are background agents. Claude Code refuses to attach to a live agent (claude --resume answers "stop it there first to resume here"), so such sessions are marked with ◆ and a bg <status> label, and o/Enter does not start a resume on them. The options: stop the agent, attach to it via claude agents, or fork the conversation (f) — a live process does not block a fork.

Data sources

• ~/.claude/projects/<enc>/<uuid>.jsonl — sessions (<enc> is the project path with / and . replaced by -). The title comes from custom-title (/rename), otherwise ai-title, otherwise the first message.
• ~/.claude/sessions/<pid>.json — registry of running sessions and their statuses.