Name your Claude Code sessions before you run more than one

you are looking at

// Detect dark theme var iframe = document.getElementById('tweet-2095277618807316566-141'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2095277618807316566&theme=dark" }

The shorthand in that post is missing its arguments. Both flags take a value, so the real command is closer to this:

claude --name auth-refactor --worktree auth-refactor

Once you run two or three sessions side by side, the thing that breaks first is not context or tokens. It is you, looking at four terminal panes and not knowing which one is editing which branch.

What -n and -w actually do

--name (short form -n) sets a display name for the session. It shows up in the session picker, in the /resume list, in the prompt bar, and in the session_name field the status line receives. You can set it mid-session with /rename. If two sessions end up with the same name, Claude Code renames one with a two word suffix, so you get something like auth-refactor-graceful-unicorn instead of two identical entries.

--worktree (short form -w) takes a worktree name and runs the session inside a git worktree instead of your main checkout. It creates the worktree if it does not exist. It also accepts a PR reference, which is the form worth remembering:

claude -n review-1234 -w '#1234'
claude -n hotfix -w https://github.com/org/repo/pull/1234

Inside a worktree session, Claude Code enforces isolation. Edits to files in the main checkout, git commands that would redirect it, and shell commands that reach outside are blocked. That is the actual reason to use -w rather than just opening a second terminal in the same directory.

Where the worktree lands, and on which branch

New worktrees go to .claude/worktrees/<name>/ at your repository root. The branch is named worktree-<name>, unless you branched from a PR, in which case it is pr-<number>.

The default that catches people: a new worktree branches from the repository default branch on the remote, not from your current HEAD. That is the fresh setting, and it is the documented default. If you want new worktrees to start from the work you have in front of you, change it:

{
  "worktree": {
    "baseRef": "head"
  }
}

The second gotcha is gitignored files. A fresh worktree has no .env, so anything that reads it fails immediately. Add a .worktreeinclude at the project root, next to .git/, using gitignore syntax. Files are copied only when they both match a pattern and are gitignored:

.env
.env.local
config/secrets.json

Clean worktrees are removed when the session exits. Ones with uncommitted work stay, and you remove them yourself with git worktree remove.

/color is per session and does not persist

/color sets the prompt bar color. It accepts red, blue, green, yellow, purple, orange, pink, cyan, or default to reset. With no argument it picks one at random.

It is a session-scoped setting. Close the session and the color is gone, so it is a visual tag for the panes open right now, not part of your project config. Run it once after the session starts:

/color red

Put the name and the worktree in the status line

The name and the worktree only help if you can see them without switching panes. The status line is where that goes. Point statusLine at a script in any settings file, user, project, or local:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 0
  }
}

The script gets a JSON object on stdin. The fields that matter here are session_name, the worktree object, and context_window:

#!/usr/bin/env bash
input=$(cat)
name=$(jq -r '.session_name // "unnamed"' <<< "$input")
tree=$(jq -r '.worktree.name // "main checkout"' <<< "$input")
branch=$(jq -r '.worktree.branch // "-"' <<< "$input")
pct=$(jq -r '.context_window.used_percentage // 0' <<< "$input")
printf '%s | %s (%s) | ctx %s%%' "$name" "$tree" "$branch" "$pct"

The fallbacks are not defensive padding. The worktree object is present only while the session is actually in a worktree, and session_name is absent when the session has neither a custom name nor an AI generated title. Without the defaults you get empty strings in half your panes.

The full payload carries more than this: model.display_name, workspace.project_dir, worktree.original_branch, cost, prompt_cache, rate_limits, vim.mode. If you would rather not write the script by hand, /statusline takes a natural language description and generates one, then writes the settings entry for you.

There is an installable version of the one from the video:

// Detect dark theme var iframe = document.getElementById('tweet-2096292257322181033-993'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2096292257322181033&theme=dark" }

Start here, in this order

1. Set worktree.baseRef to head in your settings file if you want worktrees to branch from your current work rather than the remote default.
2. Add a .worktreeinclude at the repo root listing the gitignored files each worktree needs.
3. Write the status line script and register it under statusLine, or generate one with /statusline.
4. Start each session with claude -n <name> -w <name>, using the same string for both so the pane, the branch, and the directory all match.
5. Run /color <color> once inside each session.
6. Confirm the status line shows the name and the branch before you start a second session, not after you have four.

You can follow me on my social media:

• Twitter (English): https://x.com/dani_avila7
• LinkedIn (Spanish): https://www.linkedin.com/in/daniel-avila-arias/
• Youtube (Spanish): https://www.youtube.com/@daniiielsan
• Instagram (Spanish): https://www.instagram.com/danielsan_avila/