Session naming conventions that survive 100 sessions

After running roughly 200 AI sessions across mq-dir's development and adjacent projects, I can tell you the single highest-leverage productivity intervention is session naming. Boring topic, real impact.

Here's the convention that survives, and the failure modes that taught us why each piece matters.

TL;DR

Use: <verb>-<noun>-<scope> for cmux session names; YYYY-MM-DD-<verb>-<noun> for session directories.

Examples:

cmux session names:        rewrite-auth-main, draft-launch-post, port-ios-appkit
session directory names:   2026-04-22-rewrite-auth, 2026-04-22-launch-post

Why these formats: scannable, memorable, sortable, no information loss.

What "naming convention" actually controls

When you have 50 sessions over a quarter:

• cmux list shows you all of them. You scan to find the one you want.
• mq-dir's CMUX sidebar mirrors the list. You click to focus.
• ~/dev/sessions/ directory listing shows session directories.

In all three contexts, the name is what differentiates. A bad name forces you to re-investigate (open the directory, check the CLAUDE.md, remember). A good name lets you decide without opening anything.

Compounded over 100 sessions, the difference is hours per quarter.

The proposed convention

For cmux session names: <verb>-<noun>-<scope>

Three parts:

1. Verb: rewrite, draft, port, bisect, investigate, debug, refactor, document, profile, optimize.
2. Noun: what it's about — auth, launch-post, ios-module, perf-regression.
3. Scope (optional): which target, which subsystem — main, web, ios, backend.

Examples:

rewrite-auth-main
draft-launch-post
port-ios-appkit
bisect-perf-regression
investigate-flaky-test
debug-render-loop

You can scan a list of 8 of these and instantly know what each one is.

For session directory names: YYYY-MM-DD-<verb>-<noun>

Four parts:

1. Date prefix (sortable).
2. Verb.
3. Noun.
4. (No scope here — the directory is just for filesystem; cmux session has the scope.)

Examples:

~/dev/sessions/
├── 2026-04-22-rewrite-auth/
├── 2026-04-22-launch-post/
├── 2026-04-23-port-ios/
├── 2026-04-23-bisect-perf/
└── ...

ls sorts naturally. Old sessions cluster; recent ones at the top. Date-based cleanup ("rm sessions/2025-Q4-*") works.

Why each piece matters

Why date prefix on directories

Date is the most durable mental index. You forget which auth thing was first; you remember "April 22 was the auth rewrite week."

Categorizing folders (bugfix/, feature/, experiment/) feels organized but the categories blur. Date doesn't.

Why no date prefix on cmux session names

cmux session names are short-lived (during the session) and need to fit in a cmux list table. Date adds noise without adding value when you're switching between active sessions.

The directory has the date; the cmux name has the verb-noun.

Why verb-first

The verb tells you what kind of work this is. "rewrite" is different from "investigate" is different from "draft." When you scan, the verb gives you the immediate frame.

Noun-first ("auth-rewrite-main") works but you have to read further to understand the verb. Verb-first ("rewrite-auth-main") leads with intent.

Why scope last

Scope (main, web, ios) is often optional — many sessions don't have ambiguity. When present, it narrows further. Putting it last keeps the verb-noun pair primary.

Anti-patterns we tried and abandoned

claude-1, claude-2, ..., claude-50

The default if you don't think about it. Becomes useless past 5 sessions. The number conveys nothing.

session-foo, session-bar

The "session-" prefix is redundant (we know it's a session — it's in a session manager). Wastes characters in the cmux list.

<long descriptive sentence>

investigate-the-flaky-integration-test-in-the-auth-module-from-yesterday

Unwieldy. Doesn't fit in column displays. The session name should be a key, not a description; the description goes in CLAUDE.md.

feature/auth-rewrite

Slashes break things in some contexts (filesystem, cmux, scripts). Use hyphens.

<project>-<verb>-<noun>

mqdir-rewrite-auth
mainapp-draft-launch

