merl

The one editor you need when agents write the code.

An agent works in one terminal split. merl sits in the other. You read what the agent wrote, walk
its branch hunk by hunk, jump from a changed line into the code around it, fix the one line that
is wrong, and go back to reading.

That is the whole tool: find your way around a project, review a diff with the code around it,
and now and then type a secret into a .env. No setup, no config, no modes. It runs wherever a
terminal does, SSH and tmux included.

_{A checkout of gitea, 5,500 files. Nothing was indexed or configured first.}

Install

brew install maksim-burtsev/tap/merl

Or take a prebuilt binary for macOS (arm64) or Linux (x86_64, arm64) from the
releases:

curl -fsSL https://github.com/Maksim-Burtsev/merl/releases/latest/download/merl-aarch64-apple-darwin.tar.gz | tar xz
sudo mv merl /usr/local/bin/

Or build it (Rust 1.88 or newer):

cargo install --git https://github.com/Maksim-Burtsev/merl

Then:

merl                 # the current directory
merl FILE:LINE[:COL] # what compilers, linters and grep print, pasted straight in
merl --review        # the branch you are on, as a diff over the real files
merl --tutor         # every key, hands on, in about ten minutes
merl --drill [N]     # N tasks (20) that name what to do, not the key; the keys you skip come most
merl --keys          # how often you press each key and miss it, the unused last
merl --reviews       # your reviews of the last 30 days: their size, their time, the jumps out

The long flags have short forms: -r for --review, -b for --base, -t for --theme,
-d for --drill and -k for --keys, so merl -r feature -b origin/dev reviews feature
against origin/dev.

Why

Agents write most of the code now. Your part is to understand it and to review it, and merl does
those two things out of the box, with nothing to configure and nothing to switch off.

• Understand the code. Open a file by a few letters of its name, search the project as you
  type, go to a definition or list its usages, and come back with [. It follows you into the
  standard library and the dependencies.

• Review a branch. merl --review draws the branch's diff over the real files, so from any
  changed line you can look up what it calls and who else uses it. It stays current while the
  agent keeps working, and a file you have walked through gets a tick that stays with the branch
  and goes when the file changes. A review, step by step.

  

• Touch up a line. Enter, type, Esc. It saves itself. Enough for a typo, a constant, or a
  secret you would rather not hand to an agent. More on editing.

I spent years switching things off in VS Code to get down to a tree, a highlighted file, go to
definition and search. Vim and Helix want weeks of learning and a config first. merl starts
there. It has no autocomplete, and it took me a while to notice: most of an editor is for typing
code, and I had stopped typing it.

What merl is not

• No plugins.
• No language server and no index. Nothing to install per language, nothing to wait for.
• No splits and no tabs. Your terminal has those.
• No mouse.
• No keymap to write. The keys are below and they stay.
• No autocomplete, no snippets, no refactoring. The agent types.

None of these is on a roadmap. If you live in Vim or Helix and like it there, you do not need
merl.

Keys

The dozen you will use every day. ? inside merl shows the rest.

The keys never change, so what you learn stays learned. merl --tutor walks you through them
once. After that merl counts the keys you press in real work, and notes when another key would
have got there in half the presses. merl --keys shows the ones you skip and the ones you miss,
and merl --drill asks for those most: its tasks say what to do and never name the key. The
counts stay on your machine.

Files and jumps

Search

Review

Editing

Selection

Movement

Panels

General

Languages

d, u and D work in all of these, with no language server and no index: a project works the
moment you open it. In Python, TypeScript and Go, d also follows the type of the receiver
(self.repo.save), and it always says how it found its target.

What each rule reads and what it refuses to guess: docs/navigation.md.

Themes

T lists the themes and repaints merl in the one under the cursor as it moves. Enter keeps it,
Esc puts the old one back. The default is tokyonight-moon. They were picked to sit in for
hours: no neon, and light themes that look like paper.

docs/themes.md has a screenshot of each and how to add your own.

Config

There is none to write: every setting has a default, and T saves the theme you pick. To change
the rest, edit ~/.config/merl/config.toml.

For example, to save sooner and keep review's rows unmarked:

autosave_delay_ms = 300
review_list_marks = false

Terminals

Any terminal, and the same keys over SSH and in tmux. Terminals keep Cmd for themselves, so copy
is Ctrl+C and quit is q. Terminal.app is the weak one: no Shift+arrows, no Ctrl+Home, no copy.

In Ghostty, keybind = performable:cmd+c=copy_to_clipboard:mixed makes Cmd+C and Cmd+X work too.

Status

I use merl every working day. 1.0 is next, and what is left for it is in the
milestone. Issues are welcome.

License

MIT. Syntax definitions come from bat via
two-face; the themes keep
their authors' licences.