Metadata-Version: 2.4
Name: llmlinq
Version: 0.1.0
Summary: A local-first timeline for every prompt you've sent to Claude Code, Codex CLI, and Gemini CLI.
Author-email: odyssey <odyssey.unheard@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: claude,cli,codex,gemini,history,localhost,prompt,timeline
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx2>=0.1
Requires-Dist: rich>=13
Requires-Dist: sse-starlette>=2.2
Requires-Dist: typer>=0.15
Requires-Dist: uvicorn>=0.32
Requires-Dist: watchdog>=6.0
Description-Content-Type: text/markdown

# <img src="frontend/public/favicon.svg" width="26" alt="LLMLinq icon"> LLMLinq

> A local-first timeline for every prompt you've ever sent to **Claude Code**,
> **Codex CLI**, and **Gemini CLI**.

LLMLinq reads the prompt history that the three major AI coding CLIs
already keep on your machine and presents it as a beautiful, searchable,
live-updating timeline at `http://127.0.0.1:8745`.

- 🗂 **Three tabs** — Claude · Codex · Gemini, with live prompt counts
- 🕰 **Timeline view** — day-grouped, newest first, with project context
- 🔍 **Search** — find any prompt you ever typed
- ⚡ **Live** — prompts appear in the timeline seconds after you type them
- 🔒 **Private by design** — read-only, binds to localhost, zero network egress, zero telemetry


## Install

```bash
uv tool install llmlinq   # or: pipx install llmlinq / pip install llmlinq
llmlinq                   # scan → serve → open http://127.0.0.1:8745
```

Or try it without installing anything:

```bash
uvx llmlinq
```

Only Python ≥ 3.11 is required — the web UI ships prebuilt inside the package.
The wheel can also be downloaded directly from the
[PyPI files page](https://pypi.org/project/llmlinq/#files).

> ⚠️ Running from a git clone (`uv run llmlinq`) shows a "UI not built"
> page — the UI is bundled into released packages, not the repository.
> Install from PyPI as above, or build the UI first (see Development).

Useful commands:

```bash
llmlinq --port 9000 --no-browser   # custom port, stay in the terminal
llmlinq paths                      # doctor: what was detected, where, how many prompts
```

## How it works

| Provider | Reads (read-only) |
|---|---|
| Claude Code | `~/.claude/history.jsonl` (or session transcripts as fallback) |
| Codex CLI | `~/.codex/history.jsonl` + per-session metadata for project names |
| Gemini CLI | `~/.gemini/tmp/<sha256(project)>/logs.json` |

Gemini never stores project paths — only a SHA-256 hash of them — so AI Prompt
Dock recovers project names by hashing paths it learned from Claude and Codex
data and matching them against Gemini's directory names.

A filesystem watcher picks up new prompts as you type them into any of the
three CLIs and pushes them to the timeline over Server-Sent Events.

Custom data locations are honored via `CLAUDE_CONFIG_DIR` and `CODEX_HOME`.

## Project structure

```
llmlinq-app/
├── pyproject.toml              # Package metadata, dependencies, tool config (ruff/mypy/pytest)
├── uv.lock                     # Locked dependency versions (reproducible installs)
├── Makefile                    # One-word workflows: make dev / test / lint / build
├── .github/workflows/ci.yml    # CI: lint + typecheck + tests (Python 3.11–3.13) + UI build
├── src/
│   └── llmlinq/           # ── The Python package ──
│       ├── cli.py              # Typer CLI entry point (`llmlinq` command)
│       ├── server.py           # FastAPI app factory + production server runner
│       ├── api/                # HTTP API routes            (Phase 2)
│       ├── core/               # Models, prompt store, file watcher (Phase 1)
│       ├── providers/          # Claude / Codex / Gemini history adapters (Phase 1)
│       └── web/static/         # Built SPA — generated by `make build-ui`, gitignored,
│                               # shipped inside the wheel
├── frontend/                   # ── The React app ──
│   ├── vite.config.ts          # Builds into src/llmlinq/web/static/; dev proxy → :8745
│   └── src/
│       ├── App.tsx             # Root component
│       └── styles/index.css    # Tailwind CSS v4 entry (sky theme)
└── tests/                      # pytest suite (synthetic CLI-data fixtures in Phase 1)
```

The one unusual thing worth knowing: **the frontend builds into the Python
package**. `vite build` outputs to `src/llmlinq/web/static/`, and the
wheel includes that directory (see `[tool.hatch.build]` in `pyproject.toml`).
That is why end users need only Python — never Node.

## Local development

Prerequisites: [uv](https://docs.astral.sh/uv/) and Node.js ≥ 22.

```bash
git clone <repo-url> && cd llmlinq-app
make install   # uv sync (creates ./.venv + installs Python deps) + npm install
make dev       # backend on :8745 + frontend on :5173, hot reload on both
```

Open **http://localhost:5173** during development — the Vite dev server
proxies `/api` and `/healthz` to the FastAPI backend on `:8745`.

All Python tooling runs inside the project virtualenv at `./.venv`
(created by `uv sync`). Use `uv run <cmd>` — or activate it with
`source .venv/bin/activate` if you prefer.

Run the halves separately when needed:

```bash
make dev-api   # FastAPI only  → uv run uvicorn --factory llmlinq.server:create_app --reload --port 8745
make dev-ui    # Vite only     → cd frontend && npm run dev
```

To test the production setup (FastAPI serving the built SPA, as end users get it):

```bash
make build-ui                  # build the SPA into the package
uv run llmlinq            # serve everything from :8745
```

Other useful targets:

```bash
make test      # pytest
make build     # build the SPA, then the wheel (dist/llmlinq-*.whl, UI bundled)
make clean     # remove build artifacts and caches
make help      # list all targets
```

## Linting & formatting

```bash
make lint      # check everything (what CI runs)
make fmt       # auto-fix + format Python code
```

`make lint` runs, in order:

| Tool | Command | Checks |
|---|---|---|
| Ruff (lint) | `uv run ruff check src tests` | Python lint rules (`E,F,W,I,UP,B,SIM,C4,RUF`) |
| Ruff (format) | `uv run ruff format --check src tests` | Python formatting |
| mypy | `uv run mypy src` | Static types, `strict = true` |
| TypeScript | `cd frontend && npm run typecheck` | Frontend types (`tsc`, strict) |

Configuration lives in `pyproject.toml` (`[tool.ruff]`, `[tool.mypy]`) and
`frontend/tsconfig.json`. CI (`.github/workflows/ci.yml`) runs the same
checks plus the test suite on Python 3.11, 3.12, and 3.13 — run
`make lint test` before pushing and you should match CI exactly.

## License

[MIT](LICENSE)
