Skip to content
alexcamloPublic

About

Pi-powered zsh shell assistant for macOS. Generate, review, revise, explain, copy, and safely execute shell commands from natural language.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

shask

shask icon

Ask your shell. Powered by Pi.

Pi-powered zsh command assistant for macOS and Linux. Generate, review, revise, explain, copy, and safely execute shell commands from natural language.

shask recreates the command-generation workflow from sigoden/aichat, but uses pi as the LLM backend.

Features

  • Natural language → valid zsh command
  • Detects the host OS and generates platform-appropriate commands
  • Confirmation before execution
  • Revise generated commands without starting over
  • Explain generated or existing shell commands
  • Copy commands with pbcopy, wl-copy, xclip, or xsel
  • Add successfully executed generated commands to zsh history
  • Optional Alt+E shortcut to the same confirmation menu
  • Static progress message while shask or Alt+E waits for Pi
  • Uses pi --system-prompt so command-generation instructions are sent as a real system prompt

Requirements

  • macOS or Linux
  • zsh
  • pi available on PATH
  • Optional clipboard command: pbcopy, wl-copy, xclip, or xsel

Install

One command:

curl -fsSL https://raw.githubusercontent.com/alexcamlo/shask/main/install.sh | zsh

Restart zsh, or source the integration immediately:

source "$HOME/.local/share/shask/shask.zsh"

Ask for a command:

shask find all pdfs bigger than 10mb under Downloads

shask will generate a command, then ask what to do:

execute | revise | describe | copy | quit:

The first letter of each action is highlighted. Press:

  • e execute
  • r revise
  • d describe
  • c copy
  • q quit

The installer:

  • installs files to $HOME/.local/share/shask
  • creates $HOME/.local/bin/shask
  • adds a managed source block to ${ZDOTDIR:-$HOME}/.zshrc

Uninstall, also one command:

curl -fsSL https://raw.githubusercontent.com/alexcamlo/shask/main/install.sh | zsh -s -- --uninstall

Usage

Confirmed execution

shask tell me how many items are in ~/Downloads folder

Example output:

find "$HOME/Downloads" -mindepth 1 -maxdepth 1 ! -name '.*' | wc -l

Then choose execute, revise, describe, copy, or quit.

Generate only

shask --print show listening tcp ports

Explain a command

shask --describe 'find . -name "*.log" -mtime +7 -print'

Alt+E confirmation menu

When shask.zsh is sourced in an interactive zsh session, Alt+E is bound automatically.

  1. Type a natural-language request at your shell prompt.
  2. Press Alt+E.
  3. The same shask confirmation menu opens with your typed request.
  4. Choose execute, revise, describe, copy, or quit.

Commands run only when you choose execute, just like calling shask directly.

Configuration

Set the model persistently through shask; no ~/.zshrc environment variable is needed:

shask --model openai/gpt-4o-mini
shask --model anthropic/claude-sonnet-4-5
shask --model google/gemini-2.5-pro

shask --model prints the active model. The setting is stored in ${XDG_CONFIG_HOME:-$HOME/.config}/shask/config, so it works both from the standalone shask executable and the sourced zsh integration.

To see models available through your Pi login:

pi --list-models

Optional environment overrides for shell behavior can still be set before sourcing shask.zsh:

export SHASK_CONTEXT=basic   # none | basic | git
export SHASK_BINDKEY=1       # 0 disables Alt+E binding
export SHASK_KEY=$'\ee'      # Alt+E

SHASK_MODEL is a fallback when no saved model is configured. SHASK_CONFIG can redirect the config-file path, which is useful for isolated environments or tests.

Context

Context modes:

  • none: no cwd/git context
  • basic: OS, zsh version, and current directory
  • git: basic plus git root, branch, and short status

No file contents are sent to pi by default.

Backend

Default generation call shape:

pi \
  --model "$SHASK_MODEL" \
  --system-prompt '<command-generation prompt>' \
  --no-tools \
  -p \
  --no-session \
  '<natural language request>'

The system prompt starts from AIChat's %shell% role, includes the detected OS, and adds zsh-specific safety rules and Finder-like counting behavior.

Executable wrapper

bin/shask is included for convenience:

export PATH="$PWD/bin:$PATH"
shask --print list files

For full shell behavior, prefer sourcing shask.zsh. The wrapper runs in a child shell, so generated commands like cd, export, or alias cannot affect your current terminal session.

Safety notes

  • Commands are not executed without explicit confirmation.
  • Alt+E opens the same confirmation menu; it does not bypass confirmation.
  • Destructive commands are discouraged in the prompt; review everything before executing.
  • Successful generated commands are recorded in zsh history after execution.

Development

Run smoke checks:

zsh -n shask.zsh bin/shask install.sh tests/smoke.zsh tests/fixtures/bin/pi
zsh tests/smoke.zsh

About

Pi-powered zsh shell assistant for macOS. Generate, review, revise, explain, copy, and safely execute shell commands from natural language.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages