promptvault-py 0.0.11

Your Claude Code & Codex conversations, searchable forever.

The Problem

Claude Code (~/.claude/history.jsonl) and Codex (~/.codex/sessions/) store conversations — not searchable, not browsable, not persistent. Both agents compact and delete old sessions without warning.

pv turns that history into a searchable markdown library + SQLite database. It auto-detects Codex and merges both agents into one vault, tagging each conversation by source (cc = Claude Code, cx = Codex) with a ctrl-s filter to narrow by agent. Browse in Obsidian, search from the terminal with fzf. Zero dependencies. Pure stdlib.

Quick Start

# recommended — fast, isolated, always on PATH
uv tool install promptvault-py

# alternative — same idea, traditional tool
pipx install promptvault-py

pv-sync                        # sync your Claude Code history
pv                             # browse conversations
pv search "database migration" # full-text search

# upgrade to latest version
uv tool upgrade promptvault-py   # or: pipx upgrade promptvault-py

Don't have uv? curl -LsSf https://astral.sh/uv/install.sh | sh (docs)

Don't have pipx? brew install pipx or pip install --user pipx (docs)

Both tools install pv into an isolated virtualenv and symlink the executable to ~/.local/bin/, so it's available globally — no environment activation needed.

pv is the short alias. promptvault / promptvault-sync also work.

Optional: install fzf for the interactive UI (brew install fzf / apt install fzf). Without it, pv falls back to plain text.

How It Works

pv-sync reads Claude Code's history.jsonl and (if ~/.codex/ exists) Codex's rollout sessions, groups prompts by conversation, and generates:

1. Markdown vault — One .md per conversation, YYYY/MM/ structure, YAML frontmatter (incl. source). Drop into Obsidian.
2. SQLite database — FTS5 full-text search with BM25 ranking. Millisecond queries. Each conversation keeps its source.

The sync is idempotent — always rebuilds from source, impossible to reach a bad state. Resolves pasted-text placeholders, deduplicates prompts, filters slash commands, cleans whitespace.

Commands

All commands launch fzf by default (split pane: conversation list + live preview). Add --no-fzf for plain text.

Controls:

Full documentation: docs/usage.md

Shell Widget

Insert a previous prompt directly into your command line with Alt-P:

# Add to your shell config:
eval "$(pv shell-init zsh)"    # or bash

Customise the key with PROMPTVAULT_WIDGET_KEY (default: \ep = Alt-P).

Real-Time Capture

A Claude Code hook captures prompts the moment you send them — no sync needed.

Add to ~/.claude/hooks.json:

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "python3 /path/to/promptvault/promptvault/hook.py",
        "timeout": 5000
      }]
    }]
  }
}

Fast (<50ms), silent (no stdout), safe (errors swallowed). Captures to ~/.claude/prompt-library/capture.jsonl.

Windows: use python instead of python3 and backslash paths.

Markdown Vault

Each conversation becomes an Obsidian-compatible .md with YAML frontmatter:

~/.claude/prompt-library/vault/
├── _index.md
├── 2026/
│   └── 03/
│       ├── 2026-03-25__c792e74f__refactor-user-auth.md
│       └── ...

Open as an Obsidian vault. The Calendar plugin works well for browsing.

Environment Variables

Contributing

Contributions welcome! See CONTRIBUTING.md. 340 tests, all synthetic data.

git clone https://github.com/reidemeister94/promptvault.git
cd promptvault
uv tool install --editable .   # global "pv" that tracks your local source
make setup-dev-env
make test && make lint

License

MIT

If pv saves your prompts, save us a

Report an issue · Contribute