[BUG] sessions-index.json stops updating - new sessions not appearing in /resume picker (Linux/WSL2)

[juangutierrezmonaco]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

Description

The sessions-index.json file stops updating at some point, causing new sessions to not appear in the /resume
picker. Session .jsonl files are correctly written to disk, but they are never registered in the index file.

Steps to Reproduce

1. Use Claude Code normally over multiple sessions across several days
2. Run /resume to see the list of past conversations
3. Notice that recent sessions (last 2-3 days) are missing from the list
4. Verify that the .jsonl session files exist on disk:

   ls -lt ~/.claude/projects/<project-path>/*.jsonl | head -10

5. Check sessions-index.json and confirm it has not been updated:
   cat ~/.claude/projects//sessions-index.json

Expected Behavior

All sessions should appear in /resume. The sessions-index.json file should be updated every time a new session is
created.

Actual Behavior

sessions-index.json stopped updating on Feb 3rd. Sessions from Feb 3, 4, and 5 exist as .jsonl files (including one
that is 6.6 MB) but are not in the index. The last indexed session is from Jan 29.

The sessions can still be resumed manually using:
claude --resume

This has happened repeatedly - sessions keep "disappearing" from /resume.

Diagnostic Data

• 5 session files on disk not present in sessions-index.json
• sessions-index.json last meaningful update: Jan 29, file mtime: Feb 3
• Largest missing session: 6.6 MB (e60db920-8e16-4f8d-855a-2a8f48ed1802.jsonl)
• Index contains 11 entries, but at least 16 session files exist

Environment

• Claude Code version: 2.1.31
• OS: Linux (WSL2) - Linux 6.6.87.2-microsoft-standard-WSL2
• Platform: Ubuntu on Windows WSL2
• Shell: bash

Related Issues

• [BUG] /resume only shows a few recent conversations, most sessions missing from picker #23375 - /resume only shows a few recent conversations
• Bug: /resume command shows incomplete session list #23302 - /resume command shows incomplete session list
• Sessions not appearing in resume list despite valid session files #23358 - Sessions not appearing in resume list (closed/completed)

Labels (seleccionalos en la barra lateral)

• bug
• area:core
• platform:linux

---

What Should Happen?

Every time a new Claude Code session is created, it should be registered in the sessions-index.json file so it appears in the /resume picker. All sessions should be visible and resumable from the /resume list.

Error Messages/Logs

Steps to Reproduce

1. Use Claude Code on a project over multiple days with several sessions

2. After a few days, run /resume to list past conversations

3. Notice that recent sessions (last 2-3 days) are missing from the picker

4. Verify session files exist on disk but are not indexed:

   Session .jsonl files exist:

   ls -lt ~/.claude/projects//*.jsonl | head -10

   Shows files from Feb 3, 4, 5

   But sessions-index.json only has entries up to Jan 29:

   cat ~/.claude/projects//sessions-index.json

   Last entry is from Jan 29, 11 entries total

   Meanwhile there are at least 16 .jsonl session files on disk

5. Sessions CAN be resumed manually with: claude --resume
   This confirms the session data is intact, just not indexed.

In my case, 5 sessions across 3 days were written to disk but never added
to sessions-index.json. The largest missing session is 6.6 MB. This issue
has happened repeatedly - it's not a one-time occurrence.

Claude Model

None

Is this a regression?

Yes, this worked in a previous version

Last Working Version

No response

Claude Code Version

2.1.32 (Claude Code)

Platform

Anthropic API

Operating System

Other Linux

Terminal/Shell

Terminal.app (macOS)

Additional Information

No response

[github-actions]

Found 3 possible duplicate issues:

1. sessions-index.json not updated - claude -c fails to find sessions #22462
2. Sessions not added to sessions-index.json, invisible to resume #22205
3. Bug: /resume command shows incomplete session list #23302

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[bosmadev]

Workaround: auto-repair via SessionStart hook

Same issue confirmed on Windows 11 (CC 2.1.34) — 25 of 95 sessions indexed. See #23614 for the full root cause analysis.

Built a repair script + SessionStart hook that auto-fixes this on every CC launch:

Repair script (repair-sessions-index.py)

Click to expand full script (~250 lines)

#!/usr/bin/env python3
"""
Session Index Repair Script

Repairs Claude Code sessions-index.json by:
- Finding orphaned session files (on disk but not in index)
- Detecting dead entries (in index but no file on disk)
- Fixing customTitle collisions (append date suffix)
- Backing up before modifications

Usage:
    python repair-sessions-index.py              # Dry-run (report only)
    python repair-sessions-index.py --fix        # Apply fixes
    python repair-sessions-index.py --verbose    # Detailed output
    python repair-sessions-index.py --hook       # SessionStart hook mode
    python repair-sessions-index.py --quiet      # Silent when nothing to fix
"""

import argparse
import io
import json
import re
import sys
from collections import defaultdict
from datetime import datetime, timezone
from pathlib import Path
from typing import Any

# Fix Windows cp1252 encoding for Unicode output
if sys.stdout.encoding and sys.stdout.encoding.lower() != "utf-8":
    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace")

UUID_PATTERN = re.compile(
    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.jsonl$",
    re.IGNORECASE
)

MAX_VERBOSE_SESSIONS = 10
MAX_DEFAULT_SESSIONS = 5


def format_size(size_bytes: int) -> str:
    if size_bytes < 1024:
        return f"{size_bytes}B"
    elif size_bytes < 1024 * 1024:
        return f"{size_bytes // 1024}KB"
    else:
        return f"{size_bytes / (1024 * 1024):.1f}MB"


def parse_session_file(session_path: Path) -> dict[str, Any] | None:
    """Parse a session JSONL file to extract metadata."""
    try:
        lines = session_path.read_text(encoding="utf-8").splitlines()
    except (OSError, UnicodeDecodeError) as e:
        print(f"  Failed to read {session_path.name}: {e}", file=sys.stderr)
        return None

    if not lines:
        return None

    session_id = None
    first_prompt = "No prompt"
    custom_title = None
    message_count = 0
    created = None
    modified = None
    git_branch = None
    is_sidechain = False

    for line in lines:
        if not line.strip():
            continue
        try:
            data = json.loads(line)
        except json.JSONDecodeError:
            continue

        if not session_id and "sessionId" in data:
            session_id = data["sessionId"]
        if git_branch is None and "gitBranch" in data:
            git_branch = data.get("gitBranch", "main")
        if "isSidechain" in data:
            is_sidechain = data.get("isSidechain", False)
        if "timestamp" in data:
            ts = data["timestamp"]
            if not created:
                created = ts
            modified = ts
        if data.get("type") in ("user", "assistant", "tool_use", "tool_result"):
            message_count += 1
        if data.get("type") == "user" and first_prompt == "No prompt":
            message = data.get("message", {})
            content = message.get("content", "")
            if isinstance(content, str) and content.strip():
                first_prompt = content[:80].strip()
                if len(content) > 80:
                    first_prompt += "..."
        if data.get("type") == "custom-title":
            custom_title = data.get("customTitle")

    if not session_id:
        session_id = session_path.stem

    return {
        "sessionId": session_id,
        "fullPath": str(session_path.absolute()),
        "fileMtime": int(session_path.stat().st_mtime * 1000),
        "firstPrompt": first_prompt,
        "customTitle": custom_title,
        "summary": first_prompt,
        "messageCount": message_count,
        "created": created or datetime.fromtimestamp(
            session_path.stat().st_ctime, tz=timezone.utc
        ).isoformat(),
        "modified": modified or datetime.fromtimestamp(
            session_path.stat().st_mtime, tz=timezone.utc
        ).isoformat(),
        "gitBranch": git_branch or "main",
        "projectPath": str(session_path.parent.parent.absolute()),
        "isSidechain": is_sidechain,
    }


def find_orphaned_sessions(project_dir: Path, index_data: dict) -> list[dict]:
    indexed_ids = {entry["sessionId"] for entry in index_data.get("entries", [])}
    orphaned = []
    for session_file in project_dir.glob("*.jsonl"):
        if not UUID_PATTERN.match(session_file.name):
            continue
        if session_file.stem not in indexed_ids:
            metadata = parse_session_file(session_file)
            if metadata:
                orphaned.append(metadata)
    orphaned.sort(key=lambda x: x.get("created", ""), reverse=True)
    return orphaned


def find_dead_entries(project_dir: Path, index_data: dict) -> list[dict]:
    return [
        entry for entry in index_data.get("entries", [])
        if not Path(entry["fullPath"]).exists()
    ]


def detect_title_collisions(entries: list[dict]) -> dict[str, list[dict]]:
    title_map = defaultdict(list)
    for entry in entries:
        ct = entry.get("customTitle")
        if ct:
            title_map[ct].append(entry)
    return {t: e for t, e in title_map.items() if len(e) > 1}


def fix_title_collisions(entries: list[dict]) -> None:
    for title, dupes in detect_title_collisions(entries).items():
        dupes.sort(key=lambda x: x.get("created", ""))
        for entry in dupes[1:]:
            created = entry.get("created", "")
            try:
                dt = datetime.fromisoformat(created.replace("Z", "+00:00"))
                suffix = dt.strftime("%Y-%m-%d")
            except (ValueError, AttributeError, TypeError):
                suffix = "unknown"
            entry["customTitle"] = f"{title} ({suffix})"


def backup_index(index_path: Path) -> Path:
    backup_path = index_path.with_suffix(".json.bak")
    backup_path.write_text(
        index_path.read_text(encoding="utf-8"), encoding="utf-8"
    )
    return backup_path


def repair_project(project_dir: Path, fix: bool, verbose: bool) -> dict:
    index_path = project_dir / "sessions-index.json"
    if not index_path.exists():
        return {"error": f"sessions-index.json not found in {project_dir}"}

    try:
        index_data = json.loads(index_path.read_text(encoding="utf-8"))
    except (json.JSONDecodeError, OSError) as e:
        return {"error": f"Failed to read index: {e}"}

    existing = index_data.get("entries", [])
    orphaned = find_orphaned_sessions(project_dir, index_data)
    dead = find_dead_entries(project_dir, index_data)
    disk_count = len([
        f for f in project_dir.glob("*.jsonl")
        if UUID_PATTERN.match(f.name)
    ])
    collisions = detect_title_collisions(existing + orphaned)

    stats = {
        "project_dir": str(project_dir),
        "indexed": len(existing),
        "on_disk": disk_count,
        "orphaned": len(orphaned),
        "dead": len(dead),
        "collisions": len(collisions),
        "collision_entries": sum(len(e) for e in collisions.values()),
        "orphaned_sessions": orphaned[
            :MAX_VERBOSE_SESSIONS if verbose else MAX_DEFAULT_SESSIONS
        ],
    }

    if fix:
        stats["backup"] = str(backup_index(index_path))
        cleaned = [e for e in existing if e not in dead]
        merged = cleaned + orphaned
        fix_title_collisions(merged)
        merged.sort(key=lambda x: x.get("created", ""), reverse=True)
        index_data["entries"] = merged
        index_path.write_text(
            json.dumps(index_data, indent=2, ensure_ascii=False),
            encoding="utf-8",
        )
        stats["fixed"] = True
        stats["new_total"] = len(merged)

    return stats


def run_hook_mode() -> None:
    """Run as SessionStart hook - auto-fix silently, output hook JSON."""
    try:
        sys.stdin.read()
    except Exception:
        pass

    claude_dir = Path.home() / ".claude" / "projects"
    if not claude_dir.exists():
        sys.stdout.write('{"continue":true,"suppressOutput":true}')
        return

    total_fixed = 0
    for d in claude_dir.iterdir():
        if d.is_dir() and (d / "sessions-index.json").exists():
            stats = repair_project(d, fix=True, verbose=False)
            if stats.get("fixed") and stats.get("orphaned", 0) > 0:
                total_fixed += stats["orphaned"]

    if total_fixed > 0:
        print(
            f"[session-repair] Re-indexed {total_fixed} orphaned session(s)",
            file=sys.stderr,
        )
    sys.stdout.write('{"continue":true,"suppressOutput":true}')


def main() -> None:
    ap = argparse.ArgumentParser(
        description="Repair Claude Code sessions-index.json"
    )
    ap.add_argument("--fix", action="store_true")
    ap.add_argument("--verbose", action="store_true")
    ap.add_argument("--quiet", action="store_true")
    ap.add_argument("--hook", action="store_true")
    ap.add_argument("--project", type=str)
    args = ap.parse_args()

    if args.hook:
        return run_hook_mode()

    claude_dir = Path.home() / ".claude" / "projects"
    if not claude_dir.exists():
        sys.exit("Claude projects directory not found")

    if args.project:
        dirs = [claude_dir / args.project]
    else:
        dirs = [
            d for d in claude_dir.iterdir()
            if d.is_dir() and (d / "sessions-index.json").exists()
        ]

    totals = {"orphaned": 0, "dead": 0, "collisions": 0}
    results = []

    for d in dirs:
        s = repair_project(d, args.fix, args.verbose)
        results.append((d, s))
        if "error" not in s:
            for k in totals:
                totals[k] += s[k]

    if args.quiet and all(v == 0 for v in totals.values()):
        return

    print("Session Index Repair Report")
    print("=" * 60)
    if not args.fix:
        print("DRY-RUN MODE (use --fix to apply changes)\n")

    for d, s in results:
        if "error" in s:
            print(f"\n{d.name}: {s['error']}", file=sys.stderr)
            continue
        print(f"\nProject: {d.name}")
        print(f"  Indexed: {s['indexed']}, On disk: {s['on_disk']}")
        print(f"  Orphaned: {s['orphaned']}, Dead: {s['dead']}")
        print(f"  Collisions: {s['collisions']}")
        if args.fix and s.get("fixed"):
            print(f"  -> Repaired ({s['new_total']} total)")

    print(f"\n{'='*60}")
    print(f"Totals: {totals}")
    if not args.fix and any(v > 0 for v in totals.values()):
        print("Run with --fix to repair")


if __name__ == "__main__":
    main()

Usage

# One-time fix (dry-run first, then apply)
python repair-sessions-index.py
python repair-sessions-index.py --fix

# Auto-fix on every session start via hook (see below)

Auto-fix via SessionStart hook

Add to your ~/.claude/settings.json to auto-repair on every CC launch:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python /path/to/repair-sessions-index.py --hook",
            "timeout": 15
          }
        ]
      }
    ]
  }
}

The --hook flag consumes stdin, auto-fixes silently, and outputs {"continue":true,"suppressOutput":true}. Only prints to stderr when repairs are made. Index is repaired before your prompt appears — so --resume always works against a current index.

Note from #23614: In v2.1.34, the /resume picker may scan .jsonl files by recency instead of reading sessions-index.json. The index repair still helps for claude --resume "name" (CLI flag) which matches against customTitle.

[bosmadev]

Update: Published the repair script as open-source: bosmadev/claude — scripts/repair-sessions-index.py

Runs as SessionStart hook, auto-finds orphaned .jsonl session files and re-indexes them. See #23614 for latest findings on how /resume actually works in v2.1.31+.