promptlens

Your prompting habits, visualized. A Claude Code hook + terminal dashboard that scores, categorizes, and tracks every prompt you send — helping you spot patterns and level up.

Get started GitHub

promptlens

◆ PROMPTLENS Prompts 47 Sessions 12 Avg quality 7.3/10 Top category feature ? help

▸ Selected Session a3f8c21e9b04 Project promptlens ~/.claude/hooks/promptlens

	TIME	CATEGORY	COMPLEXITY	SCORE	QUALITY	INSIGHTS
▸	2m ago	feature	medium	8	████████░░	Clear goal, good context
	15m ago	debug	high	6	██████░░░░	Missing error details
	1h ago	refactor	low	9	█████████░	Precise scope, clean ask
	2h ago	explain	medium	4	████░░░░░░	Too vague, needs focus
	3h ago	config	low	7	███████░░░	[img] Screenshot adds context
	4h ago	test	medium	7	███████░░░	Good scope, add edge cases
	5h ago	docs	low	8	████████░░	Specific, well-structured

Projects

promptlens ████████ 28

api-server ████ 12

dotfiles ██ 7

// How it works

You prompt as usual

A UserPromptSubmit hook runs silently in the background every time you send a prompt. Nothing changes about your workflow.

Each prompt gets scored

A fast, cheap LLM call via OpenRouter classifies your prompt's category, complexity, and quality (1-10) with a brief insight. Results are stored locally in SQLite.

Patterns emerge

Open the dashboard anytime to see your prompt history — quality trends, what types of work you do most, which projects get the most attention.

// Why promptlens

See what you're actually asking

Every prompt scored 1-10. Spot vague prompts, track improvement over time.

Understand your work patterns

Are you mostly debugging? Building features? See the breakdown across 8 categories.

Compare across projects

Per-project breakdowns show which codebases get the most attention and prompt quality.

Zero friction

Runs silently as a hook. No changes to how you use Claude Code. Just open the dashboard when curious.

Local storage, your data

All results stored in a local SQLite database. The only external call is a cheap LLM inference via OpenRouter for analysis.

Handles images too

Detects when you attach screenshots or diagrams and factors them into the analysis.

// Get started

You'll need Bun and an OpenRouter API key (used for the cheap LLM call that scores each prompt).

RECOMMENDED

Install via Claude Code

Copy this prompt, paste it into a Claude Code session, and it will set everything up for you. You'll just need to provide your OpenRouter API key when asked.

Install promptlens for me. Here's what to do: 1. Check if bun is installed by running `which bun`. If it's not found, install it with: curl -fsSL https://bun.sh/install | bash — then make sure it's available in the current shell. 2. Clone the repo into ~/.claude/hooks/promptlens: git clone https://github.com/iaserrat/promptlens ~/.claude/hooks/promptlens 3. Run `bun install` in that directory, then `bun link` to make the `promptlens` command available globally. 4. Create the file ~/.claude/hooks/promptlens/.env with a placeholder: OPENROUTER_API_KEY=paste-your-key-here Then open it in my default text editor (use `open` on macOS or `xdg-open` on Linux) so I can paste my OpenRouter API key securely. Wait for me to confirm I've saved the file before continuing. 5. Add this hook to my ~/.claude/settings.json (merge with existing hooks if any). IMPORTANT: use $HOME instead of ~ in the command string, because bun's --env-file flag does not expand tilde: { "hooks": { "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "bun --env-file=$HOME/.claude/hooks/promptlens/.env run $HOME/.claude/hooks/promptlens/hook.ts", "async": true } ] } ] } }

▸ Or install manually

1. Clone & install

$ git clone https://github.com/iaserrat/promptlens ~/.claude/hooks/promptlens
$ cd ~/.claude/hooks/promptlens
$ bun install
$ bun link    # makes `promptlens` available globally

2. Add your OpenRouter key

# Create ~/.claude/hooks/promptlens/.env
OPENROUTER_API_KEY=sk-or-...
OPENROUTER_MODEL=anthropic/claude-haiku-4.5    # optional, this is the default
PROMPTLENS_MIN_LENGTH=50# optional, min chars to analyze

3. Register the hook in Claude Code

Add this to ~/.claude/settings.json (or your project-level settings):

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bun --env-file=$HOME/.claude/hooks/promptlens/.env run $HOME/.claude/hooks/promptlens/hook.ts",
            "async": true
          }
        ]
      }
    ]
  }
}

4. Open the dashboard

$ promptlens

Start using Claude Code as normal. Analyses appear in the dashboard automatically.