Prompt Store

A Git-backed CLI tool for managing and sharing prompt templates with a dual-tier architecture for global repositories and local workspaces.

Overview

Prompt Store provides a distributed solution for organizing prompt templates (or "bits") using Git repositories as the storage backend. It features a global store for managing repositories and a local workspace system for prompt composition. Access your prompts anywhere with full version control, collaboration features, and offline availability.

Architecture

The tool uses a two-tier architecture:

• Global Store: Manages Git repositories and maintains a centralized cache of all available prompts
• Local Workspace: Project-specific workspace where you can add/remove prompts for composition work

Features

• Git-Backed Storage: Leverage Git for version control, collaboration, and distributed access
• Dual-Tier Architecture: Global repositories with local workspaces for organized prompt composition
• Interactive Selection: fzf-like interactive prompt selection with fuzzy search and multi-select
• Multi-Repository Support: Pull prompts from multiple Git sources (personal, team, project-specific)
• Local Workspace Management: Add/remove prompts to current working directory for composition
• Powerful Search: Find prompts by ID or content with fuzzy matching across global store
• Cross-Platform: Works on Windows, macOS, and Linux

Quick Start

Installation

npm install -g prompt-store

Setup

Initialize the global prompt store system:

# Initialize global store (creates config directory and structure)
prompt-store global init

# Add repositories to global store
prompt-store global add [email protected]:username/my-prompts.git
prompt-store global add https://github.com/company/team-prompts.git

# Synchronize all repositories
prompt-store global sync

Basic Usage

Global Store Management:

# List all available prompts across all repositories
prompt-store global list

# Search for specific prompts
prompt-store global list "react component"

# Synchronize all repositories
prompt-store global sync

Local Workspace:

# Initialize workspace in current directory
prompt-store local init

# Add prompts to current workspace (interactive selection)
prompt-store local add --interactive

# Add specific prompt to workspace
prompt-store local add my-templates/code-review.md

# List prompts in current workspace
prompt-store local list

# Remove prompts from workspace (interactive)
prompt-store local remove --interactive

Commands

The CLI uses a two-tier command structure: prompt-store [global|local] [operation]

Global Store Commands

prompt-store global init Initialize the global prompt store system. Creates configuration directory and structure.

prompt-store global add <repo_url> Add a Git repository to the global store.

Options:

• --type <type> - Repository type: "writable" (default) or "view-only"
• --branch <branch> - Git branch to use (default: "main")

Examples:

prompt-store global add [email protected]:username/my-prompts.git
prompt-store global add https://github.com/company/shared-prompts.git --type view-only

prompt-store global remove <repo_name> Remove a repository from the global store.

prompt-store global sync Synchronize all repositories with their remotes.

Options:

• --repository <name> - Sync specific repository only

prompt-store global list [query] List all available prompts across all repositories.

Options:

• --repository <name> - List prompts from specific repository only
• --format <format> - Output format: "table" (default), "json", "csv"

Local Workspace Commands

prompt-store local init Initialize a local workspace in the current directory.

prompt-store local add [prompt-bit-id] Add prompts to the local workspace.

Options:

• -i, --interactive - Interactive selection with fuzzy search and multi-select
• --copy - Copy file content instead of creating symlinks

Examples:

prompt-store local add --interactive           # Interactive selection
prompt-store local add repo/path/to/file.md   # Add specific prompt

prompt-store local remove [prompt-bit-id] Remove prompts from the local workspace.

Options:

• -i, --interactive - Interactive selection with status indicators

prompt-store local list [query] List prompts in the current workspace.

prompt-store local clean Remove broken symlinks from the local workspace.

prompt-store local sync Synchronize the local workspace with the global store (updates symlinks).

Interactive Features

The tool includes powerful interactive selection capabilities for a better user experience:

Interactive Add (--interactive)

• Fuzzy Search: Type to filter through available prompts instantly
• Preview Display: See the first line of each prompt file as you browse
• Multi-Select: Use Space to select multiple prompts, Enter to confirm
• Repository Grouping: Prompts organized by repository for easy navigation
• Status Filtering: Only shows prompts not already in your workspace
• Confirmation: Review selection before adding to prevent mistakes

Interactive Remove (--interactive)

• Workspace Overview: Browse all prompts currently in your workspace
• Status Indicators: See ✓ for valid symlinks, ✗ for broken ones
• Multi-Select: Remove multiple prompts efficiently with bulk operations
• Safety Confirmation: Confirm before removing multiple items
• Error Handling: Graceful error reporting for individual failures

Example Interactive Flows

Adding Prompts:

$ prompt-store local add --interactive
Loading available prompts...
Found 25 prompts available for selection.

? Select prompts to add to workspace: (Use arrow keys, type to filter, space to select)
❯ [my-templates] ◯ code-review.md - Code review checklist template
  [my-templates] ◯ bug-report.md - Structured bug report template  
  [shared-prompts] ◯ meeting-notes.md - Meeting notes template
  [shared-prompts] ◯ project-plan.md - Project planning template

Removing Prompts:

$ prompt-store local remove --interactive
Loading workspace prompts...
Found 8 prompts in workspace.

