TUI launcher for Claude Code sessions

Browse all your projects, see git status at a glance, monitor active sessions in real time, get notified when Claude finishes, and launch everything in parallel Terminal windows.

---

Install

Requires Bun >= 1.3.0 and macOS (uses Terminal.app for launching).

# Install globally
bun install -g @alezmad/cladm

# Or run directly
bunx @alezmad/cladm

From source (for development)

git clone https://github.com/alezmad/cladm.git
cd cladm
bun install
bun link

Usage

cladm           # launch with real project data
cladm --demo    # launch with mock data (try it out without any history)

How it works

cladm reads ~/.claude/history.jsonl to discover every project you've used with Claude Code, then enriches each one with live git metadata. The result is a fast, keyboard-driven picker that shows you everything at a glance.

Live activity monitoring

cladm detects running Claude Code sessions and shows their real-time status:

Indicator	Meaning
● (green)	Busy — Claude is actively processing
◉ 3m (yellow)	Idle — Claude finished 3 min ago, waiting for input
○ (dim)	No active session

How it works: cladm reads the tail of each session's JSONL file in ~/.claude/projects/. A session is considered busy if the file was written within 5 seconds OR the last assistant message contains a pending tool_use (meaning Claude is waiting for a tool to finish). This prevents false idle triggers during long-running tool calls and subtasks.

Sound notification: When any session transitions from busy → idle, cladm plays a system sound (Glass.aiff) so you never miss a completed response — even when working across multiple projects.

Screenshots

Project list

The main view shows all discovered projects sorted by most recent Claude usage. Each row displays the project name, git branch, sync status, last commit, working tree state, Claude activity, session count, message count, and detected stack.

Column	Description
PROJECT	Relative path from ~/Desktop
BRANCH	Current git branch (truncated to 8 chars)
SYNC	Remote sync: ✓ synced, ↑n ahead, ↓n behind, ✗ no remote
COMMIT	Time since last commit
MESSAGE	Last commit message
DIRTY	Working tree: clean, or +staged ~modified ?untracked
LAST USE	Time since last Claude session
SES	Total Claude session count
MSGS	Total message count across sessions
STACK	Auto-detected stack tags (ts, py, rust, go, docker, etc.)

Expanded view

Press → on any project to expand it and see branches and individual sessions with their conversation previews.

Each session shows:

• Title — auto-generated session title
• Status — ● running (green) or ◉ idle (yellow) for active sessions
• Last prompt — your most recent message
• Claude's response — the assistant's last reply
• Size & age — session file size and time since last use

Select a branch to launch Claude with a prompt to switch to that branch. Select individual sessions to resume them directly.

Keybindings

Key	Action
↑ ↓	Navigate
Space	Toggle selection
→	Expand project (branches + sessions)
←	Collapse project
a	Select all
n	Deselect all
s	Cycle sort mode (recent → name → commit → sessions)
f	Open project folder in Finder
g	Go to active session (focus Terminal)
Enter	Launch selected in Terminal.app
PageUp PageDown	Jump 15 rows
Home End	Jump to top/bottom
i	Toggle idle sessions panel
u	Toggle usage panel
/	Filter projects
q Esc	Quit

Shell helper

Add to ~/.zshrc to focus the cladm window from any terminal:

cladm() {
  local tty=$(ps -eo tty,command | grep 'bun.*src/index.ts' | grep -v grep | awk 'NR==1{print "/dev/tty"$1}')
  if [ -z "$tty" ]; then echo "cladm not running"; return 1; fi
  osascript -e "
tell application \"Terminal\"
  activate
  repeat with w in windows
    repeat with t in tabs of w
      if tty of t is \"$tty\" then
        set selected of t to true
        set index of w to 1
        return
      end if
    end repeat
  end repeat
end tell"
}

What gets launched

Each selected project opens a new Terminal.app window running Claude Code:

cd /path/to/project && claude --dangerously-skip-permissions

If you selected a specific session, it resumes it with --resume <session-id>. If you selected a non-current branch, it adds a prompt to switch branches first.

Multiple sessions in the same project open as tabs in the same window.

Stack detection

cladm auto-detects project stacks by checking for common files:

File	Tag
package.json	node
pyproject.toml / requirements.txt	py
Cargo.toml	rust
go.mod	go
CLAUDE.md	claude
Dockerfile / docker-compose.yml	docker

Tech stack

• Runtime: Bun
• UI: @opentui/core (terminal UI framework)
• Language: TypeScript

License

MIT