bashhelp

What is it?

A local LLM-powered bash command suggestion utility. It can connect to a llama.cpp backend where you can chat with an LLM with your choice to help you find which commands to run.

명령어를 자연어로 설명하면 로컬 LLM (llama.cpp)이 실행할 명령어를 알려주는 알려주는 CLI 툴입니다.

$ bh see nvidia gpu usage

❯ nvidia-smi
The `nvidia-smi` command displays a summary of GPU utilization, memory usage, temperature, and power consumption.
# press Up-arrow to place it on your prompt, edit if needed, hit Enter yourself

(Note: llama.cpp is not provided with the app.)

Why I made it

Because the philosophy of Linux dictates everything can be done in your terminal, and opening a browser to ask a chatbot to give me a simple command wastes time and carpal muscle strength I could've instead invested in productivity.

Features

• If your prompt is ambiguous, the LLM may engage multi-turn chats with you until your query is resolved.

• Appends the AI-suggested command into your history, allowing you to press the up key to arm it directly for your submission.

• Context includes your recent bash history (the last 5 commands you ran) so suggestions fit what you're doing.

• Fully customizable configs and system prompt in TUI. It is, afterall, just an LLM frontend with a custom prompt.

• Never runs code by itself! This is not Claude Code.

• Made in under a day, for fun. Don't expect more features.

Usage

After .bashrc hook installation:

$ bh list all files in current directory human readable and sort in size descending order

❯ ls -lhS
The `ls -lhS` command lists files in long format (`-l`), with human-readable sizes (`-h`), and sorts them by size in descending order (`-S`).

Alternatively, without the hook:

$ bashhelp see nvidia gpu usage

bh is a bash function which wraps bashhelp, and additionally appends the provided command to history so you can press the UP arrow button then enter to quickly execute the command. Running bashhelp does not provide this behavior.

Because your history gets injected into the prompt, this also works:

$ nvidia-smii
Command 'nvidia-smii' not found, did you mean:
    (...)

$ bh why didnt my last command work
❯ nvidia-smi
The command `nvidia-smii` is not a standard Linux or NVIDIA utility. It is likely a typo for `nvidia-smi` (NVIDIA System Management Interface). If you intended to check your GPU status, you should use `nvidia-smi` instead.

Install

Requirements

• uv (recommended, alternatively pipx)

• A llama.cpp server somewhere (or any OpenAI-compatible /v1/chat/completions endpoint).

Installation Script

git clone https://github.com/blazenkits/bashhelp.git
cd bashhelp
./install.sh

This installs the package in the uv method (described below) and executes post-install .bashrc hook for the bh function and history feature.

Manual Installation

# with uv (recommended)
uv tool install git+https://github.com/blazenkits/bashhelp

# or with pipx
pipx install git+https://github.com/blazenkits/bashhelp

Then run the guided setup once:

bashhelp setup                # asks for your backend URL + the shell shortcut
source ~/.bashrc

setup does:

• Ask you for the backend URL
• Source the Add the bh shortcut and history feature
• If you are skeptical of bashhelp shell-install --print prints the steps and touches nothing.

You can also skip setup and configure things directly:

echo 'http://localhost:8080' > ~/.config/bashhelp/backend   # or: export BACKEND_URL=...
bashhelp shell-install

Setting up llama.cpp

llama-server \
  --model /path/to/your/model
  --jinja \                               
  -ngl 99 \                               # offload all layers to GPU (drop if CPU-only)
  --host 127.0.0.1 --port 8080            # matches bashhelp's default backend URL

Uninstall

Use the uninstaller:

./uninstall.sh

OR manually,

bashhelp shell-uninstall      # remove the ~/.bashrc line (--purge to also drop generated files)
uv tool uninstall bashhelp    # or: pipx uninstall bashhelp

Configuration

A TUI Config menu:

bh config      # arrow up/down to pick a setting, Enter to edit, q to quit

bh setup is the same TUI walked through as a first-run wizard.

What	Where	Override
Backend URL	~/.config/bashhelp/backend	$BACKEND_URL
History lines	~/.config/bashhelp/history_lines (default 5)	$BASHHELP_HISTORY_LINES (0 disables)
System prompt	~/.config/bashhelp/system_prompt (else packaged default)	edit via bh config
Generated init	~/.local/share/bashhelp/init.bash	$XDG_DATA_HOME
Runtime state	~/.cache/bashhelp/	$XDG_CACHE_HOME

Disclaimer

The tool does not check LLM output for correctness. You don't run random code from the internet. Your LLM was trained from the internet. Read before you run.

Testing

The software was tested on Ubuntu 24.04 LTS with llamacpp build b9664 and using models:

• unsloth/gemma-4-12b-it-Q4_K_M (RTX 5060Ti 16GB GPU); excellent prompt following, response time <5s
• unsloth/Qwen3.5-2B-GGUF:Q4_K_M (CPU); medium prompt following, response time <5s