? Select prompts to remove from workspace:
❯ [my-templates] ◉ ✓ code-review.md - Code review checklist template
  [my-templates] ◯ ✗ old-template.md - Target file not found
  [shared-prompts] ◯ ✓ meeting-notes.md - Meeting notes template

Configuration

Configuration Structure

The global configuration is automatically managed at:

• Config File: ~/.config/prompt-store/.global-config.yaml
• Repositories: Cloned to ~/.config/prompt-store/repositories/
• Local Workspace: .prompt-store/ directory in current working directory

Global Configuration Format

The global config is managed via CLI commands, but follows this structure:

version: "2.0"
repositories:
  my-templates:
    url: "[email protected]:username/my-prompts.git"
    type: "writable"  # or "view-only"
    path: "/home/user/.config/prompt-store/repositories/my-templates"
    added_date: "2024-01-15T10:30:00Z"
    last_sync: "2024-01-15T15:45:30Z"
    branch: "main"

Local Workspace Configuration

Each local workspace has its own config at .prompt-store/config.yaml:

version: "2.0"
workspace:
  created_date: "2024-01-15T14:20:00Z"
  prompt_files: []  # Managed automatically

Repository Authentication

SSH (Recommended):

prompt-store global add [email protected]:username/prompts.git

HTTPS with Personal Access Token:

prompt-store global add https://[email protected]/username/prompts.git

Prompt Organization

Repository Structure

Organize your Git repositories with logical directory structures:

my-prompts/
├── coding/
│   ├── react/
│   │   ├── component.md
│   │   └── hook.md
│   └── sql/
│       └── query.txt
├── writing/
│   ├── email-templates/
│   └── documentation/
└── ai/
    ├── system-prompts/
    └── few-shot-examples/

Prompt IDs

Prompts are identified using the format: {repository}/{path}/{filename} (without extension)

Examples:

• my-templates/coding/react/component → my-templates/coding/react/component.md
• team-prompts/sql/complex-query → team-prompts/sql/complex-query.txt

Supported File Extensions

• .txt - Plain text
• .md - Markdown
• .prompt - Generic prompt files

Shell Integration

Add these aliases to your shell profile for faster access:

# .bashrc or .zshrc
alias ps="prompt-store"
alias psg="prompt-store global"
alias psl="prompt-store local"

# Common global operations
alias ps-sync="prompt-store global sync"
alias ps-list="prompt-store global list"

# Common local operations  
alias ps-add="prompt-store local add --interactive"
alias ps-rm="prompt-store local remove --interactive"
alias ps-ws="prompt-store local list"

Use Cases

Personal Prompt Library

Set up your personal repository and access prompts globally:

# Add your personal repo
prompt-store global add [email protected]:username/my-prompts.git

# Browse and search your prompts
prompt-store global list "code review"

# Create workspace and add specific prompts for a project
mkdir project && cd project
prompt-store local init
prompt-store local add --interactive  # Select from your prompts

Team Collaboration

Share standardized prompts across your development team:

# Add team repository (view-only for most team members)
prompt-store global add https://github.com/company/team-prompts.git --type view-only

# Set up project workspace with team templates
prompt-store local init
prompt-store local add team-prompts/templates/pr-description
prompt-store local add team-prompts/checklists/deployment

Project-Specific Workflows

Use local workspaces to organize prompts for specific projects:

# Each project gets its own workspace
cd my-awesome-project
prompt-store local init

# Add relevant prompts for this project
prompt-store local add --interactive

# Workspace contains only what you need for this project
prompt-store local list

Multi-Repository Setup

Manage multiple sources of prompts:

# Personal prompts (writable)
prompt-store global add [email protected]:username/personal-prompts.git

# Team prompts (view-only)  
prompt-store global add https://github.com/company/shared-prompts.git --type view-only

# Project-specific prompts (writable)
prompt-store global add [email protected]:username/project-x-prompts.git

# Browse all available prompts
prompt-store global list

# Sync all repositories
prompt-store global sync

Architecture

Prompt Store uses a dual-tier architecture with Git as the source of truth:

Global Store Layer

• Repository Management: Centralized management of multiple Git repositories
• Global Cache: Maintains local clones of all configured repositories at ~/.config/prompt-store/
• Synchronization: Handles Git operations (clone, pull, push) for all repositories
• Discovery: Provides search and browse capabilities across all available prompts

Local Workspace Layer

• Project Isolation: Each project directory can have its own prompt workspace
• Selective Addition: Choose specific prompts relevant to current project work
• Symlink Management: Creates symlinks to global store files for efficient storage
• Workspace Cleanup: Tools to maintain and clean up workspace integrity

Key Benefits

• Separation of Concerns: Global management vs. local project needs
• Efficient Storage: Symlinks prevent file duplication across workspaces
• Offline Capability: Full functionality after initial repository synchronization
• Multi-Source Support: Handle personal, team, and project-specific repositories
• Interactive UX: Modern CLI experience with fuzzy search and multi-select

Development

Building from Source

git clone https://github.com/username/prompt-store.git
cd prompt-store
npm install
npm run build
npm link  # For local development

Testing

npm test           # Run test suite
npm run lint       # Code linting
npm run typecheck  # TypeScript validation

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions