claude-session

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 matches both rename-session.sh and several other session-content operations (clean-profanity, repair, summarize, etc.). Args alone are not enough to decide.

Decision procedure:

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

Topics

Quick Reference

Summarize (View/Summarize Sessions)

/session summarize                 # select project/session then summarize
/session summarize     # summarize a specific session

Detailed guide

Import (Pipeline Delivery)

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

Detailed guide

Analyze (Session Analysis)

/session analyze                   # analyze current session
/session analyze       # analyze specific session
/session analyze --sync            # sync to Serena memory

Detailed guide

Archive (Move Session Out of Active Project)

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

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

Detailed guide

Split (Topic Split Recommendation)

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

Detailed guide

Classify (Session Classification)

/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)

/session move                     # default: --cwd-mode first
/session move   --cwd-mode all    # update all cwd occurrences
/session move   --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)

/session migrate                           # classify + move code sessions to worktree
/session migrate --dry-run                 # preview only
/session migrate           # 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)

/session compress     # 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)

/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

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

Detailed guide

ID (Current Session ID Lookup)

/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)

/session search Makefile remove          # find sessions by keyword
/session search --today ansible/Makefile # only sessions modified today
/session id                     # legacy alias — routed to search

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)

scripts/destroy-session.sh

Detailed guide

Purge (Dead Session Cleanup)

/session purge                    # dry-run: list dead sessions in current project
/session purge      # 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 [--delete]

Detailed guide

Clean Profanity (Sanitize Session Content)

# Single session
python3 ~/.claude/skills/claude-session/scripts/clean-profanity.py 

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

# Resolve UUID → path first (glob catches both bare .jsonl and
# archived flat names like _.jsonl)
find ~/.claude/projects -name "*.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)

/session repair                          # default: current session (uses hook-injected ID)
/session repair              # 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):

python3 ~/.claude/skills/claude-session/scripts/repair-session.py 
python3 ~/.claude/skills/claude-session/scripts/repair-session.py  --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):

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:

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

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

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

Detailed guide

Project Name Conversion Rules

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)