llmlinq 0.1.0

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

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

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:

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.

⚠️ 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:

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 and Node.js ≥ 22.

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:

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):

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

Other useful targets:

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

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