hey, man!
hey, man, how do I find which process is listening on port 8080?
heyman: ask for a shell command in plain English. heyman lets the model read the man pages on your machine before it answers, so the flags match your system: BSD tools on macOS, GNU on Linux.
$ heyman lsof which process is listening on port 8080 lsof -i :8080 $ heyman stat print the size in bytes and modification time of notes.txt stat -f "%z %Sm" notes.txt $ heyman -- compress the logs directory into a tarball, excluding .tmp files tar --exclude='*.tmp' -czf logs.tar.gz logs
Name the program you have in mind (heyman tar …) and its man page is loaded up front. Or put -- before the request and the model searches the installed man pages itself. Either way it can call three tools while it works:
manreads any man page on this machine, in chunks or filtered by a search patternman_searchsearches man page names and descriptions, likeman -kwhichchecks whether a program is installed
Only the command goes to stdout, so $(heyman …) works. Add --explain for an explanation, -v to see which man pages it read.
Install
$ go install github.com/alecf/heyman/cmd/heyman@latest $ export ANTHROPIC_API_KEY=… $ heyman ls list files by size, largest first
That uses the default model, anthropic/claude-haiku-4-5. To use another provider, set its credentials and pass --model provider/model, or set HEYMAN_MODEL once:
| provider | setup | example |
|---|---|---|
anthropic | export ANTHROPIC_API_KEY=… (or CLAUDE_API_KEY) | heyman -m anthropic/claude-sonnet-5-5 … |
openai | export OPENAI_API_KEY=… | heyman -m openai/<model> … |
openrouter | export OPENROUTER_API_KEY=… | heyman -m openrouter/<org>/<model> … |
google | export GEMINI_API_KEY=… (or GOOGLE_API_KEY) | heyman -m google/<gemini model> … |
ollama | Run ollama serve and ollama pull <model>. Set OLLAMA_HOST if it isn’t on localhost:11434. | heyman -m ollama/qwen3:4b … |
openai-compat | export HEYMAN_OPENAI_COMPAT_BASE_URL=http://localhost:8080/v1 for llama.cpp, vLLM, LM Studio and the like. Add HEYMAN_OPENAI_COMPAT_API_KEY if the server needs a key. | heyman -m openai-compat/<model> … |
claude-code | Install the claude CLI and log in. No API key needed; expect 10s or more per request. | heyman -m claude-code/haiku … |
Local models need tool-calling support to read man pages; heyman falls back to a single prompt with the named man page if they don’t have it. More on models.
Set a default
Save models as named profiles and pick one as the default, so you don’t need --model on every run. heyman profile setup asks for a provider and model and saves a profile; the first one you create becomes the default.
$ heyman profile setup $ heyman profile list * haiku anthropic claude-haiku-4-5 local ollama qwen3:4b $ heyman profile set-default local Default profile set to: local Provider: ollama Model: qwen3:4b
Use another profile for one run with --profile haiku. heyman profile show and heyman profile delete do what they say. Profiles live in config.toml (~/Library/Application Support/heyman/ on macOS, ~/.config/heyman/ on Linux) if you’d rather edit them by hand; that’s also where a server’s base_url goes.
When several are set, the most specific wins: --model, then --profile, then the HEYMAN_MODEL and HEYMAN_PROFILE environment variables, then the default profile, then anthropic/claude-haiku-4-5.
Eval results
50 requests a developer might type, from lsof one-liners to multi-tool pipelines like “list the size of all files changed in git in the last week.” Eleven are cases where the correct flags differ between macOS and Linux (sed -i '', stat -f, date -v-1d), which is what reading local man pages is supposed to fix.
Each answer has to pass regex checks that accept equivalent spellings. Twenty-two cases are also run in a sandbox against a fixture and compared with the reference output. An LLM judge (Claude Sonnet 5.5) gives a second opinion, reported separately. Cases and runner.
Short version: for a tool you use interactively, answers need to be right and come back in well under 30 seconds. On this machine only the API models do both. The best local model, gemma4:12b, is nearly as accurate as Haiku but takes about 40 seconds per answer; the local models fast enough to use (qwen3.5:4b, gemma4:e4b, 10–15 seconds) get about half the answers right.
Test setup
Pass rate by model
Loading…
Time per answer
Seconds from request to command, including every man-page lookup.
Summary
Every case
Click a row for the commands each model produced, the first failing check and the judge’s verdict.