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

*2026-09-27*

> A heredoc replacement, agent-friendly file tool, and nano-style editor in one static C++17 binary with zero runtime dependencies.


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

```bash
# 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`.

```bash
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](https://github.com/rahlquist/hed) · MIT licensed.