🌀
← Back to Articles & Artefacts
artefactssouth

Implementation Roadmap: claude-session-manager

IAIP Research
jg-260110-osm-claude-code-a9af9be8-df86-4285-a367

Implementation Roadmap: claude-session-manager

4-week sprint to production for session extraction, indexing, visualization, and export.

Overview

Goal: Build a CLI tool + Python library that extracts Claude Code sessions, detects forks, enables search, and exports to Markdown.

Team Size: 1 architect (implementation) + code review Total Hours: ~40 hours over 4 weeks Deliverable: PyPI package with CLI, library API, and documentation

Phase 1: Foundation (Week 1)

Duration: 6 hours Focus: Data extraction and basic indexing

Sprint Tasks

Task 1.1: Directory Parsing (1 hour)

  • Write SessionMetadataExtractor class
  • Implement directory name decoding (-home-user-project → /home/user/project)
  • Extract all session directories from ~/.claude/projects/
  • Parse conversation.jsonl line by line
  • Unit tests for 10+ sample directory names

Deliverable: Can list all sessions with metadata

```python extractor = SessionMetadataExtractor() sessions = extractor.extract_all_sessions()

returns: [{'session_id': 'xxx', 'launch_path': '/home/user/project', ...}, ...]

```

Task 1.2: SQLite Indexing (2.5 hours)

  • Design schema (sessions, messages, forks tables)
  • Create SessionIndexDB class with init_db()
  • Implement index_sessions() for bulk insertion
  • Add indexes: (session_id, created_at), (launch_path), full-text search (FTS5)
  • Test insert performance on 100+ sessions

Deliverable: All sessions indexed and searchable

```python index = SessionIndexDB() index.index_sessions(sessions) results = index.search_messages("pattern") # <100ms on 10K messages ```

Task 1.3: Fork Detection (1.5 hours)

  • Write ForkDetector class
  • Scan for resume markers in assistant messages
  • Build parent→child graph
  • Test on sessions with known fork patterns

Deliverable: Fork relationships detected

```python detector = ForkDetector(sessions) all_forks = detector.detect_all_forks()

returns: {'session-1': [fork1, fork2], ...}

```

Task 1.4: Markdown Export (1 hour)

  • Write SessionMarkdownExporter class
  • Export metadata header (duration, tokens, tools)
  • Preserve message structure, code blocks, thinking tags
  • Test on 5 representative sessions

Deliverable: Human-readable Markdown files

```python exporter = SessionMarkdownExporter(session) exporter.save("/tmp/session.md")

outputs: readable markdown with full metadata

```

Phase 1 Checkpoint

  • Can extract any session to Python dict
  • Can index 100+ sessions in <1 second
  • Can search across 10K messages in <100ms
  • Can export session to Markdown
  • All code has basic unit tests

Completion Criteria: python phase1_workflow.py runs end-to-end without errors

Phase 2: Discovery & Visualization (Weeks 2-3)

Duration: 12 hours Focus: CLI tool and visual inspection

Sprint Tasks

Task 2.1: CLI Foundation (3 hours)

  • Setup Click framework for CLI commands
  • Implement claude-session list [--dir] [--days]
  • Implement claude-session search <query>
  • Implement claude-session export <id> [--format]
  • Add --help and error messages

Deliverable: CLI tool with 3 commands

```bash $ claude-session list --dir=/home/user/project Session ID Created Path Messages -home-user-project-1 2026-01-10 21:00 /home/user/project 45 -home-user-project-2 2026-01-09 19:30 /home/user/project 12

$ claude-session search "pattern matching" Found 3 messages in 2 sessions: session-1: msg #12 - "pattern matching example"

$ claude-session export session-1 --format=md --output=./session.md ✓ Exported to ./session.md ```

Task 2.2: Fork Visualization (4 hours)

  • Write SessionTreeVisualizer using Graphviz
  • Generate DOT format for all sessions
  • Color nodes by status (active/completed/archived)
  • Render to SVG/PNG using dot command
  • Implement claude-session tree <id> command

Deliverable: Visual fork hierarchies

```bash $ claude-session tree session-1

Outputs DOT and renders to SVG showing all forks

digraph SessionTree { "session-1" -> "session-2"; "session-1" -> "session-3"; "session-3" -> "session-4"; } ```

