Support subagents directory structure (Claude Code 2.1.2+)

[cboos]

Part 1 of Support new transcript structure (2026-01). Closes #79

Summary

• Add support for loading agent transcripts from the new {session-uuid}/subagents/ directory structure introduced in Claude Code 2.1.2
• Maintains backward compatibility with legacy location (agent files in same directory as session)

Changes

• converter.py: Check both legacy and new subagents directory when loading agent files
• New unit test for the subagents directory structure
• Add real project test data (-src-experiments-claude_p) with the new structure

Test plan

• Existing sidechain agent tests pass (legacy location)
• New test_subagents_directory_structure test validates new location
• Benchmark test confirms real project with subagents loads correctly

Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Improved agent transcript loading to support Claude Code 2.1+ session/subagents layout while preserving legacy compatibility.

• Tests

  • Added tests validating subagent directory handling, message counts, sidechain detection, and rendered output.
  • Included multiple new JSONL session artifacts to exercise WebSearch, tools, subagent, and session workflows.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds support for discovering Claude Code 2.1+ subagent files by checking a session-scoped .../<session_basename>/subagents/agent-<id>.jsonl path when the legacy agent-<id>.jsonl path is absent. Includes new test fixtures and a test validating the session/subagents layout and rendering.

Changes

Cohort / File(s)	Summary
Subagent Loading Logic claude_code_log/converter.py	Try legacy agent-<id>.jsonl path first; if missing, derive and check parent_dir / <session_file_stem> / subagents / agent-<id>.jsonl; use found subagent path while preserving self-reference checks and existing loading flow.
Test Data Fixtures test/test_data/real_projects/-src-experiments-claude_p/256ba646-2c15-437a-98e9-4171aafd030e.jsonl, test/test_data/real_projects/-src-experiments-claude_p/29ccd257-68b1-427f-ae5f-6524b7cb6f20.jsonl, test/test_data/real_projects/-src-experiments-claude_p/2b4ed4c0-b905-41de-9238-273db3ec737a.jsonl, test/test_data/real_projects/-src-experiments-claude_p/94604a7b-062f-4369-bdf0-da948381c3e5.jsonl	Adds JSONL session transcripts (tool usage, search, summaries) used as test fixtures; no logic changes.
Subagent Directory Test test/test_sidechain_agents.py	Adds test_subagents_directory_structure which writes a main session file and a subagents/agent-*.jsonl file under a session-named directory, asserts loading from the session subagents path (legacy ignored), checks message counts/sidechain flags, and verifies HTML includes subagent content.

Sequence Diagram(s)

mermaid
sequenceDiagram
participant Converter as claude_code_log.converter
participant FS as Filesystem
participant Session as SessionFile (session.jsonl)
participant Subagent as SubagentsFile (agent-.jsonl)

Converter->>FS: locate legacy `agent-<id>.jsonl` in parent_dir
alt legacy exists
    FS-->>Converter: return legacy path
    Converter->>Subagent: load agent file
else legacy missing
    Converter->>Session: read session file name (stem)
    Converter->>FS: check `parent_dir / session_stem / subagents / agent-<id>.jsonl`
    alt subagent exists
        FS-->>Converter: return session-scoped subagent path
        Converter->>Subagent: load agent file
    else subagent missing
        FS-->>Converter: not found -> no subagent loaded
    end
end
Converter->>Converter: self-reference check & integrate into transcript

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• Support new transcript structure (2026-01) #79: Requests loading of agent/subagent transcripts from session/subagents/ layout — this PR implements that detection and loading.

Possibly related PRs

• Foldable messages #42: Also modifies agent/subagent transcript discovery/loading; closely related to the lookup changes here.

Poem

🐰 A tunnel through folders where subagents hide,
I hop through sessions to find them inside,
Legacy doors checked, new paths explored,
Now agent logs gather — a carrot-laden hoard! 🥕

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Support subagents directory structure (Claude Code 2.1.2+)' directly and clearly summarizes the main change: adding support for a new subagents directory structure in Claude Code 2.1.2+. It aligns with the primary objective of the PR and is specific enough to convey the key improvement.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}