zzstoatzz.io / zigman
zig langref cli nate.tngl.io/zigman
Star
Fork 0
Watch
zigman docs guide.md
3.8 kB
Markdown
at main

using zigman in practice #

zigman puts the Zig language reference one keystroke away — for when you're mid-edit and can't remember the exact form of a builtin, a switch prong, or a sentinel type, and don't want to lose your place to a browser. this is the practical playbook.

the one habit #

when you're unsure how a Zig language feature is spelled or behaves, look it up instead of guessing:

zigman casting

you don't need the exact section name. type the word you have in your head — zigman resolves it to the obvious section, and only asks you to choose when it's genuinely ambiguous.

zigman optional        # opens "Optionals"
zigman error union     # opens "Error Union Type"
zigman comptime        # opens "comptime"
zigman sentinel        # ambiguous -> lists Sentinel-Terminated Arrays / Pointers / Slices

when you don't know the word #

browse or filter the table of contents, then open one:

zigman -l              # every section, indented by depth
zigman -l error        # just the sections about errors
zigman labeled block   # multi-word: lists Blocks, Labeled-switch/while/for

the rule of thumb: zigman -l <word> to find the name, then zigman <name> to read it.

everyday workflows #

  • a compile error names a concept you're shaky on — read that section first. zig build complains about @intCast arity? zigman @intCast shows the current single-argument form.
  • you forget exact syntax mid-write — zigman for (loop captures + index), zigman switch (prongs, ranges, exhaustiveness), zigman slices (slicing semantics).
  • you're reviewing and want to be sure before asserting "Zig does X" — look it up rather than trusting memory; the reference is the source of truth.
  • you need an older release's behavior — pin the version:
    zigman -V 0.15.1 comptime
  • you'd rather see it in the browser (full page, links, search) — open the section there instead:
    zigman -o comptime

it composes #

output is plain markdown on stdout, so pipe it anywhere:

zigman comptime | glow -          # pretty-render
zigman switch | rg -i "inline"     # grep within a section
zigman -l | fzf                    # fuzzy-pick a section to read

on a terminal it pages through $PAGER (default less -FRX); piped, it stays raw.

using zigman from an AI agent #

zigman ships an agentskills.io skill at skills/zigman/SKILL.md. the behavior it installs is simple and high-value: read the reference instead of guessing Zig semantics. it works in any skills-aware harness (Claude Code, opencode, Pi, Cursor, …) — point the client at the skill directory and make sure the zigman binary is on PATH. the agent then runs zigman <topic> (via its shell tool) before writing tricky Zig, which measurably reduces version-stale guesses like the old @intCast(u8, x) form.

print the skill, or a shell completion, straight from the binary:

cat "$(dirname "$(command -v zigman)")"/../skills/zigman/SKILL.md   # if installed from source
zigman --completions zsh                                            # tab-complete section names

what zigman is not #

zigman covers the language, not the standard library. for std.ArrayList, std.Io, std.fmt, allocators, and the rest, read the std source directly — zig env reports .std_dir (a path relative to $HOME):

rg --type zig 'pub fn ' "$HOME/$(zig env | sed -n 's/.*\.std_dir = "\(.*\)",/\1/p')/array_list.zig"

install & source #

curl -fsSL https://nate.tngl.io/zigman/install.sh | sh, or build from source with zig build (zig 0.16+). source and issues: tangled.org/zzstoatzz.io/zigman.