manp

manp is a local-first terminal command assistant. It watches the command you are editing in zsh, parses the executable/subcommands/flags at the cursor, and renders fast local help in a tmux side pane, at keystroke speed.

Build

go build ./cmd/manp

Put the resulting manp binary on your PATH.

zsh Setup

manp install-zsh > ~/.manp.zsh
echo 'source ~/.manp.zsh' >> ~/.zshrc

The zsh integration sends lightweight edit events to a persistent manp bridge coprocess. Parsing, docs lookup, and rendering happen outside the shell editing path.

How It Works

flowchart LR
  zshPlugin["zsh plugin"] -->|"BUFFER, CURSOR, PWD, timestamp"| localSocket["Unix socket"]
  localSocket --> daemon["manp daemon"]
  daemon --> parser["command parser"]
  daemon --> docIndex["local docs index"]
  docIndex --> manPages["man pages"]
  docIndex --> helpOutput["--help cache"]
  docIndex --> completions["shell completions"]
  daemon --> tui["tmux side pane TUI"]

Loading

manp keeps the shell editing path small. The sourced zsh hook observes the current BUFFER, cursor position, working directory, and shell name, then sends that edit event to a persistent manp bridge coprocess. The hook does not parse commands or read docs itself, so typing stays responsive.

The bridge forwards edit events to manp daemon over a per-user Unix socket. The daemon parses the command line, identifies the executable, subcommands, current token, and active flag, then looks up local documentation from cache. If the docs are missing, it immediately publishes a placeholder state and indexes docs in the background.

Docs are collected locally from shell completion output, --help / -h, and man pages, then normalized into command summaries, usage text, flags, descriptions, and examples. Cached docs are reused on the hot path.

manp tui subscribes to the daemon over the same socket and renders the latest command context in a tmux side pane. manp attach starts the daemon if needed and opens that pane for you.

Run

Inside tmux:

manp attach

This starts the daemon if needed and opens a right-side pane running manp tui.

You can also run the pieces manually:

manp daemon
manp tui

Useful Commands

manp doctor
manp index git commit
manp index docker run
manp index kubectl get

Docs are cached under the user cache directory, or under MANP_CACHE_DIR when that environment variable is set.

Dev Setup

1. Build the binary and put it on your PATH

mkdir -p .local/bin
go build -o .local/bin/manp ./cmd/manp
export PATH="$PWD/.local/bin:$PATH"
export MANP_CACHE_DIR="$PWD/.cache/manp"

2. Check if it works

manp doctor

3. Start a tmux session

tmux new-session -s manp

4. Perform the config steps

export PATH="$PWD/.local/bin:$PATH"
export MANP_CACHE_DIR="$PWD/.cache/manp"

5. Load the zsh hook

source <(manp install-zsh)

6. Attach the TUI to a tmux pane

manp attach

7. Start typing commands to see local help!