Claude Code Pending Sessions TUI

When working across multiple Claude Code sessions, it's easy to lose track of which ones are waiting for your response.

There's no ambient signal — you have to check each session manually.

I created a keyboard-driven terminal UI to track and manage Claude Code sessions awaiting your response.

Installation

pip install textual

Or use uv:

uv run main.py

Usage

python main.py

CLI Flags

Flag	Effect
--days N	Default number of days to filter (0 = show all)
--ungrouped	Start in flat (non-grouped) view
--sort-reverse	Start sorted oldest-first (ascending)
--project NAME	Show only sessions whose project name contains NAME (e.g. emtech-noema)

This launches an interactive TUI that displays:

• All active Claude Code sessions sorted by most recent activity
• Project name, session title, time elapsed, and last message preview
• A scrollable list with keyboard navigation

Key Bindings

Key	Action
j / k or ↑ / ↓	Navigate list
Space	Toggle preview pane (shows last ~5 message exchanges)
o / Enter	Open session in Claude Code
d	Dismiss session (hide from list) / restore in dismissed view
D	Toggle dismissed-sessions view
/	Search session titles (Escape clears)
f	Set the days filter (0 = show all)
p	Open a box to type a project name to filter by (blank clears; Escape cancels)
n	Open a box to add/edit a note for the selected session (shown as 📝 on the row and in the preview pane; blank clears; Escape cancels)
g	Toggle grouped-by-project vs flat view
s	Toggle sort order (newest-first / oldest-first)
v	Open VS Code in the session's dir and copy a /resume command
V	Same as v, but copies the full claude --dangerously-skip-permissions -r CLI command
r	Refresh / re-scan conversation files
q / Ctrl+C	Quit

How It Works

Session Discovery

• Scans ~/.claude/projects/ for .jsonl session files
• Parses Claude Code session metadata (ID, title, messages, timestamps)
• Displays active sessions in reverse chronological order

Dismissal

• Sessions can be marked as dismissed by pressing d
• Dismissed session IDs are stored in ~/.claude/session.log
• Dismissed sessions are hidden from the TUI
• Can also be dismissed from within Claude Code via /clear command with proper hook setup

Notes

• Notes are stored as {session_id: text} in ~/.claude/session-notes.json
• Saving a blank note clears it

Session Structure

~/.claude/projects/
├── {project-name}/
│   └── {sessionId}.jsonl    # Session messages (line-delimited JSON)
├── -/
│   └── {sessionId}.jsonl    # Default context sessions
└── (etc.)

Hook Configuration

To automatically dismiss sessions when using /clear in Claude Code, add a SessionEnd hook to ~/.claude/settings.json:

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "python -c \"import sys,json; print(json.load(sys.stdin)['session_id'])\" >> ~/.claude/session.log"
          }
        ]
      }
    ]
  }
}

The hook fires on /clear, reads the session ID from stdin (passed by Claude Code as JSON), and appends it to ~/.claude/session.log. The TUI reads that file on startup and on refresh to exclude dismissed sessions.

Project Structure

agent-dashboard/
├── pyproject.toml          # Project configuration
├── spec.md                 # Specification
├── README.md               # This file
├── main.py                 # Entry point
└── src/
    ├── __init__.py
    ├── parser.py           # Session discovery and JSONL parsing
    ├── dismiss.py          # Dismissal log management
    ├── notes.py            # Per-session notes management
    └── ui.py               # Textual TUI application

Supported Claude Code Message Formats

The parser handles multiple message content formats:

• String content: Plain text messages
• Structured content: Lists of objects with type/text fields (used for text, thinking, images, etc.)

Future Enhancements (Out of Scope v1)

• Replying from within the TUI
• Searching/filtering sessions
• Starred or pinned sessions
• Custom session ordering
• Archiving vs. deletion distinction