Metadata-Version: 2.4
Name: navig-chats
Version: 0.1.0
Summary: navig chats -- a local library for your AI conversations: import your ChatGPT data export, save chats from the page with the NAVIG Dock, search every message offline, organise them in folders, and export to Markdown, HTML, JSON or a checksummed zip.
Author: navig
License: MIT
Project-URL: Homepage, https://navig.run
Project-URL: Documentation, https://navig.run/docs
Keywords: navig,cli,plugin,chatgpt,chat,conversations,archive,export,search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: navig-sdk>=2.10.0
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13.7.0
Dynamic: license-file

# navig-chats

<!-- navig:plugin-card:start -->
<!-- Generated by scripts/gen_plugin_catalog.py — edit the plugin's pyproject.toml, not this block. -->

> A local library for your AI conversations: import your ChatGPT data export, save chats from the page with the NAVIG Dock, search every message offline, organise them in folders, and export to Markdown, HTML, JSON or a checksummed zip.

**Works on its own** — its own CLI, no navig required · v0.1.0 · not on PyPI yet (install from source below)

**On its own** (no navig needed)

```bash
pip install "git+https://github.com/navig-run/plugins#subdirectory=navig-chats"
navig-chats --help   # no navig needed
```

**With navig**

```bash
pip install "git+https://github.com/navig-run/plugins#subdirectory=navig-chats"
navig chats --help
```

<details><summary>Commands</summary>

| Command | What it does |
|---|---|
| `navig chats export` | Export chats — readable without NAVIG. Several chats go into one .zip with a manifest. |
| `navig chats folders add` | Create a folder. |
| `navig chats folders list` | Every folder, as a tree. |
| `navig chats folders rm` | Delete a folder. Its chats stay in the library; subfolders move up a level. |
| `navig chats handoff` | Continue this work — a context pack (decisions, open items, code, sources) for another agent. |
| `navig chats import` | Import a ChatGPT account export. Safe to re-run: unchanged chats are skipped. |
| `navig chats list` | List chats in the library. |
| `navig chats move` | Put chats in a NAVIG folder (a local change — nothing moves in ChatGPT). |
| `navig chats reindex` | Rebuild the search index from the stored messages. |
| `navig chats restore` | Restore chats from a NAVIG export into the library (not into ChatGPT itself). |
| `navig chats search` | Search every message and title, ranked by relevance. |
| `navig chats share` | Choose what NAVIG's knowledge index may read. Nothing is shared until you say so. |
| `navig chats shared` | Every chat NAVIG's knowledge index may read, and at which level. |
| `navig chats show` | Read one chat. |
| `navig chats stats` | How much the library holds, and where. |

</details>

<!-- navig:plugin-card:end -->

A local library for your AI conversations. It runs as `navig chats` inside [NAVIG](https://navig.run), or as `navig-chats` on its own.

- **Import your ChatGPT history.** Use the account export (ChatGPT → Settings → Data controls → Export data). Every chat comes in with all of its branches, and the branch ChatGPT showed you is marked. Re-importing changes nothing.
- **Save chats while you browse.** The NAVIG Dock's ChatGPT Lens adds a chat button to the page. Click it to save the chat. A saved chat refreshes itself when you come back to it. You can also turn on "Save every chat I open".
- **Search every message offline.** Use `"exact phrases"`, `-exclusions`, `prefix*` and `OR`. Results are ranked by relevance and point at the exact message. Open the match back in ChatGPT, or read the library copy.
- **Organise in NAVIG folders.** Folders, tags, pins and local renames are an overlay on your computer. They never change ChatGPT or its Projects.
- **Export in formats that outlive NAVIG.** Choose Markdown with front matter, HTML, plain text, or a JSON bundle. A zip of many chats includes a sha256 manifest. `restore` brings a NAVIG archive back into the library.

```text
navig chats import ~/Downloads/chatgpt-export.zip
navig chats search '"borrow checker" -python'
navig chats show 67f1c2d3
navig chats folders add Work
navig chats move 67f1c2d3 --to <folder-id>
navig chats export --all -o chats.zip
```

## Where the data lives

Your chats live in one SQLite file on this computer: `<navig data dir>/chats.db`, or the path in `$NAVIG_CHATS_DB`. It is separate from the NAVIG agent's own memory. A chat reaches the agent only if you choose to share it.

The deck routes (`/api/deck/chats/*`), used by the Dock and the Library page, answer **only this computer**. They are not reachable through a tunnel, Lighthouse or the Telegram Mini App.

## What it does not do

- It never asks for, reads or stores ChatGPT session tokens, and it never calls ChatGPT's private endpoints. It reads only what your export contains, or what the page shows you.
- **Completeness is labelled honestly:**
  - `complete`: imported from your export.
  - `rendered`: saved from the page, covering the branch you saw.
  - `partial`: some messages are missing.
  - `url_only`: only the link is saved.

  Attachments the library never held are listed as missing. They are never invented.
- Restoring an archive restores the library. It cannot recreate chats inside ChatGPT.
