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:

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:

providersetupexample
anthropicexport ANTHROPIC_API_KEY=… (or CLAUDE_API_KEY)heyman -m anthropic/claude-sonnet-5-5 …
openaiexport OPENAI_API_KEY=…heyman -m openai/<model> …
openrouterexport OPENROUTER_API_KEY=…heyman -m openrouter/<org>/<model> …
googleexport GEMINI_API_KEY=… (or GOOGLE_API_KEY)heyman -m google/<gemini model> …
ollamaRun ollama serve and ollama pull <model>. Set OLLAMA_HOST if it isn’t on localhost:11434.heyman -m ollama/qwen3:4b …
openai-compatexport 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-codeInstall 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.