helpshell — the shell config you forgot you wrote

See it first

What a resolved entry looks like.

$ helpshell show node-modules-clean-old

  FUNCTION   node-modules-clean-old

  source     ~/.config/zsh/cleanup.zsh:42
  category   node_modules cleanup
  docstring  Remove node_modules not modified in $days days.

  local days=${1:-180}
  local count=0

  find . -type d -name node_modules -prune \
    -mtime +$days -exec rm -rf {} \; \
    -exec ((count++)) \;

  echo "Removed $count directories."

One command, the whole story. Every entry resolves to its source file and line, its #:: category, its docstring (when present), and its full definition — whether it came from your .zshrc, a sourced helper, or a plugin you forgot you installed.

Why

What `grep ~/.zshrc` misses.

Plugin-defined symbols

Aliases and functions added by oh-my-zsh, zinit, or any plugin — not in your dotfiles, but live in your shell. Hybrid extraction: parse and zsh -i -c.

Sourced chains

Files pulled in via source ~/.config/zsh/*.zsh or guarded loaders. Followed recursively with cycle detection — nothing slips through.

`#::` category markers

Annotate sections of your .zshrc with #:: Fleet cache cleanup and entries below group by that label in the detail pane.

Optional AI explainer

Config-gated claude -p integration. Ask "what does this do?" on any entry. Results cached by content hash — re-explains are instant.

Trust

Runs on your machine. Sends nothing by default.

100% local

Parsing, introspection, indexing, and the web UI all run on your laptop. No account, no telemetry, no phone-home.

SQLite on disk

Index lives at ~/.local/share/helpshell/index.sqlite. Delete it any time — helpshell rebuild restores it.

Localhost-only UI

helpshell web binds to 127.0.0.1 on a random OS-assigned port and idles out after 30 minutes.

AI explainer is opt-in

Disabled by default. When enabled it shells out to whatever binary you configure (claude -p by default), sending only the entry's kind, name, and definition.

How it works

Two sources in, one searchable index out.

  rc files  ────┐
                ├──►  merger  ──►  dedupe + hash  ──►  SQLite
  zsh -i -c ────┘                                        │
                                                         ▼
                                         query  ──►  JSON  ──►  UI

The parser reads your rc files and follows source chains recursively (with cycle detection). The introspector runs zsh -i -c to snapshot what your live shell actually loaded — plugin-defined aliases included. Entries merge, dedupe by content hash, and land in a single SQLite index. The web UI consumes the same JSON layer the CLI does. Full spec in docs/design.md.

You might also be looking at

Adjacent tools, different scope.

	helpshell	navi	tldr	explainshell	znt
Parses your rc files	✓	✗	✗	✗	✗
Follows `source` chains	✓	✗	✗	✗	✗
Snapshots live shell state	✓	✗	✗	✗	✓
Finds plugin-defined aliases	✓	✗	✗	✗	✓
Indexes `$PATH` binaries	✓	✗	✗	✗	✗
Indexes completions + keybinds	✓	✗	✗	✗	partial
Web UI	✓	✗	✗	✓	✗
Optional AI explanations	✓	✗	✗	✗	✗

helpshell is the only one that indexes your own config across every source your shell actually loads — rc files, sourced chains, plugin-defined symbols, and live $PATH.

CLI

Pipe-friendly. `--json` on every read.

$helpshell rebuild# re-index rc files + live shell (~1s for 3,500 entries)

$helpshell list --kind alias# all aliases, pipe-friendly

$helpshell search node-modules# fuzzy match

$helpshell show node-modules-list-old# full detail

$helpshell explain gst# AI explain (if enabled)

$helpshell doctor# verify zsh + claude + rc files + DB

$helpshell web# start the local UI — ⌘K to search