Feature: Named sessions via --session <name> flag for easier session management

[sanalthomas47]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

Summary
Add support for named sessions so users can create, resume, and manage Claude Code sessions by a human-readable name instead of a UUID.

Problem:
Today, session management works like this:

• Sessions are stored as UUIDs (e.g. 99291a8e-d549-484b-b418-9bae19b9a3e1.jsonl) under ~/.claude/projects//
• claude --resume shows a list ordered by timestamp with the working directory — no user-defined label
• There is no way to jump directly to a known session without scrolling the resume list

This becomes painful when:

• A project has multiple long-running sessions with distinct purposes (e.g. "feature-auth", "bug-payment-race", "refactor-ledger")
• A user works across several projects and wants to resume a specific session without hunting by timestamp
• Session history grows over weeks — the resume list becomes a wall of identical-looking UUIDs

Non-Goals

• This does not change how session history is stored (.jsonl files remain the source of truth)
• No cloud sync — local only, consistent with current session storage
• Does not replace --resume — both can coexist

Environment

• Claude Code CLI
• Platform: Windows / macOS / Linux (CLI-level change, platform-agnostic)

Proposed Solution

Proposed Solution

Introduce a --session flag and a lightweight name → UUID index stored in ~/.claude/sessions-named.json.

Commands:
Create a new session with a name, or attach if name already exists
claude --session

List all named sessions (name, project path, last used)
claude --sessions

Rename an existing named session
claude --session --rename

Delete a named session entry (does not delete the underlying .jsonl history)
claude --session --delete

Alternative Solutions

No response

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

Example workflow:
$ claude --session block-c-additions
Creates new session tagged "block-c-additions", resumes it next time

$ claude --sessions
NAME PROJECT LAST USED
block-c-additions F:\Projects\practice 2026-06-21 09:14
auth-refactor D:\tradingApp\backend 2026-06-20 17:42
ledger-design D:\tradingApp\backend 2026-06-18 11:05

$ claude --session auth-refactor
Resumes that session directly, no list to scroll through

Storage format (~/.claude/sessions-named.json):
[
{
"name": "block-c-additions",
"sessionId": "99291a8e-d549-484b-b418-9bae19b9a3e1",
"project": "F:\Projects\practice",
"createdAt": "2026-06-20T08:00:00Z",
"lastUsedAt": "2026-06-21T09:14:00Z"
}
]

Additional Context

Why This Matters
Users doing long-running, multi-session work (feature development, interview prep, research projects) currently have no ergonomic way to navigate sessions. Named sessions lower the friction to resume the right context immediately, which is especially valuable given that session context directly affects Claude's output quality.

[Necmttn]

Named sessions should be aliases over immutable session ids, not replacements for them. Store name, project scope, created/renamed timestamps, uniqueness rule, and collision behavior beside the UUID-backed transcript.

claude --resume <name> can resolve name to id and print both, while JSONL paths and internal edges stay keyed by the stable session id. That keeps names user-friendly without breaking tools that correlate transcript files, telemetry, and child-session lineage by id.

---

Generated with ax.

[sanalthomas47]

Alias Store (~/.claude/session-aliases.json)

[
{
"name": "block-c-additions",
"sessionId": "99291a8e-d549-484b-b418-9bae19b9a3e1",
"projectScope": "F:\Projects\practice",
"createdAt": "2026-06-20T08:00:00Z",
"renamedAt": null,
"lastUsedAt": "2026-06-21T09:14:00Z"
}
]

Fields:

• name — user-defined alias, unique per projectScope
• sessionId — immutable UUID, unchanged on rename
• projectScope — name uniqueness is scoped to the project directory (same name allowed across different projects)
• createdAt / renamedAt — audit trail for the alias itself, independent of session creation time
• lastUsedAt — updated on resume, not stored in the JSONL

JSONL path is unchanged: ~/.claude/projects//.jsonl — the alias store is a sidecar, never the source of truth.

CLI Behaviour

Attach a name to the current session (or a specific UUID)
claude --session --name block-c-additions
claude --session --name block-c-additions --id 99291a8e-...

