Session#

Integrated skill for managing Claude Code sessions.

Topic Dispatch#

When this skill is invoked with a topic specifier (e.g., /claude-session id or Skill("claude-session", "id")), load and follow only the matching topic file ( id.md). Do not echo the Topics table or summarize other topics in the response. The Topics table below is an index for invocations without a topic specifier — it is not user-facing output when a topic is named.

HARD STOP — unknown topic word + extra args#

When the first token of args does NOT match any topic in the Topics table below, do NOT silently fall back to rename (or any other topic) by matching argument-count heuristics.

The signature <uuid> <text> matches both rename-session.sh <id> <title> and several other session-content operations ( clean-profanity, repair, summarize, etc.). Args alone are not enough to decide.

Decision procedure:

1. If args contain <uuid> followed by an action verb / imperative phrase (e.g., <uuid> remove profanity, <uuid> remove X, <uuid> clean Y, <uuid> sanitize Z), the user wants a session-content operation. Match against clean-profanity, repair, summarize by intent.
2. If args contain <uuid> followed by a noun phrase / descriptive label (e.g., <uuid> "Auth refactor PR #42"), the user likely wants rename.
3. If intent is unclear, invoke AskUserQuestion listing candidate topics — never default to rename.

#Don'tDo1Route <uuid> remove profanity to rename because the arg signature matches rename-session.sh <id> <title>"remove profanity" reads as action verb → route to clean-profanity (or AskUserQuestion if uncertain)2Treat any non-topic-word trailing text as a title for renameClassify text as verb-phrase (action) vs noun-phrase (title) first3Silent fallback when no topic matchesAskUserQuestion: list 2–4 candidate topics that fit the apparent intent

Topics#

TopicDescriptionGuideanalyzeSession statistics, tool usage patterns, optimization insightsanalyze.mdarchiveMove a completed session out of the active project key to ~/.claude/projects/.bak/<project-key>_<uuid>.jsonl (flat naming, single backup root)archive.mdclassifyClassify project sessions (delete/keep/extract)classify.mdclean-profanitySanitize profanity tokens in a session JSONL file (in-place replacement)clean-profanity.mdsplitAnalyze topic boundaries and recommend session split pointssplit.mdcompressAI-compress sessions via claude-sessions-mcpcompress.mddestroyDelete current session and restart IDEdestroy.mddual-syncWindows ↔ WSL project memory path mapping — keep both environments' memory in syncdual-sync.mdidLook up current session ID (UUID)id.mdimportPipeline session data to other agents/skillsimport.mdinstallRegister session-id-inject hook in settings.jsoninstall.mdlistEnumerate current-project sessions (UUID + mtime + size)list.mdmemory-trimTrim project memory index (MEMORY.md) pointer-line hooks to a byte budget (script: scripts/trim-memory-index.py)memory-trim.mdmigrateMove sessions between projects (main repo → worktree)migrate.mdmoveMove specific sessions by ID to another project + update cwdmove.mdpurgeDelete dead sessions (hook-only, no assistant response) permanentlypurge.mdrenameAssign and look up custom title for sessionrename.mdrepairRestore session structure (chain, tool_result, UUID)repair.mdrewindSoft-rewind conversation context without reverting local workspace coderewind.mdsearchKeyword session search with result validation (verb/path/class checks)search.mdsummarizeView and summarize conversation content from other sessionssummarize.mdurlGenerate claude-sessions web URL from session IDurl.md

Quick Reference#

Summarize (View/Summarize Sessions)#

bash

/session summarize                 # select project/session then summarize
/session summarize <session_id>    # summarize a specific session

Detailed guide

Import (Pipeline Delivery)#

bash

/session import --hookify          # deliver to hookify
/session import --analyze          # analysis pipeline
/session import --to <agent>       # deliver to specific agent

Detailed guide

Analyze (Session Analysis)#

bash

/session analyze                   # analyze current session
/session analyze <session_id>      # analyze specific session
/session analyze --sync            # sync to Serena memory

Detailed guide

Archive (Move Session Out of Active Project)#

bash

/session archive <session_id>                                     # move to ~/.claude/projects/.bak/<project-key>_<uuid>.jsonl
bash ~/.claude/skills/claude-session/scripts/archive-session.sh <session_id>           # direct script call
bash ~/.claude/skills/claude-session/scripts/archive-session.sh <session_id> --dry-run # preview only

Moves to ~/.claude/projects/.bak/<project-key>_<uuid>.jsonl (flat naming, single backup root shared with transient backups). UUID portion preserved unchanged. Updates INDEX.md ledger.

Detailed guide

Split (Topic Split Recommendation)#

bash

/session split                     # Recommend split for current conversation
/session split <session_id>        # Recommend split for specific session
/session split --execute           # Execute recommendation immediately

Detailed guide

Classify (Session Classification)#

bash

/session classify                  # classify current project sessions
/session classify --depth=medium   # required when classifying sessions scheduled for split
/session classify --execute        # execute immediately after classification

⚠️ --depth=medium or higher required before split — fast only reads the last 3 messages, so it may miss different topics at the end of the session.

🔍 RAG MCP auto-detection — If a vector store MCP (Qdrant / Chroma / Weaviate / Pinecone / etc.) is registered in the current context, classify additionally recommends sessions worth saving to RAG. Vendor-agnostic — uses whichever store tool is detected. See Section 8 of classify.md.

Detailed guide

Move (Move Specific Sessions by ID)#

bash

/session move <session_id> <target_project_path>                   # default: --cwd-mode first
/session move <session_id> <target_project_path> --cwd-mode all    # update all cwd occurrences
/session move <session_id> <target_project_path> --cwd-mode first  # update only first cwd

