aipromptdock 0.1.0__tar.gz

aipromptdock-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  backend:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - run: uv sync --frozen
+      - run: uv run ruff check src tests
+      - run: uv run ruff format --check src tests
+      - run: uv run mypy src
+      - run: uv run pytest
+
+  frontend:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm run build

aipromptdock-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,51 @@
+name: Release
+
+# Tag-driven release: pushing a tag like v0.1.0 builds the UI, packs it into
+# the wheel, and publishes to PyPI via trusted publishing (no API tokens).
+#
+# One-time setup: add a trusted publisher for the `aipromptdock` project at
+# https://pypi.org/manage/account/publishing/ with:
+#   owner: infoinlet-com · repo: aipromptdock-app
+#   workflow: release.yml · environment: pypi
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - name: Build the web UI into the package
+        working-directory: frontend
+        run: |
+          npm ci
+          npm run build
+      - uses: astral-sh/setup-uv@v5
+      - name: Build sdist and wheel (UI bundled)
+        run: uv build
+      - name: Verify the wheel contains the UI
+        run: unzip -l dist/*.whl | grep -q "aipromptdock/web/static/index.html"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

aipromptdock-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Node
+frontend/node_modules/
+npm-debug.log*
+*.tsbuildinfo
+
+# Built frontend (generated by `make build-ui`, shipped inside the wheel)
+src/aipromptdock/web/static/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+
+# Local AI-assistant artifacts and working notes
+.claude/
+.context/
+
+# Env
+.env
+.env.*

aipromptdock-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

aipromptdock-0.1.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+
+- New application icon: an isometric stack of prompt layers with code
+  brackets, replacing the anchor (#1).
+
+## [0.1.0] - 2026-06-05
+
+### Added
+
+- Timeline web app at `http://127.0.0.1:8745` with three provider tabs
+  (Claude · Codex · Gemini), day-grouped prompt cards, search, infinite
+  scroll, copy-to-clipboard, and project labels.
+- Provider adapters reading each CLI's on-disk history:
+  Claude Code (`history.jsonl`, transcript fallback), Codex CLI
+  (`history.jsonl` + session metadata for project names), Gemini CLI
+  (`tmp/<sha256(project)>/logs.json` with project-name recovery by hashing
+  paths learned from Claude/Codex data).
+- Live updates: a filesystem watcher pushes new prompts to the timeline over
+  Server-Sent Events within about a second of typing them.
+- `aipromptdock` CLI: serve (default, opens the browser), `--port`, `--host`,
+  `--no-browser`, and `aipromptdock paths` doctor command.
+- Packaging that bundles the prebuilt React UI inside the Python wheel —
+  end users need only Python 3.11+ (`uv tool install aipromptdock`).
+- CI (lint, typecheck, tests on Python 3.11–3.13, UI build) and a tag-driven
+  release workflow publishing to PyPI via trusted publishing.
+
+### Security
+
+- Binds to `127.0.0.1` only by default; read-only access to CLI data;
+  no network egress; no telemetry.

aipromptdock-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 odyssey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aipromptdock-0.1.0/Makefile

@@ -0,0 +1,42 @@
+.DEFAULT_GOAL := help
+MAKEFLAGS += --no-print-directory
+
+help: ## List available targets
+	@grep -E '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-12s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install backend (uv) + frontend (npm) dependencies
+	uv sync
+	cd frontend && npm install
+
+dev: ## Run backend (:8745) + frontend (:5173) with hot reload
+	$(MAKE) -j2 dev-api dev-ui
+
+dev-api: ## Run the FastAPI backend only (hot reload)
+	uv run uvicorn --factory aipromptdock.server:create_app --reload --port 8745
+
+dev-ui: ## Run the Vite dev server only
+	cd frontend && npm run dev
+
+build-ui: ## Build the SPA into src/aipromptdock/web/static/
+	cd frontend && npm run build
+
+build: build-ui ## Build the distributable wheel (UI bundled inside)
+	uv build
+
+test: ## Run the Python test suite
+	uv run pytest
+
+lint: ## ruff + mypy + tsc
+	uv run ruff check src tests
+	uv run ruff format --check src tests
+	uv run mypy src
+	cd frontend && npm run typecheck
+
+fmt: ## Auto-format Python code
+	uv run ruff check --fix src tests
+	uv run ruff format src tests
+
+clean: ## Remove build artifacts and caches
+	rm -rf dist src/aipromptdock/web/static .pytest_cache .mypy_cache .ruff_cache
+
+.PHONY: help install dev dev-api dev-ui build-ui build test lint fmt clean

aipromptdock-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: aipromptdock
+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: 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="AI Prompt Dock icon"> AI Prompt Dock
+
+> A local-first timeline for every prompt you've ever sent to **Claude Code**,
+> **Codex CLI**, and **Gemini CLI**.
+
+AI Prompt Dock 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 aipromptdock   # or: pipx install aipromptdock / pip install aipromptdock
+aipromptdock                   # scan → serve → open http://127.0.0.1:8745
+```
+
+Or try it without installing anything:
+
+```bash
+uvx aipromptdock
+```
+
+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/aipromptdock/#files).
+
+> ⚠️ Running from a git clone (`uv run aipromptdock`) 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
+aipromptdock --port 9000 --no-browser   # custom port, stay in the terminal
+aipromptdock 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
+
+```
+aipromptdock-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/
+│   └── aipromptdock/           # ── The Python package ──
+│       ├── cli.py              # Typer CLI entry point (`aipromptdock` 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/aipromptdock/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/aipromptdock/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 aipromptdock-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 aipromptdock.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 aipromptdock            # serve everything from :8745
+```
+
+Other useful targets:
+
+```bash
+make test      # pytest
+make build     # build the SPA, then the wheel (dist/aipromptdock-*.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)

aipromptdock-0.1.0/README.md

@@ -0,0 +1,155 @@
+# <img src="frontend/public/favicon.svg" width="26" alt="AI Prompt Dock icon"> AI Prompt Dock
+
+> A local-first timeline for every prompt you've ever sent to **Claude Code**,
+> **Codex CLI**, and **Gemini CLI**.
+
+AI Prompt Dock 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 aipromptdock   # or: pipx install aipromptdock / pip install aipromptdock
+aipromptdock                   # scan → serve → open http://127.0.0.1:8745
+```
+
+Or try it without installing anything:
+
+```bash
+uvx aipromptdock
+```
+
+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/aipromptdock/#files).
+
+> ⚠️ Running from a git clone (`uv run aipromptdock`) 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
+aipromptdock --port 9000 --no-browser   # custom port, stay in the terminal
+aipromptdock 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
+
+```
+aipromptdock-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/
+│   └── aipromptdock/           # ── The Python package ──
+│       ├── cli.py              # Typer CLI entry point (`aipromptdock` 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/aipromptdock/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/aipromptdock/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 aipromptdock-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 aipromptdock.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 aipromptdock            # serve everything from :8745
+```
+
+Other useful targets:
+
+```bash
+make test      # pytest
+make build     # build the SPA, then the wheel (dist/aipromptdock-*.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)

aipromptdock-0.1.0/frontend/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="A local timeline for your Claude Code, Codex CLI, and Gemini CLI prompts." />
+    <title>AI Prompt Dock</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>