Task 2.3: Advanced Search (3 hours)

  • Implement full-text search with ranking
  • Add filtering by role (user/assistant)
  • Add filtering by date range
  • Implement --limit parameter
  • Add relevance scoring

Deliverable: Powerful search with filters

```bash $ claude-session search "bug in parser" --role=assistant --days=7 --limit=10 ```

Task 2.4: Session Info Command (2 hours)

  • Implement claude-session info <id>
  • Show full metadata (path, dates, tokens, tools)
  • List fork relationships
  • Show token distribution over time

Deliverable: Detailed session inspection

```bash $ claude-session info session-1 ID: -home-user-project-1 Path: /home/user/project Created: 2026-01-10 21:00:00 UTC Updated: 2026-01-10 23:45:00 UTC Duration: 2h 45m Messages: 45 (23 user, 22 assistant) Tokens: 12,345 in, 45,678 out (58,023 total) Tools: file_write, search_web, generate_image Forks: session-2, session-3 Forked From: session-1-original ```

Phase 2 Checkpoint

  • CLI tool works with all commands
  • Fork visualization renders correctly
  • Search performance acceptable on 100+ sessions
  • All commands have helpful output

Completion Criteria: Demo 10-minute walkthrough of discovering sessions and exporting

Phase 3: Production Package (Weeks 3-4)

Duration: 24 hours Focus: Packaging, testing, documentation

Sprint Tasks

Task 3.1: Python Package Setup (3 hours)

  • Create setup.py and pyproject.toml
  • Define entry points for claude-session CLI command
  • Add version management
  • Setup __init__.py for library imports
  • Prepare PyPI metadata

Deliverable: Installable package

```bash $ pip install claude-session-manager $ claude-session --version claude-session-manager 0.1.0 ```

Task 3.2: Comprehensive Testing (6 hours)

  • Unit tests for extractor (10+ tests)
  • Unit tests for indexer (8+ tests)
  • Unit tests for fork detector (5+ tests)
  • Integration tests for CLI (5+ tests)
  • Test with real session data (100+ sessions)
  • Coverage reporting (target: >80%)

Deliverable: Tested, production-ready code

```bash $ pytest -v test_extractor.py::test_decode_directory_name PASSED test_indexer.py::test_search_performance PASSED ... ======== 28 passed in 3.45s ======== Coverage: 87% ```

Task 3.3: Documentation (6 hours)

  • README.md with installation, usage, examples
  • API documentation (docstrings for all classes)
  • Tutorial: "Extract Your First Session"
  • Troubleshooting section
  • Contributing guidelines
  • Example notebooks (Jupyter)

Deliverable: Complete documentation

``` docs/ ├── README.md ├── INSTALL.md ├── USAGE.md ├── API.md ├── TUTORIAL.md ├── TROUBLESHOOTING.md └── examples/ ├── basic_extraction.ipynb ├── search_and_filter.ipynb └── visualization.ipynb ```

Task 3.4: MCP Integration (6 hours)

  • Implement MCP resource provider for sessions
  • Expose sessions as queryable resources
  • Enable agent-to-agent session access
  • Write MCP spec documentation
  • Test with Claude via MCP

Deliverable: Agents can query session metadata

```python

Claude can now query:

"Get me the fork tree for session-1"

"Search for 'pattern matching' in all sessions"

"Export session-2 to markdown"

```

Task 3.5: Release Preparation (3 hours)

  • Final code review
  • Changelog
  • Version bump (0.1.0 → 0.1.0)
  • Tag release in git
  • Push to PyPI
  • Publish GitHub release

Deliverable: Public package

```bash $ pip install claude-session-manager==0.1.0 Successfully installed claude-session-manager-0.1.0 ```

Phase 3 Checkpoint

  • Package installs cleanly
  • All tests pass
  • Documentation complete and tested
  • MCP integration working
  • Ready for team use

Completion Criteria: Users can pip install and immediately start extracting sessions

Weekly Breakdown

Week 1: Foundation

  • Monday: Task 1.1 (parsing)
  • Tuesday: Task 1.2 (indexing)
  • Wednesday: Task 1.3 (forks) + 1.4 (export)
  • Thursday: Testing, bug fixes
  • Friday: Checkpoint, team review

