Add --minimal export mode (dialogue-only mini-log)

New flag '--minimal' on 'export' and 'export-all' produces a streamlined
mini-log containing only user prompts and assistant text replies. Drops:
- tool_use blocks (assistant calling Bash/Edit/etc.)
- tool_result messages (the user-role wrappers Claude gets back)
- thinking blocks (visible reasoning text)
- image / unknown blocks

Output filename gets a '.minimal.md' suffix so both modes can coexist for
the same session. Frontmatter records 'mode: dialogue-only' and an
adjusted 'messages' count reflecting only the kept turns.

On a real 296-message session the minimal export is roughly half the size.

parser.py adds 'dialogue_text(msg)' and 'is_dialogue_message(msg)' helpers
that the exporter uses when minimal=True. 9 new tests; 64/64 pass.

Author: sedelev

claude_backup/cli.py

@@ -59,8 +59,17 @@ def list_cmd(ctx: click.Context) -> None:
     default=Path("./backups"),
     help="Output directory (default: ./backups/).",
 )
+@click.option(
+    "--minimal",
+    is_flag=True,
+    default=False,
+    help="Mini-log: only user/assistant dialogue, no tool calls or reasoning. "
+    "Filename gets a .minimal.md suffix so it doesn't overwrite the full export.",
+)
 @click.pass_context
-def export_cmd(ctx: click.Context, session_id: str, output: Path) -> None:
+def export_cmd(
+    ctx: click.Context, session_id: str, output: Path, minimal: bool
+) -> None:
     projects = _safe_scan(ctx.obj.get("claude_home"))
     matches = []
     for project in projects:
@@ -87,7 +96,7 @@ def export_cmd(ctx: click.Context, session_id: str, output: Path) -> None:
         )
         sys.exit(2)
 
-    out = export_session(target, output)
+    out = export_session(target, output, minimal=minimal)
     click.echo(f"Exported: {out}")
 
 
@@ -99,8 +108,14 @@ def export_cmd(ctx: click.Context, session_id: str, output: Path) -> None:
     default=Path("./backups"),
     help="Output directory (default: ./backups/).",
 )
+@click.option(
+    "--minimal",
+    is_flag=True,
+    default=False,
+    help="Mini-log mode: only user/assistant dialogue, no tools or reasoning.",
+)
 @click.pass_context
-def export_all_cmd(ctx: click.Context, output: Path) -> None:
+def export_all_cmd(ctx: click.Context, output: Path, minimal: bool) -> None:
     projects = _safe_scan(ctx.obj.get("claude_home"))
     exported = 0
     skipped = 0
@@ -116,7 +131,7 @@ def export_all_cmd(ctx: click.Context, output: Path) -> None:
                 skipped += 1
                 continue
             try:
-                path = export_session(session, project_out)
+                path = export_session(session, project_out, minimal=minimal)
                 click.echo(f"Exported: {path}")
                 exported += 1
             except Exception as e:  # pragma: no cover - defensive

claude_backup/exporter.py

@@ -5,7 +5,7 @@
 from datetime import datetime, timezone
 from pathlib import Path
 
-from .parser import Message, parse_session
+from .parser import Message, dialogue_text, is_dialogue_message, parse_session
 from .scanner import SessionInfo
 
 
@@ -21,8 +21,13 @@ def export_session(
     session: SessionInfo,
     output_dir: Path,
     now: datetime | None = None,
+    minimal: bool = False,
 ) -> Path:
