Metadata-Version: 2.4
Name: cursor-viewer
Version: 0.1.0
Summary: Browse and search your Cursor AI chat histories locally, including tool calls
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: streamlit>=1.32.0

# cursor-viewer

A local browser UI for reading through your Cursor AI chat histories — including tool calls, search, and support for exploring backups.

Built with Streamlit. No server, no account, no data leaving your machine.

---

## What it does

- Lists all your Cursor chats grouped by project
- Renders tool calls (file reads, terminal commands, etc.) inline as collapsible sections
- Lets you search across projects and message content
- Supports pointing at a backup of your `.cursor` data directory, not just the live one

---

## Install

Requires Python 3.10+. First, get [pipx](https://pipx.pypa.io) if you don't have it:

**macOS**
```bash
brew install pipx
pipx ensurepath
```

**Linux**
```bash
sudo apt install pipx      # Debian/Ubuntu
pipx ensurepath
```

**Windows**
```bash
scoop install pipx         # or: pip install --user pipx
pipx ensurepath
```

Then install cursor-viewer:

```bash
pipx install cursor-viewer
```

Then just run:

```bash
cursor-viewer
```

It opens in your browser at `http://localhost:8501`.

---

## Configuration

The app figures out where your Cursor data lives automatically. If you want to override that:

**One-off (flag):**
```bash
cursor-viewer --cursor-path "/Volumes/Backup/Library/Application Support/Cursor"
```

**Session (env var):**
```bash
CURSOR_DATA_PATH="/path/to/cursor" cursor-viewer
```

**Persistent default (UI):**
Open the Settings panel in the sidebar, enter your path, and hit "Save as default". That writes to `~/.cursor-viewer/config.json` and sticks across restarts.

**Priority order:** flag > env var > saved config > auto-detected default.

---

## Other options

```
cursor-viewer --help
```

```
--cursor-path PATH   path to Cursor's data directory
--port PORT          port to run on (default: 8501)
```

---

## Running from source

```bash
git clone https://github.com/sahilsasane/cursor-viewer
cd cursor-viewer
uv sync
uv run streamlit run streamlit_app.py
```

---

## How Cursor stores chats

Cursor keeps chat history in SQLite databases under its data directory:

- `User/globalStorage/state.vscdb` — composer/agent chats
- `User/workspaceStorage/<id>/state.vscdb` — per-workspace chats and metadata

cursor-viewer reads these directly, read-only, without touching any Cursor internals.
