askshell

Natural language to shell commands with syntax highlighting, intelligent validation, and multi-backend AI support.

Perfect for minimal terminals like Ghostty that don't have built-in suggestions or syntax highlighting.

ask find files larger than 100mb
ask kill process on port 3000
ask how do I force push in git

Why askshell?

Modern terminals like Ghostty are fast and beautiful, but lack the autocomplete and suggestions you might be used to. askshell fills that gap:

| Feature | Traditional Terminal | With askshell | |---------|---------------------|---------------| | Command suggestions | None | AI-powered natural language | | Syntax highlighting | Limited/None | Placeholder highlighting | | Safety validation | None | Dangerous command detection | | Learning curve | Memorize flags | Just describe what you want |

Features

Syntax Highlighting for Placeholders

When AI returns a command with placeholders, they're highlighted in yellow so you can easily spot what needs editing:

→ git push origin <branch_name> --force
  ⚠ Command contains placeholders - edit before running

The command is placed in your edit buffer - just fill in the placeholder and press Enter.

Intelligent Command Validation

Question Detection - Asking "how do I..." won't execute anything:

ask how do I undo my last commit
→ git reset --soft HEAD~1
  ℹ Answer to your question (not executed)

Dangerous Command Protection - Force pushes, rm -rf, and other risky commands always require confirmation:

ask force push to origin
→ git push --force origin main
  ⚠ Dangerous command - confirm before running
  Run? [y/N]

Placeholder Detection - Commands with <branch_name>, [file], or your_path are never auto-executed.

Visual Feedback

Loading spinner while AI thinks:

  ⠹ Thinking...

Clean command output with execution options:

→ find . -type f -size +100M
Run? [Y/n/e/c]

• Y - Run immediately (default)
• n - Cancel
• e - Edit in command line
• c - Copy to clipboard

Multi-Backend AI Support

Choose your preferred AI backend - local or cloud:

| Backend | Privacy | Speed | Cost | Setup | |---------|---------|-------|------|-------| | Ollama | Local | Fast | Free | ollama serve | | Claude | Cloud | Fast | Paid | API key | | Copilot | Cloud | Fast | Subscription | gh auth | | Codex | Cloud | Fast | Paid | OAuth | | Gemini | Cloud | Fast | Free tier | API key |

Smart Command Recognition

Just start typing naturally - askshell intercepts common patterns:

show disk usage          # No "ask" prefix needed
find large files         # Automatically routed to AI
list docker containers   # Natural language works

Installation

One-liner (recommended):

curl -fsSL https://raw.githubusercontent.com/jasonkneen/askshell/main/install-remote.sh | bash

Homebrew:

brew tap jasonkneen/askshell
brew install askshell

npm:

npm install -g askshell

Manual:

git clone https://github.com/jasonkneen/askshell ~/.askshell
echo 'source ~/.askshell/askshell.zsh' >> ~/.zshrc
source ~/.zshrc

Quick Start

# Install Ollama for local AI (recommended)
brew install ollama
ollama serve &
ollama pull codestral

# Try it out
ask list files by size
ask show my ip address
ask compress this folder

Usage

# Natural language queries
ask <query>              # Uses default backend
ask! <query>             # Skip confirmation (headless)
? <query>                # Short alias
!! <query>               # Headless short alias

# Force specific backend
?ollama <query>
?claude <query>
?copilot <query>
?codex <query>
?gemini <query>

# Management
askshell                 # Show help
askshell status          # Check backend availability
askshell backend ollama  # Set default backend
askshell headless on     # Enable auto-execute
askshell headless off    # Require confirmation
askshell config          # Edit configuration
askshell version         # Show version

Configuration

Config file: ~/.config/askshell/config

# Default AI backend
ASKSHELL_BACKEND=ollama

# Auto-execute commands (true/false)
ASKSHELL_HEADLESS=true

# Ollama model for local inference
ASKSHELL_OLLAMA_MODEL=codestral:latest

# Gemini model
ASKSHELL_GEMINI_MODEL=gemini-2.0-flash

Backend Setup

Ollama (Local, Free, Private)

brew install ollama
ollama serve
ollama pull codestral        # Recommended for code
# or
ollama pull llama3.2         # General purpose

Claude (Anthropic)

Add to ~/.env:

ANTHROPIC_API_KEY=sk-ant-...

GitHub Copilot

gh auth login
gh extension install github/gh-copilot

OpenAI/Codex

npm install -g @openai/codex
codex  # Login via browser

Or add API key to ~/.env:

OPENAI_API_KEY=sk-...

Google Gemini

Add to ~/.env:

GEMINI_API_KEY=...

Safety Features

askshell prioritizes safety with multiple layers of protection:

1. Placeholder Detection - Commands with <variables> go to edit buffer
2. Question Mode - "How do I..." queries show answers without executing
3. Dangerous Command Guard - --force, rm -rf, sudo rm require explicit confirmation
4. Retry Logic - Unreliable AI responses are retried automatically
5. Command Extraction - Filters out markdown, backticks, and explanations

Examples

# File operations
ask find files larger than 100mb
ask delete node_modules recursively
ask show disk usage by folder

# Git operations
ask undo last commit
ask show changed files
ask how do I squash commits

# Process management
ask kill process on port 3000
ask show memory usage
ask find zombie processes

# Networking
ask show my ip address
ask test if google is reachable
ask list open ports

# Docker
ask list running containers
ask stop all containers
ask remove unused images

Requirements

• zsh (default shell on macOS)
• curl (for API calls)
• python3 (for JSON parsing)
• One AI backend configured

Testing

# Run test suite
./test.sh

# Docker sandbox test
docker build -t askshell-test .
docker run --rm askshell-test

Troubleshooting

"Error: ollama not running"

ollama serve  # Start Ollama server

"Error: Could not generate command"

• Check your backend is configured (askshell status)
• Ensure API keys are in ~/.env

Command has wrong syntax

• Use e to edit before running
• Switch backends: ?claude <query>

Contributing

Issues and PRs welcome at github.com/jasonkneen/askshell

License

MIT License - see LICENSE file