fix: CLI parity with cursor-chat-browser-python, exclusion rules, state format (#11)

Closes #11

- Add --exclude-rules/-e to app.py and scripts/export.py (missing vs reference)
- Add utils/exclusion_rules.py ported from reference with claude-specific defaults
- Apply exclusion rules in api/export_api.py bulk export endpoint
- Fix use_reloader=False → platform-aware (sys.platform != "win32") in app.py
- Fix export_state.json format: add lastExportTime, exportedCount, exportDir
  alongside sessions sub-key; migrate legacy flat format transparently
- Add tests: test_cli_args.py, test_export_state.py, test_export_exclusion_filtering.py

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: wpak-ai

api/export_api.py

@@ -12,14 +12,26 @@
 from utils.session_stats import compute_stats
 from utils.md_exporter import session_to_markdown
 from utils.json_exporter import session_to_json
+from utils.exclusion_rules import build_searchable_text, is_excluded_by_rules
 
 export_bp = Blueprint("export", __name__)
 
 
+def _session_text_for_exclusion(session: dict) -> str:
+    """Extract a plain-text snippet from session messages for exclusion matching."""
+    parts = []
+    for msg in session.get("messages", []):
+        text = msg.get("text") or ""
+        if isinstance(text, str) and text.strip():
+            parts.append(text)
+    return "\n\n".join(parts)
+
+
 @export_bp.route("/api/export", methods=["POST"])
 def bulk_export():
     base = current_app.config.get("CLAUDE_PROJECTS_DIR") or get_claude_projects_dir()
     projects = list_projects(base)
+    rules = current_app.config.get("EXCLUSION_RULES") or []
 
     buf = io.BytesIO()
     count = 0
@@ -32,6 +44,18 @@ def bulk_export():
                     session = parse_session(sess_info["path"])
                     if session["title"] == "Untitled Session":
                         continue
+
+                    if rules:
+                        meta = session["metadata"]
+                        searchable = build_searchable_text(
+                            project_name=project.get("display_name") or project["name"],
+                            session_title=session["title"],
+                            model_names=list(meta.get("models_used") or []),
+                            content_snippet=_session_text_for_exclusion(session),
+                        )
+                        if is_excluded_by_rules(rules, searchable):
+                            continue
+
                     stats = compute_stats(session)
                     md = session_to_markdown(session, stats)
                     title_slug = _slugify(session["title"])[:60] or "session"

app.py

@@ -1,19 +1,28 @@
 """Flask app that serves the web GUI for browsing sessions."""
 
 import os
+import sys
 
 from flask import Flask
 
 from api.projects import projects_bp
 from api.sessions import sessions_bp
 from api.search import search_bp
 from api.export_api import export_bp
+from utils.exclusion_rules import resolve_exclusion_rules_path, load_rules
 
 
-def create_app(base_dir: str | None = None) -> Flask:
+def create_app(
+    base_dir: str | None = None,
+    exclusion_rules_path: str | None = None,
+) -> Flask:
     app = Flask(__name__)
     app.config["CLAUDE_PROJECTS_DIR"] = base_dir
 
+    resolved = resolve_exclusion_rules_path(exclusion_rules_path)
+    app.config["EXCLUSION_RULES_PATH"] = resolved
+    app.config["EXCLUSION_RULES"] = load_rules(resolved)
+
     app.register_blueprint(projects_bp)
     app.register_blueprint(sessions_bp)
     app.register_blueprint(search_bp)
@@ -33,8 +42,20 @@ def index():
     parser.add_argument("--port", type=int, default=5000)
     parser.add_argument("--host", default="127.0.0.1")
     parser.add_argument("--base-dir", default=None, help="Override Claude projects dir")
+    parser.add_argument(
+        "--exclude-rules", "-e",
+        default=None,
+        metavar="PATH",
+        help="Path to exclusion rules file (sensitive sessions are omitted). "
+             "If omitted, uses ~/.claude-code-chat-browser/exclusion-rules.txt if present.",
+    )
     args = parser.parse_args()
 
-    app = create_app(base_dir=args.base_dir)
+    app = create_app(base_dir=args.base_dir, exclusion_rules_path=args.exclude_rules)
     print(f"Claude Code Chat Browser running at http://{args.host}:{args.port}")
-    app.run(host=args.host, port=args.port, debug=True, use_reloader=False)
+    app.run(
+        host=args.host,
+        port=args.port,
+        debug=True,
+        use_reloader=(sys.platform != "win32"),
+    )

requirements.txt

@@ -1 +1,16 @@
-flask>=3.0
+blinker==1.9.0
+click==8.3.1
+colorama==0.4.6
+exceptiongroup==1.3.1
+Flask==3.1.3
+iniconfig==2.3.0
+itsdangerous==2.2.0
+Jinja2==3.1.6
+MarkupSafe==3.0.3
+packaging==26.0
+pluggy==1.6.0
+Pygments==2.19.2
+pytest==9.0.2
+tomli==2.4.0
+typing_extensions==4.15.0
+Werkzeug==3.1.6

scripts/export.py

@@ -28,6 +28,12 @@
 from utils.session_stats import compute_stats, _format_duration
 from utils.md_exporter import session_to_markdown
 from utils.json_exporter import session_to_json
+from utils.exclusion_rules import (
+    resolve_exclusion_rules_path,
+    load_rules,
+    build_searchable_text,
+    is_excluded_by_rules,
+)
 
 
 STATE_DIR = os.path.join(os.path.expanduser("~"), ".claude-code-chat-browser")
@@ -285,11 +291,15 @@ def cmd_export(args):
     project_filter = getattr(args, "project", None)
     fmt = getattr(args, "format", None) or "md"
     session_filter = getattr(args, "session", None)
+    exclusion_rules_path = getattr(args, "exclude_rules", None)
 
     if not os.path.isdir(base_dir):
         _die(f"Claude Code projects directory not found: {base_dir}")
 
-    last_export = _load_state() if since == "last" else {}
+    rules = load_rules(resolve_exclusion_rules_path(exclusion_rules_path))
+
+    state = _load_state() if since == "last" else {}
+    last_export = state.get("sessions", {})
 
     # Single session export
     if session_filter:
@@ -338,6 +348,18 @@ def cmd_export(args):
                 skipped += 1
                 continue
 
+            if rules:
+                meta = session["metadata"]
+                searchable = build_searchable_text(
+                    project_name=project.get("display_name") or project["name"],
+                    session_title=session["title"],
+                    model_names=list(meta.get("models_used") or []),
+                    content_snippet=_session_text_for_exclusion(session),
+                )
+                if is_excluded_by_rules(rules, searchable):
+                    skipped += 1
+                    continue
+
             stats = compute_stats(session)
             meta = session["metadata"]
             ts = meta.get("first_timestamp", "")
@@ -420,8 +442,8 @@ def cmd_export(args):
             zf.writestr("manifest.jsonl", manifest_str)
         print(f"Exported {exported} file(s) to {zip_path}")
 
-    _save_state(last_export)
-    print("Export state saved.")
+    _save_state(last_export, count=len(manifest), out_dir=out_dir)
+    print(f"State saved to {STATE_FILE}")
 
 
 def _export_single(session: dict, stats: dict, fmt: str, out_dir: str):
@@ -445,6 +467,19 @@ def _export_single(session: dict, stats: dict, fmt: str, out_dir: str):
         print(f"Exported: {fpath}")
 
 
+# ==================== Helpers ====================
+
+
+def _session_text_for_exclusion(session: dict) -> str:
+    """Extract plain text from all session messages for exclusion rule matching."""
+    parts = []
+    for msg in session.get("messages", []):
+        text = msg.get("text") or ""
+        if isinstance(text, str) and text.strip():
+            parts.append(text)
+    return "\n\n".join(parts)
+
+
 # ==================== Argument Parser ====================
 
 
@@ -469,6 +504,14 @@ def build_parser() -> argparse.ArgumentParser:
                         default=None, help="Export format (default: md)")
     parser.add_argument("--session", default=None,
                         help="Export/stats for single session (UUID prefix)")