-    """Export a single session to Markdown. Returns path to the written file."""
+    """Export a single session to Markdown. Returns path to the written file.
+
+    When `minimal=True`, drops tool calls, tool results, and reasoning blocks —
+    keeps only the user/assistant dialogue. Filename gets a `.minimal.md` suffix.
+    """
     if session.jsonl_path is None or not session.jsonl_path.exists():
         raise FileNotFoundError(
             f"Session JSONL not found for {session.session_id}"
@@ -32,10 +37,11 @@ def export_session(
     messages = parse_session(session.jsonl_path)
 
     date_prefix = _date_prefix(session, messages)
-    filename = f"{date_prefix}--{session.session_id}.md"
+    suffix = ".minimal.md" if minimal else ".md"
+    filename = f"{date_prefix}--{session.session_id}{suffix}"
     out_path = output_dir / filename
 
-    md = render_markdown(session, messages, now=now)
+    md = render_markdown(session, messages, now=now, minimal=minimal)
     out_path.write_text(md, encoding="utf-8")
     return out_path
 
@@ -44,13 +50,16 @@ def render_markdown(
     session: SessionInfo,
     messages: list[Message],
     now: datetime | None = None,
+    minimal: bool = False,
 ) -> str:
     """Build the full Markdown document for a session."""
     now = now or datetime.now(timezone.utc)
 
+    visible = [m for m in messages if is_dialogue_message(m)] if minimal else messages
+
     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)
+    msg_count = len(visible) if minimal else (session.message_count or len(messages))
 
     fm_fields = {
         "project": session.project,
@@ -60,6 +69,8 @@ def render_markdown(
         "messages": msg_count,
         "exported_at": _format_iso(now),
     }
+    if minimal:
+        fm_fields["mode"] = "dialogue-only"
     if session.title:
         fm_fields["title"] = session.title
     frontmatter = _render_frontmatter(**fm_fields)
@@ -70,7 +81,7 @@ def render_markdown(
     else:
         header = f"# {session.project} / {title_branch} / {session.session_id}\n"
 
-    body = _render_body(messages)
+    body = _render_body(visible, minimal=minimal)
 
     parts = [frontmatter, "", header, body]
     return "\n".join(parts).rstrip() + "\n"
@@ -108,7 +119,7 @@ def _yaml_scalar(value) -> str:
     return s
 
 
-def _render_body(messages: list[Message]) -> str:
+def _render_body(messages: list[Message], minimal: bool = False) -> str:
     if not messages:
         return "_No messages._\n"
 
@@ -117,7 +128,11 @@ def _render_body(messages: list[Message]) -> str:
         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)_"
+        if minimal:
+            text = dialogue_text(msg).rstrip()
+        else:
+            text = msg.content.rstrip() if msg.content else ""
+        body = text or "_(empty)_"
         sections.append(f"{heading}\n{body}\n")
     return "\n".join(sections)
 

claude_backup/parser.py

@@ -181,6 +181,37 @@ def _normalize_content(content) -> str:
     return str(content)
 
 
+def dialogue_text(msg: "Message") -> str:
+    """Extract only human-facing text from a message: no tool_use, no tool_result,
+    no thinking, no images. Used by `--minimal` export mode."""
+    nested = msg.raw.get("message") if isinstance(msg.raw, dict) else None
+    raw = nested if isinstance(nested, dict) else msg.raw
+    content = raw.get("content") if isinstance(raw, dict) else None
+
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, list):
+        return ""
+
+    parts: list[str] = []
+    for block in content:
+        if isinstance(block, str):
+            parts.append(block)
+            continue
+        if not isinstance(block, dict):
+            continue
+        if block.get("type") == "text":
+            text = block.get("text", "")
+            if isinstance(text, str) and text:
+                parts.append(text)
+    return "\n".join(parts)
+
+
+def is_dialogue_message(msg: "Message") -> bool:
+    """True if the message has any visible human-facing dialogue text."""
+    return bool(dialogue_text(msg).strip())
+
+
 def session_summary(jsonl_path: Path) -> dict:
     """Quick stats about a session: message count, first prompt, model."""
     messages = parse_session(jsonl_path)

tests/test_minimal.py

@@ -0,0 +1,131 @@
+"""Tests for --minimal export mode (dialogue-only output)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from click.testing import CliRunner
+
+from claude_backup.cli import main
+from claude_backup.exporter import export_session, render_markdown
+from claude_backup.parser import dialogue_text, is_dialogue_message, parse_session
+from claude_backup.scanner import scan_projects
+
+
+def _real_session(claude_home: Path):
+    projects = scan_projects(claude_home)
+    real = next(p for p in projects if p.name == "real-format-project")
+    return real.sessions[0]
+
+
+def test_dialogue_text_strips_tool_use(claude_home: Path) -> None:
+    """In `real-001.jsonl` the assistant says 'Installing now.' then makes a tool_use call.
+    `dialogue_text` should keep the text and drop the tool_use marker."""
+    f = claude_home / "real-format-project" / "real-001.jsonl"
+    messages = parse_session(f)
+    assistant_first = next(m for m in messages if m.role == "assistant")
+    assert dialogue_text(assistant_first) == "Installing now."
+    assert "[tool_use:" not in dialogue_text(assistant_first)
+
+
+def test_dialogue_text_strips_tool_result(claude_home: Path) -> None:
+    """The user 'tool_result' message should produce empty dialogue text."""
+    f = claude_home / "real-format-project" / "real-001.jsonl"
+    messages = parse_session(f)
+    tool_result_user = [
+        m for m in messages if m.role == "user" and "installed" in m.content
+    ][0]
+    assert dialogue_text(tool_result_user) == ""
+    assert is_dialogue_message(tool_result_user) is False
+
+
+def test_dialogue_text_strips_thinking(tmp_path: Path) -> None:
+    f = tmp_path / "x.jsonl"
+    f.write_text(
+        '{"role":"assistant","content":['
+        '{"type":"thinking","thinking":"weighing options","signature":"sig"},'
+        '{"type":"text","text":"answer"}'
+        ']}\n'
+    )
+    messages = parse_session(f)
+    assert dialogue_text(messages[0]) == "answer"
+
+
+def test_is_dialogue_message_true_for_user_prompt(claude_home: Path) -> None:
+    f = claude_home / "real-format-project" / "real-001.jsonl"
+    messages = parse_session(f)
+    real_user = next(m for m in messages if m.role == "user")
+    assert is_dialogue_message(real_user) is True
+
+
+def test_render_markdown_minimal_drops_tool_messages(claude_home: Path) -> None:
+    session = _real_session(claude_home)
+    messages = parse_session(session.jsonl_path)
+    md = render_markdown(session, messages, minimal=True)
+
+    assert "[tool_use:" not in md
+    assert "tool_result" not in md
+    assert "installed" not in md  # tool_result content
+    assert "Installing now." in md
+    assert "Done." in md
+    assert "install superpowers skill" in md
+    assert "mode: dialogue-only" in md
+
+
+def test_render_markdown_full_keeps_tool_messages(claude_home: Path) -> None:
+    """Sanity: without minimal flag, tool messages are still there."""
+    session = _real_session(claude_home)
+    messages = parse_session(session.jsonl_path)
+    md = render_markdown(session, messages, minimal=False)
+
+    assert "[tool_use: Bash]" in md
+    assert "installed" in md
+    assert "mode: dialogue-only" not in md
+
+
+def test_export_session_minimal_writes_separate_file(
+    claude_home: Path, tmp_path: Path
+) -> None:
+    session = _real_session(claude_home)
+    full_path = export_session(session, tmp_path, minimal=False)
+    minimal_path = export_session(session, tmp_path, minimal=True)
+
+    assert full_path != minimal_path
+    assert full_path.name.endswith(".md")
+    assert not full_path.name.endswith(".minimal.md")
+    assert minimal_path.name.endswith(".minimal.md")
+
+    assert "[tool_use:" in full_path.read_text(encoding="utf-8")
+    assert "[tool_use:" not in minimal_path.read_text(encoding="utf-8")
+
+
+def test_cli_export_with_minimal_flag(claude_home: Path, tmp_path: Path) -> None:
+    runner = CliRunner()
+    out = tmp_path / "backups"
+    result = runner.invoke(
+        main,
+        [
+            "--claude-home",
+            str(claude_home),
+            "export",
+            "real-001",
+            "--output",
+            str(out),
+            "--minimal",
+        ],
+    )
+    assert result.exit_code == 0, result.output
+    files = list(out.glob("*.minimal.md"))
+    assert len(files) == 1
+
+
+def test_cli_export_all_with_minimal_flag(claude_home: Path, tmp_path: Path) -> None:
+    runner = CliRunner()
+    out = tmp_path / "all"
+    result = runner.invoke(
+        main,
+        ["--claude-home", str(claude_home), "export-all", "--output", str(out), "--minimal"],
+    )
+    assert result.exit_code == 0, result.output
+    minimal_files = list(out.rglob("*.minimal.md"))
+    assert len(minimal_files) >= 1