---
name: script-claude-sessions
description: claude-sessions — tmux session manager; interactive menu with folder picker, unique topic, and location column
metadata:
  type: reference
---

# claude-sessions

Python script (`scripts/claude-sessions`, symlinked to `~/sbin/`). Manages Claude Code tmux sessions: list, recover, resume, spawn, gc. Run with no args for the interactive menu.

## Menu behaviour (2026-10-26)

- **Location column.** Live and resumable rows show the session folder (`~` for `$HOME`). Live rows take it from the registry (`project_dir`), falling back to tmux `#{session_path}`.
- **`n` New session.** Asks for a folder: Enter accepts the nearest `CLAUDE.md` folder, `b` opens the folder browser, or type a project name/path (same lookup as `claude-tmux`).
- **Folder browser.** `zenity --file-selection --directory` when `DISPLAY`/`WAYLAND_DISPLAY` is set and zenity exists (has Create Folder). Otherwise a terminal browser: number = open, `u` up, `n` new folder, `/text` filter, `>` `<` page, `h` hidden, `~`/`/path` jump, Enter/`s` select, `q` cancel.
- **Profile.** After the topic, a numbered picker lists every `~/.claude-[company]-[profile]` dir that has a `projects/` folder, shown as `Company (profile)` (e.g. `O'Reilly IT (anthropic)`). A dir with no profile part (`~/.claude-octopus`) is skipped; `~/.claude` shows `Personal (main)`. Company names come from `profiles.yaml` `display_name` (parenthetical stripped), else the Title-Cased segment. Enter accepts `oreillyit-anthropic`. The choice is passed as `--profile` to `claude-tmux`.
- **Topic.** Becomes the tmux session name and the Remote Control name (passed as `--name` to `claude-tmux`). Defaults to the Title-Cased folder name. If that name is already a live tmux session, no default is offered and a unique topic is required. Topics containing `.` or `:` are rejected because tmux rewrites them to `_`.

## Headless spawn

`claude-sessions spawn <folder> --headless [--name topic] [--create] [--mode m] [--profile p]` — no prompts, no attach, for scripts and the `/spawn-session` skill. Exit 1 = folder missing (or `--create` needs an absolute path); exit 2 = topic in use (default topic is the Title-Cased folder name; no `#N` suffix is added). Without `--headless`, `spawn` behaves as before.

## Gotchas

- "In use" means a live tmux session. Resumable registry entries do not block a topic.
- `claude-tmux` still auto-appends `#N` on a collision, but the menu rejects collisions first.