hed: the tiny C++ editor that replaces heredocs and makes agents happy

Ask a shell script to write a file and you get heredocs — which bash and zsh handle fine but fish doesn’t. Ask an agent to edit a config and you get a tangle of sed, cat >, and hope. hed is the answer to both problems: a single C++17 binary that replaces heredocs, gives agents a machine-readable file editing API, and doubles as a nano-style interactive editor.

Three tools, one binary

hed (Heredoc Replacement · Agent File Tool · Nano-Style Editor) is a single static executable with zero runtime dependencies — no ncurses, no hunspell, no data files. Three modes:

Mode	Use case	Example
One-shot CLI	Scripts, agents, automation — never prompts, machine-readable exit codes	`hed replace file.py 'old = 3' 'new = 5'`
Pipe	Edit text in a pipeline — reads stdin, writes result to stdout	`cat config.yaml \| hed \| tee config.yaml.new`
Interactive	Full-screen editing with syntax highlighting, search, undo, spell check	`hed src/main.cpp`

Heredoc replacement

# Works identically in bash, zsh, and fish (which has no heredocs)
hed write config.yaml <<'EOF'
key: value
EOF

# Or one-shot with -c
hed write -p -m 755 ~/bin/hello -c '
    #!/usr/bin/env bash
    echo "hello $USER"
'

Atomic writes via write/fsync/rename. Exit codes: 0 success, 1 not found, 2 usage error, 3 ambiguous.

Agent-friendly one-shot commands

write · show · search · replace · insert · delete · spell · config · log

Every command is deterministic — no prompts, no TTY required, unified diffs printed for every change, ambiguous matches refused. An agent can script file edits with the same confidence it scripts git.

hed replace app.py 'retries = 3' 'retries = 5'   # must match exactly once
hed replace app.py 'print(' 'log(' --all --expect 7 -b
hed insert app.py --after-match 'import os' -c 'import sys'
hed delete app.py --range 88:90
hed spell README.md                               # exits 1 on typos

Interactive editor

hed FILE opens a full-screen nano-style editor with syntax highlighting for Python, Bash, Fish, JavaScript, TypeScript, SQL, HTML, CSS, JSON, and Markdown. 82,765-word SymSpell spell checking with suggestions ranked by edit distance + frequency. Undo/redo with depth indicator. Mark/cut/paste. Comment toggling. Live search with match counter. Crash recovery via swap files. Three built-in themes (catppuccin, dark, light) plus custom themes without recompiling. Shell completions for bash, fish, and zsh.

cmd | hed | cmd2 works like vipe — pipe text through the editor in-place.

Why it exists

Agents shouldn’t need to cobble together sed, awk, and cat to edit files. Shells shouldn’t lose heredoc support just because you’re using fish. And a full-screen editor shouldn’t require a terminal library the size of a dinner napkin.

hed is ~2 MB of C++17 that does all three jobs cleanly. Build it with make, install with sudo make install, and never think about heredocs again.

Platform support

Linux — native, primary target (make && sudo make install)
macOS — Intel and Apple Silicon (g++ via Homebrew or clang++ via Xcode CLT)
Windows (WSL) — works out of the box
Windows (native) — not supported; use WSL

Source: github.com/rahlquist/hed · MIT licensed.