SEER - Shell Enhanced Execution & Reasoning

LLM-powered assistant for your terminal. Get contextual help from your local or cloud LLM based on what just happened in your shell — errors, failed commands, unexpected output.

Inspired by PEEL for PowerShell.

Supported platforms: macOS, Linux
Supported shells: zsh, bash

$ git pull-request
git: 'pull-request' is not a git command. See 'git --help'.

$ seer help
The command `git pull-request` is not valid. Use `git pull` to fetch and
merge, or install the `gh` CLI and run `gh pr create` to open a pull request.

How it works

Shell hooks (PROMPT_COMMAND / precmd) save your terminal's scrollback after every command. When you run seer help, the saved context is sent to your LLM of choice. No copy-pasting, no switching windows.

With tmux, the full screen output (including stderr) is captured. Without tmux, the last command and exit code are saved as fallback.

Installation

Method 1: Installer (Recommended)

Run directly from GitHub — installs seer, sets up shell integration and implicit mode:

curl -fsSL https://raw.githubusercontent.com/zeddius1983/seer/main/install.sh | bash

uv is installed automatically if not already present. To install a specific version or branch:

# By version tag
curl -fsSL https://raw.githubusercontent.com/zeddius1983/seer/main/install.sh | bash -s -- --version v1.1.0

# By branch
curl -fsSL https://raw.githubusercontent.com/zeddius1983/seer/main/install.sh | bash -s -- --version feature/v1.1.0

--version accepts any git ref (tag, branch, or SHA). It can be combined with other flags:

curl -fsSL https://raw.githubusercontent.com/zeddius1983/seer/main/install.sh | bash -s -- --version v1.1.0 --all

Note: Whenever ~/.zshrc is modified, a backup is created first as ~/.zshrc.YYYYMMDD_HHMMSS.bak.

Method 2: Build from source

git clone https://github.com/zeddius1983/seer
cd seer
uv tool install .

Uninstallation

If you installed via the installer (Method 1):

curl -fsSL https://raw.githubusercontent.com/zeddius1983/seer/main/install.sh | bash -s -- --uninstall

Usage

Implicit Mode (Ctrl+G)

Implicit mode is installed automatically with seer. Type any question directly into your terminal and press Ctrl+G:

find the largest file in this folder[Press Ctrl+G]
# Instantly expands and runs: seer find the largest file in this folder

To use a different key, set SEER_IMPLICIT_BIND (zsh bindkey notation) when installing:

curl -fsSL https://raw.githubusercontent.com/zeddius1983/seer/main/install.sh | SEER_IMPLICIT_BIND='^@' bash   # Ctrl+Space

Before v1.1.0 the default was Ctrl+Space, which clashes with global hotkeys in some apps (e.g. OpenClaw) and macOS input-source switching. Re-run the installer to switch.

Standard Commands

# Explain what just went wrong
seer help

# Ask anything shell-related
seer how to list all datasets in a ZFS pool
seer what does SIGKILL mean
seer how do I find which process is using port 8080

# Let seer do it — generates a command, shows it, asks before running
seer do find the largest file in ~/Downloads
seer do show disk usage by folder in /var
seer do list all listening ports

# Tip: quote the task if it contains apostrophes or special characters
seer do "show all files modified in the last week"
seer do "find the largest file and show it's size in MB"

# Pipe output directly (no shell hook needed)
kubectl get pods 2>&1 | seer
journalctl -xe | seer why is nginx failing

# Skip context, ask a clean question
seer --no-context explain the difference between hard and soft links

# Raw output — no glow or rich rendering
seer --raw how do I list open ports
seer -r help

# Use a specific provider or model for one query
seer -p anthropic help
seer -p openai -m gpt-4o how do I list listening ports

# Use your installed Claude Code / Codex CLI (your own subscription)
seer -p claude-cli help
seer -p claude-cli -m haiku help

Subcommands

Flags

Configuration

Generate the default config file:

seer config

This creates ~/.config/seer/config.yaml:

provider: lmstudio        # active provider

providers:
  lmstudio:               # LM Studio (or any OpenAI-compatible local server)
    type: openai
    base_url: http://localhost:1234/v1
    api_key: lmstudio
    model: google/gemma-3-4b

  ollama:
    type: openai
    base_url: http://localhost:11434/v1
    api_key: ollama
    model: llama3.2

  openai:
    type: openai
    model: gpt-4o
    api_key: sk-...       # or set OPENAI_API_KEY env var

  anthropic:
    type: anthropic
    model: claude-sonnet-4-6
    api_key: sk-ant-...   # or set ANTHROPIC_API_KEY env var

  # Any OpenAI-compatible endpoint (vLLM, llama.cpp, etc.)
  custom:
    type: openai
    base_url: http://myserver:8080/v1
    api_key: none
    model: my-model

Supported providers

Subscription CLIs (Claude Code, Codex)

If you have Claude Code or Codex installed and signed in, seer can use them instead of an API key. This is off by default and only happens if you choose it:

# Use one explicitly…
provider: claude-cli

# …or let `provider: auto` fall back to them when no local server is running.
# Local servers are always tried first.
auto_cli: true                        # tries claude-cli, then codex-cli
# auto_cli: [codex-cli, claude-cli]   # or set your own order / subset

providers:
  claude-cli:
    type: claude-cli
    model: sonnet             # haiku / sonnet / opus alias or a full model id
  codex-cli:
    type: codex-cli
    # Tried in order: if a model isn't available on your plan, seer falls back
    # to the next one. auto = the model from ~/.codex/config.toml
    model: [gpt-6-luna, auto]
    reasoning_effort: low     # passed as -c model_reasoning_effort=...
    # command: /path/to/codex # optional, if the binary isn't on PATH

How it works:

• seer runs the official, unmodified claude -p / codex exec binary. The CLI signs in with your own account; seer never reads, stores, or forwards your credentials.
• Tools are disabled (claude --tools "", codex --sandbox read-only) and sessions aren't saved, so the CLI only answers. It never runs commands or edits files.
• Your terminal context is sent to Anthropic / OpenAI, and the requests count against your plan's usage limits. seer --stats shows (your subscription) when one of these providers is active.
• claude-cli streams tokens and starts in a few seconds. codex-cli returns the whole answer at once and is slower (~10s), because Codex adds its own agent prompt.

Using your subscription this way is subject to Anthropic's and OpenAI's terms. If you want no ambiguity, use the anthropic / openai providers with an API key.

Development

git clone https://github.com/zeddius1983/seer
cd seer

# Install dev environment
uv sync

# Run directly without installing
.venv/bin/seer --help

# Build a wheel
uv build
# → dist/seer-1.0.0-py3-none-any.whl