PromptHive 🐝

Professional prompt manager for developers. Terminal-native, sub-80ms operations, works with any AI tool.

TL;DR

# Install (Latest: v0.1.7) - Multiple Options
brew tap CalmHive/prompthive https://github.com/CalmHive/prompthive.git
brew install prompthive
# OR: cargo install prompthive

# Multiple Workflows - Choose Your Style

# 1. Perfect commit messages (PRODUCTION READY ✅)
git diff --staged | ph use essentials/commit | llm     # Instant (45ms)

# 2. Instant debugging (BATTLE TESTED ✅)
cat error.log | ph use essentials/debug | claude           # Piped input (48ms)
ph use essentials/debug "Fix type error in handleSubmit" | llm  # Direct input (43ms)

# 3. Complete PR workflows
git diff main...HEAD | ph use essentials/pr | claude -p | gh pr create --body-file -  # Complex workflows

Why? Because copy-pasting from ChatGPT history takes 30+ seconds. PromptHive takes 45ms.

Current Version: 0.1.7 - Production ready with professional registry, magic link authentication, team collaboration, and viral sharing

🚀 Philosophy: Terminal-First Development | Spec-Driven AI Engineering
📁 Documentation: See README.md for complete usage guide

Core Promise: Every command under 80ms. It's a TOOL, not a LIBRARY.

Unix Philosophy: We don't run AI. We manage prompts perfectly, and pipe them to ANY AI tool you prefer. Like npm doesn't run JavaScript, we don't run prompts. We just make them instantly accessible.

# PromptHive + Your Favorite AI Tools

# Interactive (read output, then act):
ph use essentials/debug "API timeout" | claude        # Read analysis, fix manually
ph use essentials/pr | llm                           # Read description, create PR
ph use essentials/code-review | aichat               # Read review, apply changes

# Direct piping (output flows to command):
git diff --staged | ph use essentials/commit | claude -p | git commit -F -
ph use essentials/issue "Bug report" | claude -p | gh issue create --body-file -

🚀 Installation

Homebrew (macOS/Linux) - Available Now ✅

# Add the custom tap
brew tap CalmHive/prompthive https://github.com/CalmHive/prompthive.git

# Install prompthive
brew install prompthive

# Verify installation
ph --version

Cargo (Rust) - Coming June 16, 2025

# Install from crates.io (available after June 16, 2025)
cargo install prompthive

# Verify installation
ph --version

Current Status: Homebrew installation is fully working. Cargo installation will be available after June 16, 2025.

Shell Completions

After installation, set up shell completions for the best experience:

Bash

ph completion bash > ~/.bash_completion.d/prompthive
source ~/.bash_completion.d/prompthive

Zsh

ph completion zsh > ~/.zsh_completions/_prompthive
# Add to ~/.zshrc: fpath=(~/.zsh_completions $fpath)

Fish

ph completion fish > ~/.config/fish/completions/ph.fish

Quickstart

# Use built-in essentials (ready to go!)
git diff --staged | ph use essentials/commit | llm   # Perfect commit messages
ph use essentials/debug "Fix auth timeout error" | claude # Analyze any error

# Use immediately with real workflows
git diff main...HEAD | ph use essentials/pr | llm     # Generate PR descriptions
cat main.py | ph use essentials/code-review | llm    # Review any code

# Use with ANY AI tool (copies to clipboard if terminal, pipes if piped)
ph use essentials/debug "Fix auth timeout" | llm     # LLM by Simon Willison
git diff --staged | ph use essentials/commit | aichat    # AIChat
git diff main...HEAD | ph use essentials/pr | claude  # Interactive PR description
cat legacy-code.js | ph use essentials/refactor | mods    # Mods
cat api.py | ph use essentials/generate-tests | sgpt      # Shell GPT

# Lightning-fast operations
ph ls                                      # List all prompts
ph f commit                                # Fuzzy search essentials
ph u essentials/debug-error                # Short aliases work

# Share with the world
ph bank publish my-workflow-prompts
ph install @team/essentials

"But Why Not Just..."

...use text files?

• Can't fuzzy search across them in 50ms
• No smart matching (ph u au → auth-basic)
• No metadata or descriptions
• No sharing/versioning/teams

...use shell aliases?

