Stop losing your best prompts. Start using PromptVault.
Have you ever crafted the perfect prompt, only to lose it in a sea of chat histories, scattered notes, or random text files? As AI agents become a core part of our daily workflows, managing how we interact with them shouldn't be an afterthought.
PromptVault is your centralized command center for AI interactions. It’s a self-hosted, local-first dashboard that watches your AI CLI history files (Claude, Gemini, Antigravity) in real time and gives you a searchable, categorized library of everything you've ever typed into an AI agent.
- 🧠 Never Lose a Prompt: Say goodbye to digging through past conversations. Save your most effective queries and build a personal library of high-performing prompts.
- ⚙️ Parameterized Templates: Stop re-typing the same context. Build dynamic prompts with custom
{{variable}}slots, so you can adapt your best queries on the fly. - ⚡ Seamless Workflow: Designed for speed and efficiency, PromptVault removes the friction between having an idea and executing it.
- 🔒 100% Private: Your data never leaves your machine. All history stays in a local SQLite file.
Keywords: AI prompt tracker, Claude Code history, Gemini CLI history, prompt manager, self-hosted AI tools, prompt library, NestJS, Next.js, Docker, SQLite, open source
- Automatic history import — picks up Claude Code, Gemini CLI, and Antigravity CLI history on startup, then watches for new entries in real time
- Full-text search — filter by keyword, source (claude / gemini / antigravity), project, date range, and favorites
- Categories — organize prompts into color-coded, icon-labeled groups
- Templates — create reusable prompt blueprints with
{{variable}}slots and a live preview - Hardware dashboard — live CPU, RAM, temperature, and Docker container stats
- Agent Hub — scans your projects for AI agent config files (CLAUDE.md, AGENTS.md, .cursorrules, etc.) and shows a health score per project
- Self-hosted — your data never leaves your machine; all history stays in a local SQLite file
- One-command start —
docker compose up -dis all you need
| Layer | Technology | Path | Port |
|---|---|---|---|
| Frontend | Next.js (App Router) + Tailwind CSS | apps/web |
8654 |
| Backend | NestJS + TypeORM + Swagger | apps/api |
8653 |
| Database | SQLite (via better-sqlite3) | ./data/ |
— |
We've made setup as easy as possible, even if you aren't a developer!
- Docker Desktop: Download and install it. Make sure it's running in the background.
- At least one AI tool installed: Claude Code, Gemini CLI, or Antigravity CLI.
Open your terminal (Terminal on Mac/Linux, or PowerShell on Windows) and paste these commands:
git clone https://github.com/yourusername/prompt-tracker.git
cd prompt-tracker
bash setup.shOur friendly setup wizard will check your system, find your AI tools, and configure everything automatically.
If you prefer to skip the wizard, you can start the app manually:
# Clone the repository
git clone https://github.com/yourusername/prompt-tracker.git
cd prompt-tracker
# Copy the default configuration
cp .env.example .env
# Start the application
docker compose up -d🎉 That's it! Open http://localhost:8654 in your browser. Your prompts will start appearing within seconds.
Copy .env.example to .env. All settings have sensible defaults; you only need to change what's relevant to your setup:
# Optional: protect the API with a secret key
API_KEY_SERVER=your-secret-here
# Logging
LOG_LEVEL=DEBUG # DEBUG | INFO | WARN | ERROR
# Override history paths if your CLIs use non-standard locations
# CLAUDE_HISTORY_PATH=/home/youruser/.claude/history.jsonl
# CLAUDE_PROJECTS_PATH=/home/youruser/.claude/projects
# GEMINI_HISTORY_PATH=/home/youruser/.gemini/tmp
# ANTIGRAVITY_HISTORY_PATH=/home/youruser/.gemini/antigravity-cli/history.jsonl
# ANTIGRAVITY_BRAIN_PATH=/home/youruser/.gemini/antigravity-cli/brain
# Agent Hub — mount a directory of projects for scanning
# PROJECTS_DIR=/home/youruser/IdeaProjects
# Agent Hub — shared skills directory (default: ~/.agents/skills)
# AGENTS_GLOBAL_SKILLS_PATH=/home/youruser/.agents/skillsDo not run PromptVault as root. The application does not need elevated privileges. Running it as root exposes your entire filesystem to the container process.
PromptVault is designed for local use only — it binds to 0.0.0.0 so you can open it from other devices on the same home network, but it has no authentication by default.
| Scenario | What to do |
|---|---|
| Trusted home network | Default settings are fine |
| Shared or office LAN | Set API_KEY_SERVER=<random-secret> in .env — every request will require an X-API-Key header |
| Exposed to the internet | Not supported. PromptVault is designed exclusively for local developer machines. |
Ports 8653 (API) and 8654 (Web UI) should never be opened directly to the internet.
PromptVault is free and open source (MIT). The only "cost" is compute on your own machine:
| Resource | At idle | Under load |
|---|---|---|
| RAM | ~500 MB (Docker + both containers) | ~700 MB |
| Disk | ~2 GB (Docker images) + tiny SQLite file | grows with history |
| CPU | <1% | <5% during import |
| Cloud / telemetry | None — ever | — |
See docs/modules/ for per-module deep dives covering how each part of PromptVault works and why it was built that way.
Single-file executables for Linux, macOS, and Windows are planned for v1.1 — bundled Node runtime + Next.js standalone + better-sqlite3 prebuilt addon, so you can ./promptvault and skip Docker entirely. v1.0 ships Docker-first.
prompt-tracker/
├── apps/
│ ├── api/ # NestJS backend (SQLite, Swagger, file watcher)
│ │ └── src/modules/
│ │ ├── prompts/ # Prompt history: import, search (FTS5), filter
│ │ ├── templates/ # Reusable templates with {{variable}} slots
│ │ ├── categories/ # Category management
│ │ ├── hardware/ # Live CPU/RAM/Docker metrics (15s poll)
│ │ ├── watcher/ # Chokidar-based incremental history file watcher
│ │ ├── settings/ # K/V config store + setup flow state machine
│ │ ├── agent-configs/ # Agent Hub: scans projects for AI config files
│ │ └── health/ # Liveness probe for Docker health checks
│ └── web/ # Next.js frontend (App Router + Tailwind)
│ └── src/app/
│ ├── page.tsx # Dashboard
│ ├── prompts/ # Prompt browser
│ ├── templates/ # Template manager
│ ├── categories/ # Category manager
│ ├── hardware/ # Hardware monitor
│ ├── agent-hub/ # Agent Hub
│ └── setup/ # First-run onboarding wizard
├── docs/
│ └── modules/ # Per-module deep-dive documentation
├── data/
│ └── promptvault.sqlite # All data lives here
├── docker-compose.yml # Local stack (api + web)
├── setup.sh # Interactive setup wizard
└── SETUP.md # Full setup guide
| Source | Default path | What's imported |
|---|---|---|
| Claude Code | ~/.claude/history.jsonl + ~/.claude/projects/ |
Global history + full session conversations |
| Gemini CLI | ~/.gemini/tmp/<workspace>/chats/ |
Per-workspace session chat logs |
| Antigravity CLI | ~/.gemini/antigravity-cli/history.jsonl + brain/ |
Global history + session logs |
The NestJS API is fully documented via Swagger at http://localhost:8653/api.
All endpoints are versioned under /v1:
| Endpoint | Description |
|---|---|
GET /v1/prompts |
List prompts with filtering, search, and pagination |
POST /v1/prompts/import |
Trigger a full history re-import |
GET /v1/prompts/stats |
Counts by source, today, favorites, top projects |
GET /v1/templates |
List templates |
POST /v1/templates |
Create a template |
GET /v1/categories |
List categories |
GET /v1/hardware |
Live CPU, RAM, temperature, Docker stats |
GET /v1/health |
API + database liveness check |
# Full stack with hot-reload
docker compose up -d
docker compose logs -f api web
# Backend only (without Docker)
cd apps/api
npm install && npm run migration:run
npm run start:dev # → http://localhost:8653
# Frontend only (without Docker)
cd apps/web
npm install
npm run dev # → http://localhost:8654
# Tests
cd apps/api && npm test
cd apps/web && npm test| OS | Supported | Notes |
|---|---|---|
| Linux (Ubuntu, Debian, Arch…) | ✅ | Native; CPU temperature via lm-sensors |
| macOS (Intel + Apple Silicon) | ✅ | Docker Desktop required |
| Windows | ✅ | Docker Desktop + WSL2 required; run setup.sh in Git Bash or WSL2 |
- Export prompts to JSON / CSV
- Tag-based filtering
- Prompt diffing (compare versions over time)
- Additional source adapters (Copilot, Aider, Continue)
- REST webhooks for new prompt events
Open source for personal and non-commercial use. Commercial use requires explicit permission. See LICENSE for details.
This repository is configured for professional AI-agent collaboration. The following files are automatically loaded by each supported agent:
| Agent | Config file |
|---|---|
| Claude Code | CLAUDE.md → AGENTS.md |
| Gemini CLI | GEMINI.md (includes @file auto-loads) |
| GitHub Copilot | .github/copilot-instructions.md |
| Cursor | .cursor/rules/mandatory.mdc (always), + context-sensitive rules |
| Any agent | AGENTS.md (canonical source of truth) |
The shared skill library lives in .agents/:
.agents/
├── rules/mandatory.md # always-on rules
├── skills/project/ # this repo's workflow playbooks
├── skills/external/ # framework & tool patterns
└── subagents/ # test-writer, migration-writer
See .agents/README.md for the full index.
Issues and pull requests are welcome. Please read the AGENTS.md for coding conventions before submitting a PR.