The project is already in the working directory. Adding it to the name is duplication. mq-dir's session for "rewrite-auth" is in ~/dev/sessions/.../repo which is a worktree of ~/dev/repos/mq-dir; the project relationship is automatic.

wip-<topic>

wip-auth
wip-docs

Everything is "wip" while you're working on it. The label adds no information. Drop it.

Capitalized names

RewriteAuth
DraftLaunchPost

cmux and most shells are case-sensitive but typing capitals is friction. Lowercase-with-hyphens is the convention; follow it.

Edge cases

Daemon / always-on sessions

For sessions that don't expire (build watchers, log tails, persistent agents):

daemon-build-watcher
daemon-log-tail
watch-deploy-status

Use daemon- or watch- prefix. Signals "don't clean me up automatically."

Resuming a session

If you finish today and continue tomorrow on the same task, keep the same name. The directory stays at 2026-04-22-rewrite-auth even if you work on it April 23+. Date is "started date," not "active date."

If the task expands into multiple distinct phases, spawn a new session:

2026-04-22-rewrite-auth-phase1
2026-04-25-rewrite-auth-phase2

Each phase has its own scope and CLAUDE.md.

Quick experiments

For 30-minute sessions, don't bother with full directories:

cmux create scratch
# work, done
cmux kill scratch

The convention is for sessions worth tracking. Throwaway is fine throwaway.

Multiple sessions on the same task

Sometimes you spawn a parallel session to investigate while another implements:

implement-auth-jwt
investigate-auth-jwt-edge-cases

The verb tells you which is which. Both reference the same noun.

Migrating an existing chaotic setup

If you're starting from claude-1 through claude-30 and want to migrate:

Step 1: list and label

cmux list > /tmp/sessions.txt

For each, look at the working directory + recent activity. Manually note "this is rewrite-auth-main" etc.

Step 2: rename

cmux rename claude-1 rewrite-auth-main
cmux rename claude-2 draft-launch-post
# ...

Step 3: move directories

If your session directories are also poorly named:

mv ~/dev/sessions/foo ~/dev/sessions/2026-04-22-rewrite-auth

Update the cmux session's working directory if needed.

Step 4: update CLAUDE.md files

Make sure each session's CLAUDE.md has the right title:

# Session: rewrite-auth-main — 2026-04-22

After migration, the convention is in place going forward.

Tools that support this convention

The convention works with any session manager, but specific integrations help:

cmux

cmux create <name> --dir <directory> — first-class support for named sessions.

mq-dir

mq-dir's CMUX sidebar shows the cmux session list directly. Names appear as the sidebar text. Good naming = scannable sidebar.

init-session.sh template

The session-init script (see the templates post) takes a verb-noun argument and creates everything correctly named:

init-session.sh rewrite-auth
# Creates ~/dev/sessions/2026-04-22-rewrite-auth/
# You'd separately spawn cmux:
cmux create rewrite-auth-main --dir ~/dev/sessions/2026-04-22-rewrite-auth

Why we settled on this

We tried roughly five conventions over 18 months:

1. claude-N: failed by session 8.
2. <noun> (e.g., auth): failed when we had auth and authrewrite and forgot which was which.
3. <verb>-<noun>: worked well — about 90% of the value.
4. <verb>-<noun>-<scope>: edge case improvement for when you have rewrite-auth-main and rewrite-auth-mobile simultaneously.
5. YYYY-MM-DD-<verb>-<noun> for directories: separate from cmux name; date enables natural sort and cleanup.

The double-format (cmux short-form, directory long-form-with-date) is what works in practice.

Verdict

Session naming is unglamorous but compounding. The convention that scales:

• cmux session: <verb>-<noun>-<scope> (lowercase, hyphens).
• Session directory: YYYY-MM-DD-<verb>-<noun>.

Lowercase. Hyphens. No spaces. No "session-" prefix. No project name (it's in the directory).

Spend 30 seconds picking the right verb-noun. Save hours of "which session was that?" investigation later.

mq-dir's CMUX sidebar makes the convention visible — well-named sessions are scannable, poorly named ones aren't. The naming is the indexing system; the file manager just renders it.