+    parser.add_argument(
+        "--exclude-rules", "-e",
+        default=None,
+        metavar="PATH",
+        dest="exclude_rules",
+        help="Path to exclusion rules file (sensitive sessions are omitted). "
+             "If omitted, uses ~/.claude-code-chat-browser/exclusion-rules.txt if present.",
+    )
 
     subparsers = parser.add_subparsers(dest="command")
 
@@ -506,13 +549,18 @@ def build_parser() -> argparse.ArgumentParser:
                           help="Filter by project name")
     export_p.add_argument("--base-dir", default=None,
                           help="Override Claude Code projects directory")
+    export_p.add_argument(
+        "--exclude-rules", "-e",
+        default=None,
+        metavar="PATH",
+        dest="exclude_rules",
+        help="Path to exclusion rules file (sensitive sessions are omitted). "
+             "If omitted, uses ~/.claude-code-chat-browser/exclusion-rules.txt if present.",
+    )
 
     return parser
 
 
-# ==================== Helpers ====================
-
-
 def _find_session(session_id: str, base_dir: str) -> str | None:
     """Scan all projects for a session matching this UUID (or prefix).
     Fails if the prefix matches more than one session."""
@@ -534,14 +582,41 @@ def _find_session(session_id: str, base_dir: str) -> str | None:
 
 
 def _load_state() -> dict:
-    if os.path.isfile(STATE_FILE):
-        with open(STATE_FILE, "r") as f:
-            return json.load(f)
-    return {}
-
-
-def _save_state(state: dict):
+    """Load export state, migrating legacy flat format to the current schema.
+
+    Current schema::
+
+        {
+            "lastExportTime": "2026-02-25T12:00:00",
+            "exportedCount": 42,
+            "exportDir": "/path/to/out",
+            "sessions": {"<session-uuid>": <mtime-float>, ...}
+        }
+
+    Legacy schema (written by older versions)::
+
+        {"<session-uuid>": <mtime-float>, ...}
+    """
+    if not os.path.isfile(STATE_FILE):
+        return {}
+    with open(STATE_FILE, "r") as f:
+        data = json.load(f)
+    # Migrate: if the file has neither "sessions" nor "lastExportTime" it is
+    # the old flat dict of session_id → mtime.
+    if "sessions" not in data and "lastExportTime" not in data:
+        return {"sessions": data}
+    return data
+
+
+def _save_state(sessions: dict, count: int, out_dir: str):
+    """Persist export state with standardised fields matching cursor-chat-browser."""
     os.makedirs(STATE_DIR, exist_ok=True)
+    state = {
+        "lastExportTime": datetime.now().isoformat(),
+        "exportedCount": count,
+        "exportDir": out_dir,
+        "sessions": sessions,
+    }
     with open(STATE_FILE, "w") as f:
         json.dump(state, f, indent=2)