Give Claude Code Sessions Human‑Readable Names and Resume with One Click

Problem

Claude Code sessions are identified by UUIDs such as 198d4193-3a16-4051-8dfa-a9dac573c933. The native claude --resume command only lists sessions in the current directory, cannot rename a session after creation, and generates opaque names like multi-agent-d5, making it hard to recall which session belongs to which task.

Claude Code session mechanism

Session data is stored in two file types: ~/.claude/sessions/<pid>.json – registry of active sessions (sessionId, cwd, name, status).

~/.claude/projects/<project‑path>/<sessionId>.jsonl

– transcript of each session organized by project.

The built‑in CLI provides three related flags that work only before the session starts or are limited to the current directory: --name to name a session at launch. --resume <uuid> to resume a specific session. --continue to continue the most recent session in the current directory.

ccsa tool

cc-session-alias ( ccsa) is a single‑binary Go CLI (≈4 MB, no CGO, zero runtime dependencies) that maintains an alias → UUID mapping and resolves the alias back to the UUID before invoking claude --resume. Install it with:

go install github.com/bigwhite/cc-session-alias@latest

Typical workflow

In a project directory, give the most recent active session a readable name, list all sessions, view details, and resume with optional parameters:

# Assign a name to the most recent session
ccsa set agent-evolution

# List sessions (short ID, project, creation date)
ccsa list

# Show details and liveness state
ccsa info agent-evolution

# One‑click resume, passing extra flags to Claude
ccsa r agent-evolution --model fable

ccsa set

without --id automatically discovers the most recent session by first scanning sessions/*.json and, if none is found, falling back to projects/<project‑path>/*.jsonl. This removes the need to locate UUIDs manually.

Resume options

ccsa r <alias>

– shortest form; the process is replaced via syscall.Exec without an extra wrapper.

Install an optional shell wrapper so the native command claude --resume <alias> works transparently (the alias is expanded to the UUID before being passed to Claude).

Use an explicit pipeline: claude --resume $(ccsa get <alias>) – works without the wrapper and is the most robust.

Additional commands

Other useful commands include: ccsa rename – rename an alias. ccsa rm – delete an alias. ccsa prune – clean up aliases that point to vanished sessions. ccsa info – display the session’s liveness state as active (idle), active (busy), exited, or gone.

Design choices

Dual‑track resume : ccsa r uses syscall.Exec for a clean exec without extra process layers, while the optional shell wrapper intercepts only the first argument when it is not a UUID, leaving all other claude flags untouched.

Minimal storage : Aliases are stored in a single JSON file ~/.cc-session-alias/aliases.json with directory permissions 0700 and file permissions 0600. Writes are performed atomically via a temporary file and rename; corrupted files are backed up with a .bak suffix.

Wrapper boundary : The wrapper intercepts --resume / -r only when the argument is not a UUID, and does not affect other claude usages such as claude -p or claude --continue.

Target users

Heavy users of Claude Code with multiple concurrent sessions – a single alias eliminates the need to scan UUID lists.

Developers who frequently switch between project directories – ccsa list provides a global view, and --project filters by project.

Anyone who prefers clean, semantic context management – each session gets a meaningful name, and ccsa prune keeps the alias table tidy.

Tips and pitfalls

Run ccsa set <human‑readable‑name> in the current project first to experience automatic discovery. Names may contain letters, numbers, underscores, or hyphens, be 1–64 characters long, and must not include spaces or dots. ccsa r enables DisableFlagParsing, so flags such as --model are passed through unchanged, but the built‑in help ( r -h) is suppressed – an intentional trade‑off.

The shell wrapper is optional; the core ccsa r command works without it. Install the wrapper with ccsa install-hook and remove it with ccsa uninstall-hook; both operations are idempotent.

Conclusion

Claude Code’s native session handling is functional, but it lacks post‑creation naming, cross‑project visibility, and semantic resume. The 4 MB ccsa binary fills this gap, offering automatic discovery ( set), cross‑project listing ( list), three‑state liveness ( info), and one‑click resume ( r), plus an optional transparent shell wrapper.

Repository: https://github.com/bigwhite/cc-session-alias