Move explicit session IDs to another project directory and update cwd references via Python script. Cross-platform (Windows + macOS/Linux). Unlike migrate, no classification — just direct move.

Detailed guide

Migrate (Move Sessions Between Projects)#

bash

/session migrate                           # classify + move code sessions to worktree
/session migrate --dry-run                 # preview only
/session migrate <source> <target>         # specify source/target projects

Classifies sessions as CODE/INFRA/TINY/READ, then moves CODE sessions to worktree project and optionally deletes TINY sessions.

Detailed guide

Compress (Session Compression)#

bash

/session compress <session_id>    # compress specific session
/session compress                 # batch compress sessions containing "hookEvent":"Stop"

Calls mcp__claude-sessions-mcp__compress_session directly (registers the MCP server in project config first if not yet available).

Detailed guide

List (Enumerate Current-Project Sessions)#

bash

/session list                       # list current-project sessions (UUID + mtime + size)
/session list --all-projects        # summary across all projects
/session list --limit 20            # top N by mtime
/session list --engine antigravity  # list Antigravity (Gemini IDE) sessions instead

Non-destructive enumeration. For categorization or cleanup, use classify or purge instead.

Detailed guide

ID (Current Session ID Lookup)#

bash

/session id                          # look up current session ID

Current session ID — fast path (handle here, do NOT read id.md):

1. Hook injection (preferred) — Look for Current session ID: {uuid} in conversation context. SessionStart hook ~/.claude/hooks/session-id-inject.sh injects it as additionalContext at session start. If present, return the UUID immediately.
2. File path UUIDs — Scan recent tool results for UUID pattern [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12} in subagent/task/transcript paths. Return if found.
3. Marker fallback — Only if 1 & 2 fail: read id.md for the marker→grep procedure.

Detailed guide

Search (Keyword Session Search)#

bash

/session search Makefile remove                  # find sessions by keyword
/session search --today ansible/Makefile          # only sessions modified today
/session search --engine antigravity <keyword>    # search Antigravity (Gemini IDE) sessions instead
/session id <keyword>                             # legacy alias — routed to search

Default engine is Claude Code ( ~/.claude/projects/). Pass --engine antigravity (or reference a known ~/.gemini/antigravity-ide/brain/<uuid>/ session) to search Antigravity's transcript.jsonl instead — see search.md "Engine Selection" for both engines' procedures, including the SQLite-DB fallback for content not mirrored into the Antigravity transcript.

Always run the result-validation gate (verb ambiguity, artifact location, action class) before reporting matches as the answer to "which session did X" — a misplaced artifact path is a "task orphaned" signal, not a successful match.

Detailed guide

Destroy (Delete Session)#

bash

scripts/destroy-session.sh

Detailed guide

Purge (Dead Session Cleanup)#

bash

/session purge                    # dry-run: list dead sessions in current project
/session purge <project_name>     # dry-run: specific project
/session purge --all              # dry-run: all projects

Dead session = 10 lines or fewer + no "type":"assistant" response. Script: scripts/purge-dead-sessions.sh <project_name> [--delete]

Detailed guide

Clean Profanity (Sanitize Session Content)#

bash

# Single session
python3 ~/.claude/skills/claude-session/scripts/clean-profanity.py <session_file.jsonl>

# Multiple sessions
python3 ~/.claude/skills/claude-session/scripts/clean-profanity.py file1.jsonl file2.jsonl

# Resolve UUID → path first (glob catches both bare <uuid>.jsonl and
# archived flat names like <project-key>_<uuid>.jsonl)
find ~/.claude/projects -name "*<uuid>.jsonl"

Replaces matched tokens with **** in place. Patterns loaded from data/profanity-patterns.json. Back up before running; do not run on the live current session.

Detailed guide

Repair (Session Recovery)#

bash

/session repair                          # default: current session (uses hook-injected ID)
/session repair <session_id>             # repair specific session
/session repair --dry-run                # preview only
/session repair --check-only             # validate only (no repair)

Primary script (full pipeline: backup → dedup → 400 error → orphan tool_result → chain → validate):

bash

python3 ~/.claude/skills/claude-session/scripts/repair-session.py <session_file>
python3 ~/.claude/skills/claude-session/scripts/repair-session.py <session_file> --dry-run

Repair targets:

• Broken chain (missing parentUuid)
• Orphan tool_result (no matching tool_use)
• Duplicate UUIDs / duplicate message.id (Syncthing conflicts)
• API 400 error lines (incl. invalid surrogate pair / thinking-block signature)

Detailed guide

Rename (Naming a Session)#

Current session → output a copyable /rename list (NO script, NO AskUserQuestion):

text

Session name suggestions:

1. `/rename Candidate 1`
2. `/rename Candidate 2`
3. `/rename Candidate 3`

/rename is a Claude Code built-in command — it cannot be invoked via Bash or the Skill tool. The user copies and pastes the desired line. Do NOT call rename-session.sh for the current session (it is reserved for other sessions by ID).

Other session (session ID specified) → apply via script:

bash

# Assign a name to a specific session
bash scripts/rename-session.sh <session_id> "name"

# Check current title
bash scripts/rename-session.sh --show <session_id>

# List named sessions in current project
bash scripts/rename-session.sh --list

Detailed guide

Project Name Conversion Rules#

Actual PathProject Name/Users/<user>/works/.vscode``-Users-user-works--vscode``/Users/<user>/Sync/AI``-Users-user-Sync-AI

Rule: all non-alphanumeric characters → - (i.e., replace(/[^a-zA-Z0-9]/g, '-'))

Requirements#

• claude-sessions-mcp MCP server required
• Serena MCP server (when using analyze --sync)