PALRUN

Project-aware command palette for your terminal with AI-powered intelligence.

Why Palrun?

Stop memorizing commands. Palrun automatically discovers every command available in your project and presents them in a blazing-fast fuzzy-searchable interface. Whether you're working with npm, cargo, make, docker, or any of 9+ supported project types, Palrun knows what you can run.

┌─────────────────────────────────────────────────────────────────────────────┐
│                              PALRUN v0.1.0                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   Project Scan ──► Command Discovery ──► Fuzzy Search ──► Execute          │
│                    (9+ types)             (nucleo)         (context-aware)  │
│                                                                             │
│   Cargo.toml   ──► cargo build, test    ──► "bui"     ──► cargo build      │
│   package.json ──► npm run dev, test    ──► "dev"     ──► npm run dev      │
│   Makefile     ──► make all, clean      ──► "cle"     ──► make clean       │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Features

Core Capabilities

• Project-Aware Discovery: Automatically detects commands from 9+ project types
• Fuzzy Search: Lightning-fast fuzzy matching powered by nucleo engine
• Context-Aware Sorting: Commands sorted by proximity to your current directory
• Cross-Platform: Works on macOS, Linux, and Windows
• Shell Integration: Keyboard shortcuts for instant access
• TUI Interface: Beautiful terminal UI with keyboard navigation
• Plugin System: Extensible architecture for custom scanners

Supported Project Types

Installation

Using Cargo

cargo install palrun

From Source

git clone https://github.com/GLINCKER/palrun.git
cd palrun
cargo install --path .

Homebrew (macOS/Linux)

brew tap GLINCKER/tap
brew install palrun

NPM (Node.js users)

npm install -g @glinr/palrun

Quick Install Script

curl -fsSL https://raw.githubusercontent.com/GLINCKER/palrun/main/scripts/install.sh | bash

Quick Start

1. Set Up Your Project

Initialize Palrun in your project with intelligent detection:

palrun setup

This will:

• Detect your project type (Node.js, Rust, Python, etc.)
• Create .palrun.toml with recommended settings
• Generate .palrun/runbooks/ with sample workflows
• Suggest relevant configurations

Options:

palrun setup --dry-run          # Preview what would be created
palrun setup --force            # Overwrite existing files
palrun setup --non-interactive  # Use defaults without prompts

2. Interactive Mode

Launch the command palette:

palrun

Use arrow keys to navigate, type to search, and press Enter to execute.

List Commands

Show all discovered commands:

palrun list

Output as JSON:

palrun list --format json

Filter by source type:

palrun list --source cargo
palrun list --source npm

Scan Project

Preview what commands would be discovered:

palrun scan
palrun scan --recursive

Execute Directly

Run a command by name:

palrun exec build
palrun exec "npm test"

Skip confirmation:

palrun exec build -y

Shell Integration

Add to your shell configuration for keyboard shortcuts:

Bash

eval "$(palrun init bash)"

Zsh

eval "$(palrun init zsh)"

Fish

palrun init fish | source

PowerShell

palrun init powershell | Invoke-Expression

Keyboard Shortcuts

Configuration

Configuration file location: ~/.config/palrun/config.toml

# Theme settings
[theme]
highlight_color = "cyan"

# Shell settings
[shell]
default = "bash"

# Scanner settings
[scanner]
exclude_patterns = ["node_modules", "target", ".git"]

Show config path:

palrun config --path

Shell Completions

Generate shell completions:

# Bash
palrun completions bash > /etc/bash_completion.d/palrun

# Zsh
palrun completions zsh > ~/.zfunc/_palrun

# Fish
palrun completions fish > ~/.config/fish/completions/palrun.fish

Plugin System

Palrun supports custom scanners through a plugin architecture. Example plugins are included:

• cargo-scanner: Enhanced Cargo.toml scanning
• composer-scanner: PHP Composer support
• gradle-scanner: Gradle build tool support
• maven-scanner: Maven build tool support
• poetry-scanner: Python Poetry support

See examples/plugins/ for implementation details.

Development

Building

cargo build
cargo build --release

Testing

cargo test
cargo test --all-features

Running

cargo run
cargo run -- list
cargo run -- scan

Features Status

Completed

• AI-powered command suggestions (Claude, OpenAI, Ollama)
• Runbook system for team workflows
• Command history and analytics
• Git integration (branch switching, status)
• Environment management (nvm, pyenv, etc.)
• Plugin system with SDK
• MCP (Model Context Protocol) integration
• Advanced search and filtering
• Theme support (multiple built-in themes)

Coming Soon

• Cloud sync and team collaboration
• VS Code extension
• Signed binaries for macOS/Windows
• More IDE integrations

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

• Bug reports and fixes
• New project type scanners
• Performance improvements
• Documentation updates

License

MIT License - free for personal and commercial use.

See LICENSE for details.

Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Built by GLINCKER