Resume by name — resolves to UUID, prints both
claude --resume block-c-additions
→ Resuming session "block-c-additions" (99291a8e-d549-484b-b418-9bae19b9a3e1)

Resume by UUID still works, unchanged
claude --resume 99291a8e-d549-484b-b418-9bae19b9a3e1

List: names and UUIDs shown together
claude --sessions
NAME SESSION ID PROJECT LAST USED
block-c-additions 99291a8e-d549-484b-b418-9bae19b9a3e1 F:\Projects\practice 2026-06-21 09:14
auth-refactor 3fa2c10d-8e41-4b77-bc90-1d2e456f9a8b D:\tradingApp\backend 2026-06-20 17:42

Rename: only updates the alias, sessionId and JSONL are untouched
claude --session block-c-additions --rename study-guide-html

Remove alias only (JSONL transcript preserved)
claude --session block-c-additions --unalias

Uniqueness Rule and Collision Behavior

• Names unique within projectScope — same name allowed across different projects
• On collision within same project: error with suggestion
  Error: alias "auth-refactor" already exists in this project
  (session 3fa2c10d..., last used 2026-06-20)
  Use --force to reassign, or --rename to pick a different name.
• --resume with ambiguity (same name in multiple projects): prompt user to select, or require --project flag to disambiguate

What doesn't change

• JSONL paths stay .jsonl — no file moves on rename
• Telemetry, child-session lineage, and any tools correlating by ID are unaffected
• --resume continues to work exactly as today
• The alias store is optional — sessions without aliases continue to work normally

[kcarriedo]

Named sessions would directly address the ergonomics problem for multi-agent setups where the human has to track which session is handling which workstream.

The alias-over-UUID approach from the earlier comment is the right model. Mutable session content should stay at the immutable ID layer; the name is just a pointer. One addition worth including in the spec: an optional --session-scope flag so session names are project-local rather than global. When you are running 4-5 parallel sessions across different repos, a global name like "feature-auth" collides across projects.

A related gap that named sessions do not fully solve: once you have names, you still have no signal about which named sessions are currently live vs. idle. Even a read-only field like lastActiveAt in the alias store would let a parent process or dashboard surface which sessions actually need attention and which have compacted and gone quiet.

We ended up building external session tracking for this at Claudeverse -- a scheduling layer that maintains its own ledger of active sessions, their state, and their last heartbeat. Named sessions with stable handles would make that integration significantly cleaner because we would not have to scan transcript directories to infer session identity.

[kcarriedo]

Strongly agree with the named sessions proposal. The UUID-based list degrades fast once you have more than a handful of sessions per project -- even with timestamps it is hard to reconstruct "which session was I using last Tuesday for the auth refactor."

One addition that would make this more useful for orchestration workflows: a way to pass --session to a non-interactive invocation, so automated tools can resume a specific named session without a TTY. Right now the --resume flag requires a UUID, which means any automation that wants to resume a prior session has to first parse the session list -- brittle and fragile.

A secondary ask: expose session name (or a short slug derived from the name) in the API response or in the JSONL filename alongside the UUID, so external tooling can index sessions without shelling into the CLI. This would make session-aware orchestration significantly more reliable.

Running multi-session coordination tooling on top of Claude Code and session discoverability is the current rough edge -- every tool in the ecosystem that manages multiple concurrent sessions ends up re-implementing session enumeration from the ~/.claude/projects/ directory.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[kcarriedo]

The named sessions idea solves exactly the right problem. Right now the only way to find a specific session is to open each one and check what it was working on -- there's no external index of running sessions.

A --session flag would also make it possible to wire sessions into external orchestration: if you can reference a session by name, a wrapper script can track which named session is handling which workstream, restart a specific one if it orphans, or pass context between named sessions without relying on conversation history alone.

Would also be useful for hooks -- a hook that knows it's running in the "auth-refactor" session can write to a named output location rather than a generic temp directory.

Disclosure: I'm building Claudiverse (claudeverse.ai), a session orchestration layer for Claude Code that works around the lack of named sessions by maintaining an external index. A first-party flag would be cleaner than the workaround.