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 gitModern 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 |
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.
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.
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- Cancele- Edit in command linec- Copy to clipboard
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 |
| OpenRouter | Cloud | Fast | Pay-per-use | API key |
| Copilot | Cloud | Fast | Subscription | gh auth |
| Codex | Cloud | Fast | Paid | OAuth |
| Gemini | Cloud | Fast | Free tier | API key |
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 worksOne-liner (recommended):
curl -fsSL https://raw.githubusercontent.com/jasonkneen/askshell/main/install-remote.sh | bashHomebrew:
brew tap jasonkneen/askshell
brew install askshellnpm:
npm install -g askshellManual:
git clone https://github.com/jasonkneen/askshell ~/.askshell
echo 'source ~/.askshell/askshell.zsh' >> ~/.zshrc
source ~/.zshrc# 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# 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>
?openrouter <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 versionConfig 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
# OpenRouter model (access to multiple providers)
ASKSHELL_OPENROUTER_MODEL=anthropic/claude-haiku-4.5brew install ollama
ollama serve
ollama pull codestral # Recommended for code
# or
ollama pull llama3.2 # General purposeAdd to ~/.env:
ANTHROPIC_API_KEY=sk-ant-...OpenRouter provides access to multiple AI models through a single API, including Claude, OpenAI, Llama, and more.
- Get API key from openrouter.ai
- Add to
~/.env:
OPENROUTER_API_KEY=sk-or-v1-...- (Optional) Choose a model in
~/.config/askshell/config:
# Popular options:
ASKSHELL_OPENROUTER_MODEL=anthropic/claude-haiku-4.5
ASKSHELL_OPENROUTER_MODEL=openai/gpt-4o
ASKSHELL_OPENROUTER_MODEL=meta-llama/llama-3.1-70b-instructSee available models for the full list.
gh auth login
gh extension install github/gh-copilotnpm install -g @openai/codex
codex # Login via browserOr add API key to ~/.env:
OPENAI_API_KEY=sk-...Add to ~/.env:
GEMINI_API_KEY=...askshell prioritizes safety with multiple layers of protection:
- Placeholder Detection - Commands with
<variables>go to edit buffer - Question Mode - "How do I..." queries show answers without executing
- Dangerous Command Guard -
--force,rm -rf,sudo rmrequire explicit confirmation - Retry Logic - Unreliable AI responses are retried automatically
- Command Extraction - Filters out markdown, backticks, and explanations
# 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- zsh (default shell on macOS)
- curl (for API calls)
- python3 (for JSON parsing)
- One AI backend configured
# Run test suite
./test.sh
# Docker sandbox test
docker build -t askshell-test .
docker run --rm askshell-test"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
eto edit before running - Switch backends:
?claude <query>
Issues and PRs welcome at github.com/jasonkneen/askshell
MIT License - see LICENSE file