Add claude-backup CLI implementation

- Click-based CLI: list, export, export-all
- Modules: scanner (project discovery), parser (JSONL), exporter (Markdown)
- Test suite: 42 tests, 93% coverage
- GitHub Actions CI for Python 3.10/3.11/3.12
- Test fixtures with edge cases: unicode, malformed JSON, empty files, missing index

Author: sedelev

.github/workflows/test.yml

@@ -0,0 +1,34 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package + dev deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run pytest
+        run: pytest -v --cov=claude_backup --cov-report=term-missing
+
+      - name: Smoke-test CLI
+        run: claude-backup --help

.gitignore

@@ -0,0 +1,32 @@
+# Real Claude data — never commit
+.claude/
+**/.claude/projects/
+
+# Local backup output
+backups/
+/backups/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+.eggs/
+build/
+dist/
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+.venv/
+venv/
+env/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/
+*.swp

claude_backup/__init__.py

@@ -0,0 +1,3 @@
+"""claude-backup: Export Claude Code session history to Markdown."""
+
+__version__ = "0.1.0"

claude_backup/cli.py

@@ -0,0 +1,173 @@
+"""CLI entry point for claude-backup."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from . import __version__
+from .exporter import export_session
+from .scanner import ProjectInfo, get_claude_home, scan_projects
+
+
+@click.group(help="Export Claude Code session history to Markdown.")
+@click.version_option(__version__, prog_name="claude-backup")
+@click.option(
+    "--claude-home",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Override the Claude projects root (default: ~/.claude/projects).",
+)
+@click.pass_context
+def main(ctx: click.Context, claude_home: Path | None) -> None:
+    ctx.ensure_object(dict)
+    ctx.obj["claude_home"] = claude_home
+
+
+@main.command("list", help="List all discovered sessions.")
+@click.pass_context
+def list_cmd(ctx: click.Context) -> None:
+    projects = _safe_scan(ctx.obj.get("claude_home"))
+    rows = _flatten_sessions(projects)
+
+    if not rows:
+        click.echo("No sessions found.")
+        return
+
+    headers = ["Project", "Session ID", "First Prompt", "Msg Count", "Created", "Git Branch"]
+    table_rows = [
+        [
+            r.project,
+            r.session_id,
+            _truncate(r.first_prompt, 40),
+            str(r.message_count),
+            r.created or "-",
+            r.git_branch or "-",
+        ]
+        for r in rows
+    ]
+    click.echo(_format_table(headers, table_rows))
+
+
+@main.command("export", help="Export a single session by ID.")
+@click.argument("session_id")
+@click.option(
+    "--output",
+    "-o",
+    type=click.Path(path_type=Path),
+    default=Path("./backups"),
+    help="Output directory (default: ./backups/).",
+)
+@click.pass_context
+def export_cmd(ctx: click.Context, session_id: str, output: Path) -> None:
+    projects = _safe_scan(ctx.obj.get("claude_home"))
+    target = None
+    for project in projects:
+        for session in project.sessions:
+            if session.session_id == session_id:
+                target = session
+                break
+        if target:
+            break
+
+    if target is None:
+        click.echo(f"Session not found: {session_id}", err=True)
+        sys.exit(2)
+
+    if target.jsonl_path is None or not target.jsonl_path.exists():
+        click.echo(
+            f"Session {session_id} has no JSONL file on disk.", err=True
+        )
+        sys.exit(2)
+
+    out = export_session(target, output)
+    click.echo(f"Exported: {out}")
+
+
+@main.command("export-all", help="Export every discovered session.")
+@click.option(
+    "--output",
+    "-o",
+    type=click.Path(path_type=Path),
+    default=Path("./backups"),
+    help="Output directory (default: ./backups/).",
+)
+@click.pass_context
+def export_all_cmd(ctx: click.Context, output: Path) -> None:
+    projects = _safe_scan(ctx.obj.get("claude_home"))
+    exported = 0
+    skipped = 0
+
+    for project in projects:
+        project_out = output / project.name
+        for session in project.sessions:
+            if session.jsonl_path is None or not session.jsonl_path.exists():
+                click.echo(
+                    f"Skip {project.name}/{session.session_id}: no JSONL file",
+                    err=True,
+                )
+                skipped += 1
+                continue
+            try:
+                path = export_session(session, project_out)
+                click.echo(f"Exported: {path}")
+                exported += 1
+            except Exception as e:  # pragma: no cover - defensive
+                click.echo(
+                    f"Failed {project.name}/{session.session_id}: {e}", err=True
+                )
+                skipped += 1
+
+    click.echo(f"\nDone. Exported: {exported}, skipped: {skipped}")
+
+
+def _safe_scan(claude_home: Path | None) -> list[ProjectInfo]:
+    try:
+        return scan_projects(claude_home)
+    except FileNotFoundError:
+        root = get_claude_home(claude_home)
+        click.echo(
+            f"Error: Claude projects directory not found at {root}.\n"
+            f"Have you used Claude Code on this machine?",
+            err=True,
+        )
+        sys.exit(1)
+    except NotADirectoryError as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+
+def _flatten_sessions(projects):
+    rows = []
+    for project in projects:
+        for session in project.sessions:
+            rows.append(session)
+    return rows
+
+
+def _truncate(text: str, length: int) -> str:
+    if not text:
+        return "-"
+    text = text.replace("\n", " ").strip()
+    if len(text) <= length:
+        return text
+    return text[: length - 1] + "…"
+
+
+def _format_table(headers: list[str], rows: list[list[str]]) -> str:
+    widths = [len(h) for h in headers]
+    for row in rows:
+        for i, cell in enumerate(row):
+            widths[i] = max(widths[i], len(cell))
+
+    def line(cells: list[str]) -> str:
+        return "  ".join(cell.ljust(widths[i]) for i, cell in enumerate(cells))
+
+    sep = "  ".join("-" * w for w in widths)
+    return "\n".join([line(headers), sep, *[line(r) for r in rows]])
+
+
+if __name__ == "__main__":
+    main()

claude_backup/exporter.py

@@ -0,0 +1,150 @@
+"""Exporter: Convert parsed sessions to Markdown files."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .parser import Message, parse_session
+from .scanner import SessionInfo
+
+
+ROLE_LABELS = {
+    "user": "User",
+    "assistant": "Assistant",
+    "tool_result": "Tool Result",
+    "system": "System",
+}
+
+
+def export_session(
+    session: SessionInfo,
+    output_dir: Path,
+    now: datetime | None = None,
+) -> Path:
+    """Export a single session to Markdown. Returns path to the written file."""
+    if session.jsonl_path is None or not session.jsonl_path.exists():
+        raise FileNotFoundError(
+            f"Session JSONL not found for {session.session_id}"
+        )
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    messages = parse_session(session.jsonl_path)
+
+    date_prefix = _date_prefix(session, messages)
+    filename = f"{date_prefix}--{session.session_id}.md"
+    out_path = output_dir / filename
+
+    md = render_markdown(session, messages, now=now)
+    out_path.write_text(md, encoding="utf-8")
+    return out_path
+
+
+def render_markdown(
+    session: SessionInfo,
+    messages: list[Message],
+    now: datetime | None = None,
+) -> str:
+    """Build the full Markdown document for a session."""
+    now = now or datetime.now(timezone.utc)
+
+    branch = session.git_branch or _first_non_empty(m.git_branch for m in messages)
+    model = _first_non_empty(m.model for m in messages)
+    msg_count = session.message_count or len(messages)
+
+    frontmatter = _render_frontmatter(
+        project=session.project,
+        session_id=session.session_id,
+        branch=branch,
+        model=model,
+        messages=msg_count,
+        exported_at=_format_iso(now),
+    )
+
+    title_branch = branch or "no-branch"
+    header = f"# {session.project} / {title_branch} / {session.session_id}\n"
+
+    body = _render_body(messages)
+
+    parts = [frontmatter, "", header, body]
+    return "\n".join(parts).rstrip() + "\n"
+
+
+def _render_frontmatter(**fields) -> str:
+    lines = ["---"]
+    for key, value in fields.items():
+        lines.append(f"{key}: {_yaml_scalar(value)}")
+    lines.append("---")
+    return "\n".join(lines)
+
+
+_YAML_INDICATOR_PREFIXES = ("'", '"', "[", "{", "&", "*", "!", "|", ">", "%", "@", "`", "?", "-")
+
+
+def _yaml_scalar(value) -> str:
+    if isinstance(value, int):
+        return str(value)
+    s = str(value) if value is not None else ""
+    if s == "":
+        return '""'
+    needs_quoting = (
+        "\n" in s
+        or '"' in s
+        or ": " in s
+        or " #" in s
+        or s.startswith(_YAML_INDICATOR_PREFIXES)
+        or s.endswith(":")
+        or s.strip() != s
+    )
+    if needs_quoting:
+        escaped = s.replace("\\", "\\\\").replace('"', '\\"')
+        return f'"{escaped}"'
+    return s
+
+
+def _render_body(messages: list[Message]) -> str:
+    if not messages:
+        return "_No messages._\n"
+
+    sections: list[str] = []
+    for msg in messages:
+        label = ROLE_LABELS.get(msg.role, msg.role.capitalize())
+        time_str = _format_short_time(msg.timestamp)
+        heading = f"## {label} ({time_str})" if time_str else f"## {label}"
+        body = msg.content.rstrip() if msg.content else "_(empty)_"
+        sections.append(f"{heading}\n{body}\n")
+    return "\n".join(sections)
+
+
+def _format_iso(dt: datetime) -> str:
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _format_short_time(timestamp: str) -> str:
+    if not timestamp:
+        return ""
+    try:
+        dt = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+    except ValueError:
+        return timestamp
+    return dt.strftime("%H:%M:%S")
+
+
+def _date_prefix(session: SessionInfo, messages: list[Message]) -> str:
+    candidate = session.created or _first_non_empty(m.timestamp for m in messages)
+    if candidate:
+        try:
+            dt = datetime.fromisoformat(candidate.replace("Z", "+00:00"))
+            return dt.strftime("%Y-%m-%d")
+        except ValueError:
+            pass
+    return datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+
+def _first_non_empty(values) -> str:
+    for v in values:
+        if v:
+            return v
+    return ""