Week 2: CLI & Visualization

  • Monday: Task 2.1 (CLI foundation)
  • Tuesday: Task 2.2 (visualization) - Part A
  • Wednesday: Task 2.2 (visualization) - Part B
  • Thursday: Task 2.3 (search)
  • Friday: Task 2.4 (info command), checkpoint

Week 3: Production & Testing

  • Monday: Task 3.1 (packaging)
  • Tuesday: Task 3.2 (testing) - Part A
  • Wednesday: Task 3.2 (testing) - Part B
  • Thursday: Task 3.3 (documentation)
  • Friday: Integration testing, bug fixes

Week 4: Finalization & Release

  • Monday: Task 3.4 (MCP) - Part A
  • Tuesday: Task 3.4 (MCP) - Part B
  • Wednesday: Task 3.5 (release prep)
  • Thursday: Final review, PyPI push
  • Friday: Team walkthrough, gather feedback

Definition of Done

For each task to be considered complete:

  • Code written and locally tested
  • Unit tests pass (>80% coverage)
  • Integration tests pass
  • Code reviewed (syntax, logic, performance)
  • Documentation updated
  • No console warnings or errors
  • Performance benchmarks met (if applicable)

Success Metrics

By end of Week 4:

✓ Extract 100+ sessions in <1 second ✓ Search 10K messages in <100ms ✓ Export any session to Markdown in <1 second ✓ Visualize fork trees with >50 nodes ✓ CLI tool with <5 commands (list, search, export, tree, info) ✓ >80% test coverage ✓ Published on PyPI ✓ Documentation complete ✓ MCP integration working ✓ Zero known bugs

Risk Mitigation

Risk: Fork detection heuristic is unreliable

Mitigation: Combine resume markers + timestamp analysis + manual linking UI. Document false positives.

Risk: SQLite performance plateaus at 100K+ messages

Mitigation: Profile early (Week 1). Consider PostgreSQL or Redis if bottleneck found. Cache frequent queries.

Risk: Directory encoding breaks on edge cases

Mitigation: Test extensively with symlinks, special characters, Unicode paths. Add validation.

Risk: MCP integration adds complexity

Mitigation: Implement as optional plugin (Week 4). Can be deferred to v0.2 if time is tight.

Tools & Dependencies

Required

  • Python 3.9+
  • SQLite3 (built-in)
  • Click (CLI framework)
  • Graphviz (for visualization)

Optional

  • pytest (testing)
  • sphinx (documentation)
  • MCP SDK (agent integration)

Development

  • git, GitHub
  • mypy (type checking)
  • black (formatting)

Team Checkpoints

End of Week 1

Question: Can we extract and index sessions reliably? Acceptance: Phase 1 checkpoint met, no data loss, performance acceptable

End of Week 2

Question: Can users discover and visualize sessions easily? Acceptance: Phase 2 checkpoint met, CLI is intuitive, visualization is clear

End of Week 3

Question: Is the code production-ready and tested? Acceptance: Phase 3 checkpoint met, >80% test coverage, documentation complete

End of Week 4

Question: Can we release and support this tool? Acceptance: All success metrics met, PyPI release, team walkthrough, feedback captured

Post-Launch (v0.2 and beyond)

Planned Features

  • Merge branches back together
  • Session templates (reusable starting contexts)
  • Web dashboard (optional)
  • GitOps integration (auto-commit exported sessions)
  • Slack notifications on session completion
  • Cost tracking (token usage → $ spent)

Community Features (if demand)

  • Shared session repositories
  • Session templates from community
  • Agent-to-agent session marketplace
  • Public session browser (with permission)

Budget Summary

PhaseTasksHoursNotes
146Extraction, indexing, export
2412CLI, visualization, search
3524Testing, packaging, docs, MCP
Total13404 weeks, ~10 hours/week

Success Criteria Checklist

  • Phase 1: End-to-end extraction pipeline works
  • Phase 2: CLI is intuitive, visualization is clear
  • Phase 3: Code is tested, documented, published
  • MCP integration functional
  • Zero critical bugs
  • Team can use tool independently
  • Documentation complete and tested
  • Performance acceptable (under Phase 2 metrics)

Launch Ready: All items checked ✓