ph is a transparent wrapper for AI CLI tools (such as Gemini CLI, Claude CLI, etc.). It captures every prompt into a local SQLite database, providing full-text and semantic search, automatic background analysis, and Git context snapshots.
- 📥 Automatic Capture: Saves prompts, output (if non-interactive), and metadata.
- 🌳 Git Context: Saves branch, modified files, and diff at the time of the prompt.
- 🔍 Advanced Search: Textual search (FTS5) and semantic search (vectorial).
- 🧠 Background Analysis: Automatic prompt analysis (role, tags, relevance) via Ollama or Gemini.
- 🖥️ Interactive TUI: Interactive browser (
ph browse) to manage history.
# Clone and local build
git clone git@github.com:gi4nks/ph.git
cd ph
npm install
make build
make install # Installs the global 'ph' linkThe tool uses a configuration file at ~/.ph_config.json.
ph config set gemini-api-key "YOUR_KEY"
ph config set analyze-provider gemini # or 'ollama' (default)
ph config set background-analysis true # Enable auto-analysisph stores its data locally to ensure privacy and fast access.
| Item | Default Path | Description |
|---|---|---|
| Database | ~/.prompt_history.db |
SQLite database with FTS5 and vector embeddings. |
| Config | ~/.ph_config.json |
JSON configuration file (stored with 0o600 permissions). |
You can move your database to a different location (e.g., an external drive or a cloud-synced folder):
ph config set db-path "/path/to/your/custom.db"As you use ph, the database might grow due to Git diffs and metadata. Use these commands to keep it lean:
# Remove prompts shorter than 20 chars or older than 30 days
ph cleanup --min-length 20 --days 30
# Compact the database file to reclaim disk space
ph vacuum
# Run a dry-run to see what would be deleted
ph cleanup --dry-run --days 60The database uses WAL (Write-Ahead Logging) mode, which allows concurrent read and write operations. This is crucial for the Background Analysis system to work without locking your CLI session.
Hooks allow ph to automatically capture prompts and responses from other AI CLI tools by integrating directly with their native hook systems.
Hooks are located in the hooks/ folder. Instead of wrapping the execution, they act as post-action handlers (e.g., AfterAgent in Gemini CLI or Stop in Claude Code) that send the prompt and response to ph log in the background.
- Link the hook script to your
.geminifolder:ln -sf /path/to/ph/hooks/gemini/ph-hook.sh ~/.gemini/ph-hook.sh - Register the hook in
~/.gemini/settings.json:{ "hooks": { "AfterAgent": [ { "hooks": [ { "type": "command", "command": "~/.gemini/ph-hook.sh" } ] } ] } }
- Link the hook script to your
.claudefolder:ln -sf /path/to/ph/hooks/claude/ph-hook.sh ~/.claude/ph-hook.sh - Register the hook in
~/.claude/settings.json:{ "hooks": { "Stop": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": "~/.claude/ph-hook.sh", "async": true } ] } ] } }
The hooks will automatically send every interaction to ph without requiring any shell aliases or manual capture commands.
ph search "how to refactor" # Textual search
ph search --semantic "refactoring" # Semantic searchph browseHotkeys: f (filters), e (edit metadata), r (rerun prompt), y (copy), x (delete).
The project follows Semantic Versioning (SemVer) and uses Conventional Commits. Releases are managed via standard-version.
To create a new version (updates package.json, generates CHANGELOG.md, and creates a Git tag):
make release-patch # Increments: 0.1.0 -> 0.1.1 (fixes and small changes)
make release-minor # Increments: 0.1.1 -> 0.2.0 (new compatible features)
make release-major # Increments: 0.2.0 -> 1.0.0 (breaking changes)After the release, remember to push the tags to trigger the GitHub Action for publication:
git push --follow-tags origin mainThe package will be automatically built and published to npmjs.org.
Install globally with:
npm install -g @gi4nks/phph export --format md --limit 5 > prompts.md