GitHub - litlig/heywtf: smart terminal buddy: hey to ask, hey wtf to fix · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
litlig
heywtf
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>8 Commits<br>8 Commits
heywtf
heywtf
shell
shell
.gitignore
.gitignore
LICENSE
LICENSE
README.md
README.md
config.example.json
config.example.json
pyproject.toml
pyproject.toml
View all files
Repository files navigation
heywtf
AI-powered terminal assistant for macOS. Ask how to do things in the terminal, or diagnose the last failed command.
Platform: macOS with zsh. Linux works for hey queries, but hey wtf shell integration is zsh-only.
Backends: Ollama (local, no API key, default) · OpenAI · Gemini (both need an API key).
Install
uv tool install heywtf
Install uv first if needed (brew install uv). Then run the setup wizard:
hey config
It walks you through picking a backend, setting an API key, and adding shell integration to ~/.zshrc so hey wtf works.
Usage
Ask a question:
hey how to count words in a file<br>hey find all python files modified in the last 24 hours
Diagnose a failed command — just run hey wtf after it fails:
$ chmod 777 /etc/hosts<br>chmod: changing permissions of '/etc/hosts': Operation not permitted
$ hey wtf
heywtf • powered by ollama (qwen2.5-coder:0.5b)<br>❌ Command failed: chmod 777 /etc/hosts<br>──────────────────────────────────────────────────
Permission denied — use sudo for system files:<br>sudo chmod 777 /etc/hosts
This needs shell integration (set up via hey config). Pause/resume capture with buddy-off / buddy-on — e.g. before an interactive session.
Override the backend for one query:
hey o explain async/await in Python # OpenAI<br>hey g difference between TCP and UDP # Gemini
Configure
hey config show # view current config<br>hey config set backend openai # default backend<br>hey config set openai_api_key sk-... # API key<br>hey config set ollama_model qwen3-coder:3b
API keys can also come from OPENAI_API_KEY / GOOGLE_API_KEY. For the default Ollama backend:
brew install ollama && ollama serve<br>ollama pull qwen2.5-coder:0.5b
How hey wtf works
A zsh preexec hook captures each command and its stderr; a precmd hook saves the command and error if the exit code is non-zero. hey wtf then reads that context and asks the AI to diagnose it. Interactive commands (vim, ssh, top, etc.) are skipped.
Development
git clone https://github.com/litlig/heywtf.git && cd heywtf<br>python3 -m venv .venv && source .venv/bin/activate<br>pip install -e .<br>source heywtf/shell/buddy.zsh # load shell hooks in the current session
License
MIT
About
smart terminal buddy: hey to ask, hey wtf to fix
Topics
macos
terminal
ai-assistant
localllm
ollama
Resources
Readme
License
MIT license
Uh oh!
There was an error while loading. Please reload this page.
Activity
Stars
stars
Watchers
watching
Forks
forks
Report repository
Releases
No releases published
Packages
Uh oh!
There was an error while loading. Please reload this page.
Contributors
Uh oh!
There was an error while loading. Please reload this page.
Languages
Python<br>83.2%
Shell<br>16.8%
You can’t perform that action at this time.