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:

• man reads any man page on this machine, in chunks or filtered by a search pattern
• man_search searches man page names and descriptions, like man -k
• which checks 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:

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.

Summary

Every case

Click a row for the commands each model produced, the first failing check and the judge’s verdict.