Claude Code /rename Explained: Give Your Sessions Meaningful Names

Why /rename exists

After using Claude Code for a while, your session history grows long. By default, sessions are only identified by timestamps — to find the debugging context from three days ago, you’re left guessing or scrolling through entries one by one.

/rename solves this: give the current session a meaningful name so your history becomes searchable and traceable.

Basic usage

/rename works two ways:

Manual naming:

/rename fix-auth-token-expiry

Specify a name directly — it takes effect immediately:

Session renamed to: fix-auth-token-expiry

AI auto-naming:

/rename

With no arguments, Claude Code calls the Haiku model to analyze the current session and generate a name automatically. If there isn’t enough content yet, you’ll see:

Could not generate a name: no conversation context yet. Usage: /rename <name>

How AI auto-naming works

When you run /rename without arguments, here’s what happens under the hood:

Step 1: Extract conversation text

Claude Code scans the session’s message history and keeps only actual text from user and assistant messages — skipping tool call results, system messages, and meta messages.

If the conversation text exceeds 1,000 characters, only the last 1,000 are used — a tail-slice so that recent context takes priority, since what you’ve been doing most recently best represents the session.

Step 2: Call Haiku to generate a kebab-case name

The extracted text is sent to Haiku with this system prompt:

“Generate a short kebab-case name (2-4 words) that captures the main topic of this conversation. Use lowercase words separated by hyphens.”

With examples like: fix-login-bug, add-auth-feature, refactor-api-client, debug-test-failures.

Haiku returns a JSON response; Claude Code parses the name field as the final name.

Step 3: Apply the name

The generated name and a manually specified name go through exactly the same save flow.

Why Haiku instead of a more capable model? Naming is a simple summarization task — Haiku is faster and cheaper, and more than adequate.

Naming at startup: the -n flag

Beyond using /rename mid-session, you can name a session right from the start:

claude -n fix-login-bug
# or
claude --name fix-login-bug

The session has a name from the very first message — no need to rename later. The name is immediately written to the session title cache and shows up in /resume listings.

Auto-naming when exiting Plan mode

This is a detail most people never notice.

When you finish drafting a plan in Plan mode (/plan) and are about to move into execution, Claude Code automatically tries to name the session — as long as it doesn’t already have a name.

When it triggers: the moment you confirm exit from Plan mode (Accept Plan).

At that point, Claude Code calls generateSessionName on your plan content (taking the first 1,000 characters, head-slice rather than tail-slice — because the goal is usually stated at the beginning of a plan), generates a kebab-case name, saves it automatically with source set to 'auto' (distinct from /rename’s 'user').

The auto-naming has a guard:

If the session already has a name (manual or previously auto-named), it won’t be overwritten
If it’s a “clear-context” operation, the guard is skipped so the new execution session can be named

The dual-title system

Claude Code maintains two separate titles, both stored in the same session .jsonl file:

Type	Field	Entry type	Source	Priority
User-defined title	`customTitle`	`custom-title`	`/rename`, `-n` flag, Plan mode auto-naming	High
AI auto title	`aiTitle`	`ai-title`	System background generation	Low

When reading, customTitle always wins over aiTitle — whatever you explicitly named takes precedence; the system-generated title is just a fallback.

Why two separate entry types instead of one field?

This is intentional design, spelled out in the source comments:

Prevent AI titles from overwriting user titles: /resume restores the title only from custom-title entries, never treating an ai-title entry as a user-defined name
Prevent re-append bugs: When the session file’s tail is rewritten, only custom-title entries are re-appended — never ai-title — so a stale AI title can’t overwrite a name the user set mid-session
Separate write semantics: An AI title can overwrite a previous AI title, but it can never overwrite a user title

Two different AI naming formats

Claude Code has two distinct AI naming generators with completely different output formats:

Source	Format	Example
`/rename` (no args)	kebab-case, 2–4 words	`fix-auth-token-expiry`
System auto-naming (background)	Sentence case, 3–7 words	`Fix login button on mobile`

/rename produces machine-friendly short tags, suited for terminal display and scripting. System auto-naming produces more natural short phrases, suited for UI list display.

Their Haiku calls also differ: /rename uses a name JSON field; the system generator uses a title field. They are entirely independent generators.

Where it’s saved

The name is written as two entries in the session file (~/.claude/projects/<project-hash>/<session-id>.jsonl):

custom-title entry: stores the name for display in /resume and other list commands
agent-name entry: simultaneously updates the agent name shown in the terminal prompt bar, so you can see the current session name while the session is active

Both are appended to the same .jsonl file — no extra files created.

Sync with claude.ai

If you use Claude Code through Claude Desktop or claude.ai/code, /rename also syncs the new name to the cloud Bridge session:

Checks whether the current session is associated with a Bridge session ID (replBridgeSessionId)
If so, asynchronously calls updateBridgeSessionTitle to update the cloud-side title
The sync is non-blocking (fire-and-forget) — failures are silently swallowed and don’t affect local naming

This means a /rename in your terminal also updates the session list on claude.ai.

Can’t rename in Swarm mode

If the current session is a Swarm (multi-agent parallel) Teammate sub-session, /rename refuses:

Cannot rename: This session is a swarm teammate. Teammate names are set by the team leader.

Teammate names are managed by the Team Leader — individual teammates can’t rename themselves, preventing coordination confusion.

Using /rename with /resume

The value of /rename is most visible in /resume:

  1. fix-auth-token-expiry          2 hours ago
  2. add-payment-webhook            yesterday
  3. debug-memory-leak-prod         3 days ago
  4. 1745123456789                  4 days ago   ← unnamed, just a timestamp

Named sessions are instantly recognizable. Unnamed ones are just timestamps.

Make it a habit: name the session when you start a new task, or let Plan mode auto-name it for you. Your future self will thank you.

Practical tips

Name early: Once you know what you’re working on, run /rename fix-xxx before diving in.

Use -n at startup: Launch with claude -n refactor-api-client and skip the in-session rename entirely.

When unsure, just /rename (no args): Let AI decide — it’s usually more accurate than whatever you’d improvise, because it’s based on actual conversation content rather than your initial expectations.

Pair with Plan mode: When using /plan, accepting the plan auto-names the session for you — no manual step needed.

Closing thoughts

/rename is a small command, but it solves a real problem: context management for AI-assisted development.

Code commits live in git with full history. But conversations with Claude are nameless and hard to search by default. /rename gives each valuable session a recognizable label — and the dual-title system, Bridge sync, and Plan mode auto-naming together form a session management experience that’s been carefully thought through.

The best filing system is the one you actually use — /rename is how you file your AI conversations.