zshguy

A zsh widget that generates commands from natural language using LM Studio, Ollama, or an OpenAI-compatible API.

Type what you want to do in plain English, and zshguy asks the model for a zsh command or an insertion at the cursor position.

Requirements

• zsh
• One model backend:
  • lms from LM Studio
  • ollama from Ollama
  • An OpenAI-compatible Chat Completions server, with curl and jq installed

curl and jq are required only for the openai backend. LM Studio and Ollama CLI users do not need these additional dependencies.

Preflight

For LM Studio, complete its first-run setup and run:

# Check LMS CLI availability
lms --help

# Confirm LM Studio is running and the model is reachable
lms chat -p "ping"

If you set ZSHGUY_MODEL, run lms chat "$ZSHGUY_MODEL" -p "ping" instead.

For Ollama, start the server and run:

# Check Ollama CLI and server availability
ollama --version

# Confirm installed model names
ollama list

# Verify generation
ollama run qwen3:4b "ping"

LM Studio model setup (example: qwen/qwen3.5-9b)

qwen/qwen3.5-9b is an example model name. Replace it with the model key you want to use.

When preparing a new environment, run once:

# Download model
lms get qwen/qwen3.5-9b

# Confirm local model key
lms ls

# Load model to memory
lms load qwen/qwen3.5-9b

# Verify generation
lms chat qwen/qwen3.5-9b -p "ping"

If you omit the model/key argument for lms get or lms load, LM Studio opens an interactive selector.

Ollama model setup (example: qwen3:4b)

# Download model
ollama pull qwen3:4b

# Confirm local model name
ollama list

# Verify generation
ollama run qwen3:4b "ping"

Installation

sheldon

Add zshguy to your plugins.toml and let sheldon load the canonical plugin entrypoint:

[plugins.zshguy]
github = "hokupod/zshguy"

Other plugin managers

Use zshguy.plugin.zsh as the canonical plugin entrypoint:

source /path/to/zshguy.plugin.zsh

zshguy.sh remains available as a compatibility path for manual sourcing and older setups.

Manual source

If you do not use a plugin manager, source the compatibility wrapper from your .zshrc:

source /path/to/zshguy.sh

Key Binding

zshguy does not bind a key automatically. Add a manual bindkey mapping:

bindkey '^X^J' zshguy-widget

Other examples:

bindkey '^X^J' zshguy-widget
bindkey '^X^G' zshguy-widget

Usage

Press your bound key, then enter a prompt at the [zshguy] prompt. The generated command is placed in the command buffer and is not executed automatically. Review it, then press Enter to execute it.

Empty buffer

If the command line is empty, zshguy generates a full zsh command.

Example prompt:

count the number of files in the current directory

Existing input

If you already have text on the command line, zshguy inserts text at the cursor position.

Example buffer:

git checkout 

Example prompt:

main

If the prompt is empty or generation fails, the current buffer stays unchanged.

Backend and Model

LM Studio is the default backend. Existing configurations continue to work without ZSHGUY_BACKEND:

export ZSHGUY_BACKEND=lms
export ZSHGUY_MODEL=llama-3.1-8b-instruct

For Ollama, set the backend and an installed model name:

export ZSHGUY_BACKEND=ollama
export ZSHGUY_MODEL=qwen3:4b

ZSHGUY_MODEL is optional for LM Studio because lms chat can use its default model. It is required for Ollama. The Ollama CLI connects to 127.0.0.1:11434 by default. To use another host or port, set OLLAMA_HOST:

export OLLAMA_HOST=127.0.0.1:12345

Ollama thinking output is hidden so only the generated command is passed to the widget.

OpenAI-compatible API

Install curl and jq with your system package manager, then verify availability:

curl --version
jq --version

Configure the API base URL and a model served by that endpoint:

export ZSHGUY_BACKEND=openai
export ZSHGUY_BASE_URL=http://localhost:1234/v1
export ZSHGUY_MODEL=your-model-name

# Set only if your server requires Bearer authentication:
export ZSHGUY_API_KEY=your-api-key

Variable	Meaning
ZSHGUY_BASE_URL	Required HTTP(S) API base URL, including any version prefix such as /v1. No default.
ZSHGUY_MODEL	Required model identifier accepted by your server.
ZSHGUY_API_KEY	Optional Bearer token. Leave unset or empty for servers without authentication.

zshguy appends /chat/completions to the base URL (a trailing slash is allowed). For example, the configuration above calls http://localhost:1234/v1/chat/completions. Use your provider's base URL for a hosted service. Only ZSHGUY_API_KEY is read; OPENAI_API_KEY is not used automatically.

The backend sends system and user messages with stream: false, using the Chat Completions API format, and reads choices[0].message.content only when choices[0].finish_reason is stop. The server must support this format; Responses-only endpoints are not supported. Your prompt, current directory, and command text around the cursor (in insertion mode) are sent to the configured server.

Connections time out after 10 seconds, with a 120-second limit for the entire request. HTTP errors, malformed responses, missing content, and responses marked as truncated or filtered leave the command buffer unchanged.

Debugging

To inspect model output rejected by validation, enable debug mode:

export ZSHGUY_DEBUG=1

When validation fails, zshguy prints the raw output and normalized output to stderr.

Testing

Run the unit tests and interactive ZLE integration tests (curl and jq must be installed):

zsh tests/run.zsh

The integration tests cover both startup loading and sourcing zshguy after other ZLE plugins have already initialized. OpenAI-compatible backend tests use simulated responses and do not require a running server or API key.

License

MIT

Author

hokupod

Originally based on bashguy by Yasuhiro Matsumoto (a.k.a. mattn).