ai-prompt

Natural language to shell commands with ghost text preview.

Install

Requires curl, jq, and Bun (for building).

# Clone
git clone https://github.com/mattapperson/ai-prompt ~/.ai-prompt
cd ~/.ai-prompt

# Install dependencies and build
bun install
bun run build

# Add to .zshrc
echo 'source ~/.ai-prompt/ai-prompt.plugin.zsh' >> ~/.zshrc

# Set your API key
export OPENROUTER_API_KEY='sk-or-...'

# Or use macOS Keychain
security add-generic-password -s 'openrouter-api-key' -a "$USER" -w 'sk-or-...'

Usage

1. Type a natural language description: find all javascript files
2. Press Enter - ghost text appears with the suggested command
3. Press Enter again to accept and execute, or keep typing to dismiss

Commands (with flags, pipes, etc.) execute normally on Enter without AI intervention.

Configuration

Variable	Description	Default
AI_PROMPT_HIGHLIGHT	Ghost text style (zsh region_highlight)	fg=8
AI_PROMPT_SKIP_COMMANDS	Skip AI for command-like input	true
AI_PROMPT_OPENROUTER_MODEL	OpenRouter model	z-ai/glm-4.6:nitro
AI_PROMPT_DEBUG	Enable debug logging	false
AI_PROMPT_LOG	Debug log path	/tmp/ai-prompt.log

Provider

Uses OpenRouter for LLM inference. Get an API key at openrouter.ai/keys.

OpenRouter supports hundreds of models - set any model ID via AI_PROMPT_OPENROUTER_MODEL.

export AI_PROMPT_OPENROUTER_MODEL='anthropic/claude-3.5-sonnet'

Command Detection

The plugin distinguishes between natural language and actual shell commands. When input looks like a real command, it skips the AI call.

Skips AI (already a command):

• Has flags: git commit -m "fix", ls -la
• Has operators: ps aux | grep nginx, echo hello > file.txt

Calls AI (natural language):

• Question words: how do I list hidden files
• Descriptive phrases: find all javascript files modified today

Manual bypass: Prefix with $ to force skip AI. The prefix is stripped from the buffer.

$ find all files    # skips AI, buffer becomes "find all files"

Disable detection entirely with AI_PROMPT_SKIP_COMMANDS=false to always call AI.

Development

# Install dependencies
bun install

# Run tests
bun test

# Build binary
bun run build

# Run CLI directly (for testing)
bun run src/index.ts detect "find all files"
bun run src/index.ts suggest "find large files"

Architecture

The plugin is a hybrid TypeScript/zsh architecture:

• TypeScript CLI (src/) - Handles API calls, command detection heuristics, output sanitization
• Zsh wrapper (ai-prompt.plugin.zsh) - Wraps accept-line (Enter), ghost text rendering

Flow on Enter:

User presses Enter
    ↓
bin/ai-prompt detect "$BUFFER"
    ↓
{"type":"skip"}  →  Execute command normally
{"type":"detect"} →  bin/ai-prompt suggest → Show ghost text
    ↓
User presses Enter again → Accept and execute

Enable debug logging:

AI_PROMPT_DEBUG=true
tail -f /tmp/ai-prompt.log