# This gets unwieldy fast:
alias fix="echo 'Debug this error and suggest a fix'"
alias commit="echo 'Generate a commit message from the diff'"
alias review="echo 'Review this code for issues'"
# vs
ph f debug   # Fuzzy finds essentials/debug-error instantly

...use ChatGPT/Claude history?

• Takes 30+ seconds to search and copy
• Lost between browser tabs
• Can't pipe or compose
• No version control

...use GitHub Gists?

• Network latency (2-5 seconds minimum)
• No offline access
• Requires browser
• Can't pipe directly

See this README for complete documentation.

Commands (v0.1.6)

ph use <name>         # Use a prompt (u) - auto-clipboard, save, append, file
ph show <name>        # Display prompt (s) - with I/O options
ph new <name>         # Create prompt (n) - smart detection
ph edit <name>        # Edit prompt (e) - opens $EDITOR  
ph find <query>       # Search prompts (f) - fuzzy matching
ph ls                 # List prompts (l) - see all
ph delete <name>      # Delete prompt (d) - with confirm
ph clean <text>       # Clean and format text with AI-style processing

# Just run 'ph' to launch the TUI (like lazygit)
ph                    # Launch interactive TUI

### Advanced Features
```bash
ph compose <prompts>  # Chain prompts together
ph stats              # Usage analytics dashboard  
ph completion <shell> # Generate shell completions
ph login              # Authenticate with registry for sync
ph sync               # Sync prompts with cloud (Pro feature) ✅ WORKING
ph sync status         # Check sync status and conflicts ✅ WORKING
ph sync push          # Push local changes to cloud ✅ WORKING
ph sync pull          # Pull cloud changes locally ✅ WORKING

🚀 Power User Examples

Template Variables - Supercharge Your Prompts

# Built-in variables make prompts dynamic
ph new standup "Daily standup for {date} by {user} on {hostname}"
ph new bug-report "Bug in {pwd} on branch {git_branch} ({git_status})"

# Set custom variables for your workflow
ph vars set project "PromptHive"
ph vars set team "backend"
ph vars set api_version "v2.0"

# Use them in any prompt
ph new feature "Feature for {project} {api_version} by {team} team"
ph use feature "OAuth implementation" | llm
# Output: "Feature for PromptHive v2.0 by backend team\n\nOAuth implementation"

# Environment variables work too
ph new deploy "Deploy to {env:AWS_REGION} in {env:ENVIRONMENT}"

Version Control - Never Lose a Good Prompt

# Tag important versions of your prompts
ph version api-design v1.0 -m "Initial stable API prompt"
ph version api-design v1.1 -m "Added error handling section"
ph version api-design v2.0 -m "Complete rewrite for REST best practices"

# View history
ph versions api-design
# 📚 Version history for 'api-design'
# 📌 v2.0 (a3b4c5d6) - Complete rewrite for REST best practices
# 📌 v1.1 (87654321) - Added error handling section  
# 📌 v1.0 (12345678) - Initial stable API prompt

# Rollback when needed
ph rollback api-design v1.1
# ✅ Rolled back 'api-design' to version 'v1.1'

Batch Operations - Manage Prompt Libraries

# Add tags to multiple prompts
ph batch "find api" --add-tag production
ph batch "backend/" --add-tag team:backend

# Clean up old prompts
ph batch "test-*" --move-to archive/
ph batch "old-*" --delete  # With confirmation

# Export prompt collections
ph batch "essentials/" --export ./team-essentials
ph batch "find prod" -f production-prompts.txt

Diff & Merge - Collaborate on Prompts

# Compare prompt versions
ph diff api-v1 api-v2
ph diff api-v1 api-v2 --format side-by-side
ph diff local-prompt team/shared-prompt --context 10

# Merge improvements
ph merge team/api-enhanced api-design --backup
ph merge experimental-fix stable-prompt --preview

Web Dashboard - Visual Analytics

# Open interactive dashboard
ph web                    # Full dashboard
ph web stats             # Usage analytics
ph web prompts           # Browse all prompts
ph web --no-browser      # Generate HTML only

Command History - Track Your Usage

# See what you've been using
ph history                        # Recent commands
ph history --search "api"        # Find specific usage
ph history --command use          # Filter by command
ph history --today               # Today's activity

🎯 Unified I/O Design - Smart Defaults

PromptHive uses intelligent defaults based on context, reducing typing while maintaining flexibility:

Text Transformation Commands (use, show, clean)

In Terminal (TTY):

• Auto-copies to clipboard by default
• No stdout output (content is on clipboard)
• Use -q to suppress clipboard and output to stdout instead

When Piping:

• Outputs to stdout for pipe compatibility
• No auto-clipboard (use -c to force clipboard)

# Terminal usage - auto-clipboard
ph clean "messy text"                    # ✓ Copied to clipboard (2ms)
ph use api-design "Create user endpoint" # ✓ Copied to clipboard (3ms)

# Piping - outputs to stdout
echo "messy text" | ph clean | ph use formatter | claude -p

# Force clipboard even when piping
echo "important" | ph clean -c          # Copies AND outputs

# Quiet mode in terminal
ph clean "text" -q                      # Outputs to stdout, no clipboard

Query Commands (ls, find)

Always outputs to stdout (auto-clipboard would be too noisy)

• Use -c to explicitly copy results
• Use -s to save as a new prompt

ph ls                                    # Lists to stdout
ph find "api" -c                        # Find and copy results
ph ls -s "my-prompt-list"               # Save list as a new prompt

Universal I/O Flags

Every command supports these consistent flags:

• -s NAME - Save output as a new prompt
• -a NAME - Append output to existing prompt
• -c - Force copy to clipboard
• -f PATH - Write to file (with bidirectional sync)
• -q - Quiet mode (suppress default behaviors)
• -e - Edit before output (where applicable)

Smart File Operations

The -f flag creates bidirectional sync by default:

# Create prompt with automatic file sync
ph new "API guidelines" -f              # Creates ./api-guidelines.md
ph new "API guidelines" -f api.md       # Creates ./api.md

# Smart naming when path not provided
ph use api-design "endpoints" -f        # Creates ./api-design-output.md

# Bidirectional sync means:
# - Edit the file → prompt updates
# - Edit the prompt → file updates
# - Always stay in sync!

Composable Flags

All flags work together sensibly:

# Clean, save, append, copy, and write to file
ph clean "text" -s cleaned -a log -c -f output.md

# Use prompt, edit result, save, and sync to file  
ph use template -e -s edited -f template-output.md

# Find prompts, save results, copy to clipboard
ph find "api" -s search-results -c

Design Philosophy

• Smart defaults: Do the right thing based on context
• Explicit overrides: Flags always override defaults
• Composability: All flags combine logically
• No surprises: Predictable behavior in all contexts

Performance

PromptHive operations are optimized for instant prompt access:

$ time ph use essentials/commit
✓ Prompt loaded and copied to clipboard (3ms)
real    0m0.045s

$ ph ls
📋 Your prompts: (12ms)
  essentials/commit       - Semantic commit messages
  essentials/debug-error  - Error analysis & fixes
  essentials/pr          - Pull request descriptions
  essentials/code-review - Code review analysis
  essentials/refactor    - Code refactoring

What these times represent:

• PromptHive operations: File I/O, prompt processing, fuzzy matching (~2-50ms)
• AI processing time: Separate - depends on your AI tool (5-30+ seconds)
• Value proposition: Zero-latency prompt access vs. writing prompts from scratch

The real speed gain: Instead of spending 2-5 minutes crafting the perfect prompt, you get battle-tested prompts instantly.

Partial Matching (Like JJ)

PromptHive uses smart partial matching:

$ ph use d
# If unique, uses the match
# If ambiguous, shows options:
Error: Multiple matches. Did you mean:
  essentials/debug-error    (de)   - Error analysis & fixes
  essentials/document       (do)   - Documentation generation  
  custom/deploy            (dep)  - Deployment scripts

$ ph use de  # Now unique - uses 'essentials/debug-error'

The Magic: Composition

PromptHive is the ONLY tool that lets you chain prompts:

# Fix a bug completely
cat error.log | \
  ph use analyze-error | \
  ph use find-root-cause | \
  ph use generate-fix | \
  ph use add-tests | \
  claude

# Each prompt transforms the previous output
# Total time: 250ms for 5 prompts

Real-World Usage

Daily Developer Workflows

# 🔥 Auto-generate perfect commit messages
git diff --staged | ph use essentials/commit | llm

# 🐛 Debug errors instantly
cat error.log | ph use essentials/debug | aichat
ph use essentials/debug "Fix timeout in API calls" | claude

# 📝 Generate PR descriptions
git diff main...HEAD | ph use essentials/pr | claude

# 🧪 Create tests from code
cat src/api.js | ph use essentials/generate-tests | llm > src/api.test.js

# 📚 Document your code
cat complex-function.py | ph use essentials/docstring | llm

# 🔍 Code review helper
git show HEAD | ph use essentials/code-review | aichat > review-notes.md

Advanced Workflows

# Chain multiple prompts for complex tasks
cat buggy-code.js | \
  ph use essentials/debug | llm | \
  ph use essentials/refactor | llm | \
  ph use essentials/generate-tests | llm > fixed-code.js

# Morning standup automation
git log --since=yesterday --oneline | \
  ph use essentials/standup | llm > standup.md

# Refactor legacy code
cat old-api.py | \
  ph use essentials/refactor | llm | \
  ph use essentials/add-types | llm > modern-api.py

🧙 Workflow Automation Examples

# AI-Powered Git Workflow
alias smart-commit='git diff --staged | ph use commit-message | llm | git commit -F -'
alias smart-pr='git diff main...HEAD | ph use essentials/pr | claude -p | gh pr create --body-file -'

# Automated Code Review Pipeline
function ai-review() {
  git diff main...HEAD | \
    ph compose check-style,find-bugs,suggest-improvements | \
    llm > review-$(date +%Y%m%d).md
}

# Daily Standup Generator
function standup() {
  echo "Yesterday: $(git log --since=yesterday --author=$(git config user.name) --oneline)" | \
    ph use standup --edit | \
    pbcopy
}

# Smart Documentation Generator  
function doc-this() {
  cat "$1" | \
    ph compose analyze-code,generate-docs,add-examples | \
    llm > "${1%.*}.docs.md"
}
  ph use modernize-code | llm | \
  ph use add-types | llm > modern-api.py

🔰 Shell Pipes Primer (for Terminal Newbies)

The Basics

# The pipe | sends output from one command to another
echo "hello" | cat           # Sends "hello" to cat

# Redirect > saves output to a file
echo "hello" > file.txt      # Saves "hello" to file.txt

# Append >> adds to a file without overwriting
echo "world" >> file.txt     # Adds "world" to file.txt

# Input < reads from a file
cat < file.txt               # Reads content from file.txt

With PromptHive

# Simple: Copy to clipboard (when in terminal)
ph use api-design           # Just copies, no pipe needed

# Pipe to AI: Send prompt to AI tool
ph use api-design | llm     # Prompt → AI tool

# Chain: Multiple operations
cat code.js | ph use review | llm | ph new review-result

# Save: Capture output
ph use api | llm > response.txt

# Combine: Mix different sources  
ph use debug "Fix this: $(cat error.log)" | aichat

When to Use What

• No pipe: When you just want to copy a prompt
• Single pipe |: When sending to one AI tool
• Multiple pipes |: When chaining operations
• Redirect >: When saving results
• Cat/Echo: When adding context to prompts

🏦 Prompt Banks - Instant Productivity

Quick Start with Essential Banks

# Option 1: Use pre-installed essentials bank
ph use essentials/commit    # Perfect git commits
ph use essentials/debug     # Fix bugs instantly
ph use essentials/review    # Review PRs like a senior

# Option 2: Create your own banks
mkdir -p ~/.prompthive/banks/team
cp my-prompts/*.md ~/.prompthive/banks/team/
# Now use them: ph use team/api-design

Sharing Banks (Unix Way)

# Personal: Share via Git
cd ~/.prompthive/banks/personal
git init && git add .
git commit -m "feat: my productivity prompts"
git remote add origin github.com/you/prompts
git push

# Team: Clone shared bank
cd ~/.prompthive/banks
git clone github.com/team/prompts team

# Public: Submit PR to community registry
git clone github.com/CalmHive/prompthive-registry
cp -r ~/.prompthive/banks/mybank registry/banks/
git add . && git commit -m "Add mybank"
git push origin mybank

Real Workflows with Banks

# Perfect commits every time
git diff --staged | ph use essentials/commit | llm

# Debug like a senior
cat error.log | ph use essentials/debug | aichat
ph use essentials/debug "API returns 500 on POST /users" | claude

# Full code review
git diff main | ph use essentials/code-review | llm > review.md

# Install a complete workflow
ph install @10x/developer
alias commit='git diff --staged | ph use essentials/commit | llm'
alias review='ph use essentials/review | llm'  
alias standup='git log --since=yesterday | ph use 10x/standup | llm'

Building PromptHive with Itself

We built PromptHive using PromptHive:

# Bootstrap phase
ph new rust-cli
ph use rust-cli | cursor

# Every feature after
ph new add-command
ph use add-command | claude

# Test and iterate
ph search "rust testing"
ph use rust-test | cursor

File Structure

Dead simple, just markdown files:

~/.prompthive/
├── prompts/
│   ├── api.md
│   ├── auth.md
│   └── test.md
├── registry/
│   └── @kentcdodds/
│       └── react/
└── config.toml

Prompt Format

Just markdown with optional frontmatter:

---
id: api
description: REST API design
---

Design a REST API with these requirements:
- Resource: {resource}
- Operations: {operations}
- Include error handling
- Follow REST best practices

Why PromptHive?

1. Speed: 80ms operations are addictive (GitHub: 30+ seconds)
2. Simple: Just like ls and cat - no learning curve
3. Universal: Works with ALL AI tools, not locked to one
4. Offline: Your prompts work without internet
5. Composable: Chain prompts like Unix commands
6. Smart I/O: Auto-clipboard, save, append - works how you think

The Dropbox Moment

"You could just use FTP!" they said about Dropbox. But UX is the product. "You could just use text files!" they'll say about PromptHive. But speed is the product.

80ms vs 30 seconds. Every time. That's the difference.

The Vision

In one year:

• Every tutorial starts with ph install
• Teams have standardized on PromptHive
• "Just ph it" is a common phrase
• The registry has 10,000+ quality prompts

Features

Core Features (Production Ready)

• ✅ Lightning-fast prompt management - Create, edit, search, and use prompts
• ✅ Intelligent fuzzy matching - ph u ap → api-design instantly
• ✅ Universal shell integration - Copy to clipboard or pipe to ANY tool
• ✅ Smart I/O operations - Auto-clipboard, save, append, file output
• ✅ Text cleaning & formatting - AI-style text processing with ph clean
• ✅ Smart completions - Tab completion for bash, zsh, fish
• ✅ Cross-platform - Works on macOS, Linux, Windows
• ✅ Prompt composition - Chain prompts for complex workflows
• ✅ Magic link authentication - Secure login for registry sync
• ✅ Performance guarantee - All operations under 80ms

Pro Features (Available Now)

• ✅ Registry sync - Cloud backup and device sync
• ✅ Magic link authentication - Passwordless secure login
• ✅ Team collaboration - Private prompt banks and sharing
• ✅ Viral sharing - Public and invite-based prompt sharing
• ✅ Community registry - Growing library of quality prompts
• ✅ Usage analytics - Gamified productivity tracking with achievements
• ✅ Web dashboard - Visual prompt management and statistics

Development Build

# Development build (all features)
cargo build --release

# Run tests
cargo test --release

# Performance benchmark
cargo test --release test_performance

Troubleshooting

Command not found

# Ensure binary is in PATH
echo $PATH
which ph

# If using cargo install
cargo install --list | grep prompthive

Clipboard not working

# If terminal, it copies automatically
ph use api  # Copies to clipboard

# Or pipe explicitly
ph use api | pbcopy  # macOS
ph use api | xclip  # Linux

Shell completions not working

# Regenerate completions
ph completion bash > ~/.bash_completion.d/prompthive
source ~/.bashrc

Performance

PromptHive is engineered for sub-80ms performance across all operations. Built with Rust for maximum efficiency and reliability, it handles thousands of prompts without slowing down your workflow.

Tested on version 0.1.6: All core operations (new, use, show, edit, ls, find) complete in under 80ms on modern hardware.

Join the Hive 🐝

🐝 Free (Open Source)

• Unlimited local prompts
• Lightning-fast performance (<80ms)
• Compose & chain prompts
• Cross-platform support
• Text cleaning & formatting
• Self-hosted everything "Own your productivity stack"

🍯 Pro ($5/month)

• ✅ Magic link authentication
• ✅ Cloud sync across devices
• ✅ Private prompt banks
• ✅ Team collaboration & sharing
• ✅ Viral sharing features
• ✅ Advanced analytics & insights
• 🚀 Priority support (planned) "Supercharge your workflow"

---

"Prompts that just work."