Skip to content

README.md

Latest commit

 

History

History
170 lines (117 loc) · 4.61 KB

README.md

File metadata and controls

170 lines (117 loc) · 4.61 KB
Psh Icon

psh - Programmable Snippet Helper

Text expansion tool with directive-based syntax for dynamic snippet expansion

(aka prompt shell)

What is psh

psh helps you reuse frequently-used prompts for LLMs without repetitive typing. Instead of manually typing instructions like "summarize this as bullet points, be concise, no emoji" every time, you can type ;;sum.blt,l2,ne and let psh expand it into the full prompt.

Why? Tired of Claude using emoji all the time? ;;ne. Claude forgot your preference as well as earlier instructions about not creating new docs? ;;nd after every message. Need to remind it to be concise for the third time in the same conversation? ;;l2. psh makes these common corrections quick and effortless through short, memorable directives.

How? Type a directive like ;;d.ne,l3 anywhere, press Cmd+Shift+;, and psh replaces it with the expanded prompt. Perfect for chat interfaces, text editors, or any text field where you interact with LLMs.

Quick Start

Build and Run

# Build Rust libraries
cd psh-macos
./build-rust.sh

# Build and run macOS app
swift build
swift run

Setup

  1. Grant accessibility permissions: System Settings → Privacy & Security → Accessibility → Enable PshMacOS
  2. Copy snippets: mkdir -p ~/.config/psh && cp snippets.toml ~/.config/psh/
  3. Restart the app

Usage

Normal Mode:

  1. Focus any text field
  2. Type a directive: ;;d.ne
  3. Press Cmd+Shift+;
  4. Review preview, press Enter to apply

Quick Mode (Auto-Apply):

  1. Enable "Don't ask again" in overlay or settings
  2. Type directive and press Cmd+Shift+;
  3. Text is replaced immediately

Browse Snippets:

  1. Focus empty text field (or any field)
  2. Press Cmd+Shift+;
  3. Browse available snippets and settings

Directive Syntax

;;namespace.operation,operation2,key=value

Format:

  • Use dot notation for namespace: namespace.op
  • Use comma to separate multiple operations: op1,op2,op3
  • Use equals for key-value pairs: key=value

Examples:

  • ;;d.ne → Documentation style prompt, no emoji
  • ;;d.ne,l1 → Minimal documentation (README only), no emoji
  • ;;sum.blt → Summarize as bullet points
  • ;;plan.stp → Step-by-step plan
  • ;;cr.l4 → Comprehensive code review
  • ;;git.cm → Generate git commit message
  • ;;ne,l5 → Global ops only (no namespace)

Architecture

Rust Core (psh-core) → FFI Bridge (psh-ffi) → macOS App (Swift/SwiftUI)

Core Components:

  • psh-core: Directive parser, snippet resolver, template expander
  • psh-ffi: C FFI bindings with memory-safe wrappers
  • psh-macos: Menu bar app with global hotkey and accessibility integration

Customizing Snippets

Edit ~/.config/psh/snippets.toml:

[[snippet]]
id = "greeting"
namespace = "g"
template = "Hello {{ name }}!"

[snippet.ops.base]
name = "World"

[snippet.ops.custom]
name = "Custom"

Usage: ;;g.base → Hello World!, ;;g.custom → Hello Custom!

Troubleshooting

"Accessibility permissions required": Grant in System Settings, restart app

"No psh directives found": Ensure ;; prefix and valid namespace

"Snippets file not found": Copy to ~/.config/psh/snippets.toml

Hotkey not working: Check for conflicts with other apps

Development

Build Rust Library

cd psh-ffi
cargo build --release

Run Tests

cargo test --workspace
cargo test --workspace -- --nocapture test_comprehensive_examples
cargo clippy --workspace -- -D warnings

Build macOS App

cd psh-macos
swift build -c release

Documentation

Features

  • Directive parsing and expansion
  • Global hotkey (Cmd+Shift+;)
  • Preview overlay with diff view
  • Snippet browser with search
  • Auto-apply mode (skip confirmation)
  • User preferences persistence
  • Config window (shown when no text present)
  • Warning display for unknown directives
  • Hotkey customization UI
  • Usage statistics tracking

Status

Phase 1 (Rust Core): Complete - 35 tests passing, 0 warnings Phase 2 (macOS App): Complete - Enhanced UI with auto-apply mode Ready for testing and feedback

See DevLog-001 for detailed implementation status.
⚡