Add support for Cursor CLI agent sessions (closes #7)

Read, browse, search, and export sessions stored in ~/.cursor/chats/
by the `cursor agent` CLI — independent of the Cursor IDE.

New modules:
- utils/cli_chat_reader.py: reconstructs conversations from the
  store.db blob-graph (BFS over SHA-256 content-addressed blobs),
  extracts workspace path from <user_info> preamble, converts
  messages to the bubble format used by the rest of the app.
- utils/cursor_md_exporter.py: reusable Markdown exporter for CLI
  sessions (YAML frontmatter + conversation body).

Web UI:
- api/workspaces.py: CLI projects appear in the workspaces list
  (id: "cli:<project_id>"); workspace detail and tabs endpoints
  handle cli:-prefixed IDs.
- api/search.py: full-text search now includes CLI sessions.

CLI export:
- scripts/export.py: exports CLI sessions alongside IDE chats
  (written to <workspace>/cli/). IDE database is now optional —
  export works gracefully when only cursor agent is installed.

Config:
- utils/workspace_path.py: get_cli_chats_path() defaults to
  ~/.cursor/chats/; overrideable via CLI_CHATS_PATH env var.

Tests:
- tests/test_cli_chat_reader.py: 53 unit tests (blob parsing,
  content extraction, message conversion, session enumeration,
  project grouping, stats aggregation).
- tests/test_cursor_md_exporter.py: 15 tests (frontmatter fields,
  body rendering, tool calls, edge cases).
- tests/test_search_exclusion_filtering.py: isolate CLI path via
  CLI_CHATS_PATH to prevent real sessions leaking into tests.

Author: wpak-ai

README.md

@@ -8,6 +8,7 @@ Inspired by [cursor-chat-browser](https://github.com/thomas-pedersen/cursor-chat
 
 - Browse and search all workspaces with Cursor chat history
 - Support for both workspace-specific and global storage (newer Cursor versions)
+- **Cursor CLI agent sessions** — browses and exports sessions from `cursor agent` (stored in `~/.cursor/chats/`)
 - View AI chat and Composer/Agent logs
 - Organize chats by workspace/project
 - Full-text search with filters for chat/composer logs
@@ -101,7 +102,9 @@ python scripts/export.py --no-composer
 
 - **Zip mode** (default): A single `cursor-export-YYYY-MM-DD.zip` file containing all Markdown files organized by date, workspace, and chat.
 - **File mode** (`--no-zip`): Individual Markdown files at `<out>/YYYY-MM-DD/<workspace>/chat/<timestamp>__<title>__<id>.md`, plus a `manifest.jsonl` index.
-- Each Markdown file includes YAML frontmatter (log ID, title, timestamps, message count, model, token usage, etc.) and the full conversation transcript.
+- Each Markdown file includes YAML frontmatter (log ID, title, timestamps, message count, model, token usage, tool calls, etc.) and the full conversation transcript.
+- IDE chats are written under `<workspace>/chat/`; Cursor CLI agent sessions are written under `<workspace>/cli/`.
+- If the Cursor IDE database is absent (e.g. on a machine with only `cursor agent` installed), only CLI sessions are exported — the script no longer exits with an error.
 
 Export state is saved to `~/.cursor-chat-browser/export_state.json` so that `--since last` works across runs.
 
@@ -119,6 +122,8 @@ The application automatically detects your Cursor workspace storage location:
 
 To override, set the `WORKSPACE_PATH` environment variable or use the Configuration page in the web UI.
 
+Cursor CLI agent sessions are read from `~/.cursor/chats/` (the default path used by the `cursor agent` CLI). Override with the `CLI_CHATS_PATH` environment variable.
+
 ## Project Structure
 
 ```
@@ -134,7 +139,9 @@ cursor-chat-browser-python/
 │   ├── pdf.py              # /api/generate-pdf endpoint
 │   └── config_api.py       # Config-related endpoints
 ├── utils/                  # Utility modules
-│   ├── workspace_path.py   # Workspace path detection
+│   ├── workspace_path.py   # Workspace path detection (IDE + CLI)
+│   ├── cli_chat_reader.py  # Reader for Cursor CLI agent sessions (~/.cursor/chats/)
+│   ├── cursor_md_exporter.py # Markdown exporter for CLI agent sessions
 │   ├── path_helpers.py     # Path normalization helpers
 │   ├── text_extract.py     # Text extraction from bubbles
 │   └── tool_parser.py      # Tool call parsing

api/search.py

@@ -13,9 +13,10 @@
 from flask import Blueprint, current_app, jsonify, request
 
 from utils.exclusion_rules import build_searchable_text, is_excluded_by_rules
-from utils.workspace_path import resolve_workspace_path
+from utils.workspace_path import resolve_workspace_path, get_cli_chats_path
 from utils.path_helpers import normalize_file_path, get_workspace_folder_paths, to_epoch_ms
 from utils.text_extract import extract_text_from_bubble
+from utils.cli_chat_reader import list_cli_projects, traverse_blobs, messages_to_bubbles
 
 bp = Blueprint("search", __name__)
 
@@ -343,6 +344,82 @@ def search():
         except Exception:
             pass
 
+        # ---------------------------------------------------------------
+        # Search Cursor CLI sessions
+        # ---------------------------------------------------------------
+        try:
+            cli_projects = list_cli_projects(get_cli_chats_path())
+            for cp in cli_projects:
+                ws_name = cp["workspace_name"] or cp["project_id"][:12]
+                for session in cp["sessions"]:
+                    meta = session.get("meta", {})
+                    session_id = session["session_id"]
+                    created_ms: int = meta.get("createdAt") or int(datetime.now().timestamp() * 1000)
+                    session_name = meta.get("name") or f"Session {session_id[:8]}"
+
+                    try:
+                        messages = traverse_blobs(session["db_path"])
+                    except Exception:
+                        continue
+
+                    bubbles = messages_to_bubbles(messages, created_ms)
+                    if not bubbles:
+                        continue
+
+                    # Derive title
+                    title = session_name
+                    if not title or title.startswith("New Agent"):
+                        for b in bubbles:
+                            if b["type"] == "user" and b.get("text"):
+                                first_lines = [l for l in b["text"].split("\n") if l.strip()]
+                                if first_lines:
+                                    title = first_lines[0][:100]
+                                break
+
+                    bubble_texts = [b["text"] for b in bubbles if b.get("text")]
+                    exclusion_text = _build_exclusion_searchable(
+                        project_name=ws_name,
+                        chat_title=title,
+                        content_parts=bubble_texts,
+                    )
+                    if is_excluded_by_rules(rules, exclusion_text):
+                        continue
+
+                    has_match = False
+                    matching_text = ""
+
+                    if title and query_lower in title.lower():
+                        has_match = True
+                        matching_text = title
+
+                    if not has_match:
+                        for text in bubble_texts:
+                            if text and query_lower in text.lower():
+                                has_match = True
+                                idx = text.lower().find(query_lower)
+                                start = max(0, idx - 80)
+                                end = min(len(text), idx + len(query) + 120)
+                                matching_text = (
+                                    ("..." if start > 0 else "")
+                                    + text[start:end]
+                                    + ("..." if end < len(text) else "")
+                                )
+                                break
+
+                    if has_match:
+                        results.append({
+                            "workspaceId": f"cli:{cp['project_id']}",
+                            "workspaceFolder": cp.get("workspace_path"),
+                            "chatId": session_id,
+                            "chatTitle": title,
+                            "timestamp": created_ms,
+                            "matchingText": matching_text,
+                            "type": "cli_agent",
+                            "source": "cli",
+                        })
+        except Exception as e:
+            print(f"Error searching CLI sessions: {e}")
+
         # Sort by timestamp descending
         def _ts(r):
             t = r.get("timestamp", 0)

api/workspaces.py

@@ -17,7 +17,12 @@
 
 from flask import Blueprint, current_app, jsonify
 
-from utils.workspace_path import resolve_workspace_path
+from utils.workspace_path import resolve_workspace_path, get_cli_chats_path
+from utils.cli_chat_reader import (
+    list_cli_projects,
+    traverse_blobs,
+    messages_to_bubbles,
+)
 from utils.path_helpers import (
     normalize_file_path,
     get_workspace_folder_paths,
@@ -712,6 +717,39 @@ def list_workspaces():
                 ),
             })
 
+        # --- Cursor CLI projects ---
+        try:
+            cli_projects = list_cli_projects(get_cli_chats_path())
+            for cp in cli_projects:
+                ws_name = cp["workspace_name"] or cp["project_id"][:12]
+                if is_excluded_by_rules(rules, ws_name):
+                    continue
+                convos = []
+                for s in cp["sessions"]:
+                    session_name = s["meta"].get("name") or f"Session {s['session_id'][:8]}"
+                    searchable = build_searchable_text(
+                        project_name=ws_name,
+                        chat_title=session_name,
+                    )
+                    if not is_excluded_by_rules(rules, searchable):
+                        convos.append(session_name)
+                if not convos:
+                    continue
+                last_ms = cp["last_updated_ms"]
+                projects.append({
+                    "id": f"cli:{cp['project_id']}",
+                    "name": ws_name,
+                    "conversationCount": len(convos),
+                    "lastModified": (
+                        datetime.fromtimestamp(last_ms / 1000, tz=timezone.utc).isoformat()
+                        if last_ms
+                        else datetime.now(tz=timezone.utc).isoformat()
+                    ),
+                    "source": "cli",
+                })
+        except Exception as e:
+            print(f"Failed to load CLI projects: {e}")
+
         projects.sort(key=lambda p: p["lastModified"], reverse=True)
         return jsonify(projects)
 
@@ -736,6 +774,26 @@ def get_workspace(workspace_id):
                 "lastModified": datetime.now(tz=timezone.utc).isoformat(),
             })
 
+        if workspace_id.startswith("cli:"):
+            project_id = workspace_id[4:]
+            cli_projects = list_cli_projects(get_cli_chats_path())
+            for cp in cli_projects:
+                if cp["project_id"] == project_id:
+                    last_ms = cp["last_updated_ms"]
+                    return jsonify({
+                        "id": workspace_id,
+                        "name": cp["workspace_name"] or project_id[:12],
+                        "path": cp["workspace_path"],
+                        "folder": cp["workspace_path"],
+                        "lastModified": (
+                            datetime.fromtimestamp(last_ms / 1000, tz=timezone.utc).isoformat()
+                            if last_ms
+                            else datetime.now(tz=timezone.utc).isoformat()
+                        ),
+                        "source": "cli",
+                    })
+            return jsonify({"error": "CLI project not found"}), 404
+
         workspace_path = resolve_workspace_path()
         db_path = os.path.join(workspace_path, workspace_id, "state.vscdb")
         wj_path = os.path.join(workspace_path, workspace_id, "workspace.json")
@@ -782,6 +840,97 @@ def get_workspace(workspace_id):
 from utils.tool_parser import parse_tool_call as _parse_tool_call
 
 
+def _get_cli_workspace_tabs(workspace_id: str):
+    """Return tabs for a Cursor CLI project (``workspace_id`` starts with ``cli:``)."""
+    try:
+        project_id = workspace_id[4:]
+        cli_projects = list_cli_projects(get_cli_chats_path())
+        project = next((cp for cp in cli_projects if cp["project_id"] == project_id), None)
+        if project is None:
+            return jsonify({"error": "CLI project not found"}), 404
+
+        rules = current_app.config.get("EXCLUSION_RULES") or []
+        ws_name = project["workspace_name"] or project_id[:12]
+        tabs = []
+
+        for session in project["sessions"]:
+            meta = session.get("meta", {})
+            session_id = session["session_id"]
+            created_ms: int = meta.get("createdAt") or int(datetime.now().timestamp() * 1000)
+            session_name = meta.get("name") or f"Session {session_id[:8]}"
+
+            try:
+                messages = traverse_blobs(session["db_path"])
+            except Exception as e:
+                print(f"CLI: could not read session {session_id}: {e}")
+                continue
+
+            bubbles = messages_to_bubbles(messages, created_ms)
+            if not bubbles:
+                continue
+
+            # Derive title from first user bubble when name is generic
+            title = session_name
+            if not title or title.startswith("New Agent"):
+                for b in bubbles:
+                    if b["type"] == "user" and b.get("text"):
+                        first_lines = [l for l in b["text"].split("\n") if l.strip()]
+                        if first_lines:
+                            title = first_lines[0][:100]
+                            if len(title) == 100:
+                                title += "..."
+                        break
+
+            searchable = build_searchable_text(project_name=ws_name, chat_title=title)
+            if is_excluded_by_rules(rules, searchable):
+                continue
+
+            # Aggregate metadata
+            total_tool_calls = 0
+            tool_breakdown: dict = {}
+            for b in bubbles:
+                tcs = (b.get("metadata") or {}).get("toolCalls") or []
+                total_tool_calls += len(tcs)
+                for tc in tcs:
+                    tn = tc.get("name", "unknown")
+                    tool_breakdown[tn] = tool_breakdown.get(tn, 0) + 1
+
+            tab_meta: dict | None = None
+            if total_tool_calls or tool_breakdown:
+                tab_meta = {"totalToolCalls": total_tool_calls or None}
+                if tool_breakdown:
+                    tab_meta["toolBreakdown"] = tool_breakdown
+
+            tab = {
+                "id": session_id,
+                "title": title,
+                "timestamp": created_ms,
+                "bubbles": [
+                    {
+                        "type": b["type"],
+                        "text": b.get("text", ""),
+                        "timestamp": b.get("timestamp", created_ms),
+                        **({"metadata": b["metadata"]} if b.get("metadata") else {}),
+                    }
+                    for b in bubbles
+                ],
+                "source": "cli",
+            }
+            if tab_meta:
+                tab_meta_clean = {k: v for k, v in tab_meta.items() if v is not None}
+                if tab_meta_clean:
+                    tab["metadata"] = tab_meta_clean
+
+            tabs.append(tab)
+
+        tabs.sort(key=lambda t: t.get("timestamp") or 0, reverse=True)
+        return jsonify({"tabs": tabs})
+
+    except Exception as e:
+        print(f"Failed to get CLI workspace tabs: {e}")
+        return jsonify({"error": "Failed to get CLI workspace tabs"}), 500
+
+
 def _extract_chat_id_from_bubble_key(key: str) -> str | None:
     m = re.match(r"^bubbleId:([^:]+):", key)
     return m.group(1) if m else None
@@ -794,6 +943,9 @@ def _extract_chat_id_from_code_block_diff_key(key: str) -> str | None:
 
 @bp.route("/api/workspaces/<workspace_id>/tabs")
 def get_workspace_tabs(workspace_id):
+    if workspace_id.startswith("cli:"):
+        return _get_cli_workspace_tabs(workspace_id)
+
     global_db = None
     try:
         workspace_path = resolve_workspace_path()