What changed in 2.5.3

Written on 2026-07-28, as a snapshot of that day. Behaviour moves; this page does not. For the reference that is kept current, follow the links out of each section.

If you only read one thing

Upgrade. A background probe could get stuck re-running every 90 seconds, spending the very Claude budget the usage gauge exists to report — one reporter counted 21 runs in half an hour, and 41 of their 50 listed sessions were its leftovers. Nothing to configure; it is fixed by installing 2.5.3.

npx mulmoterminal@latest

Two things are new and off until you turn them on: sending raw key sequences to the terminal (keymap.send), and a digest of what a project already decided (decisionDigest).

The usage gauge stops burning your budget

Nothing to configure.

What was wrong

The gauge (top right, 5h / 7d) gets Claude’s numbers by starting one hidden Claude session and reading its status line. When that session brought nothing back, the code recorded no attempt — so the “our reading is stale” test stayed true and the next poll started another one. Immediately. Forever. Each run costs a real query against your window.

How to tell you have the fix

When the gauge cannot show Claude’s numbers, it now says why. Where the figures would be you get claude usage n/a; hover it and you get one of:

What you see on hover What it means
the claude command was not found on PATH Nothing to probe. Install claude, and the gauge recovers on its own — no restart
this account reports no 5h / 7d windows (API-key billing) Structural: API-key billing has no windows to report. Asked again about once an hour in case billing changes
the last check got no answer. Retrying, less often each time An unanswered trust prompt, an expired login, or a machine too slow. Backs off 90s → 3m → 6m … up to an hour

Before this, “not measured yet” and “cannot be measured here” looked identical — which is exactly why a runaway loop could run for half an hour without anyone noticing.

And the sessions it left behind

The probe’s own throwaway sessions no longer appear in the session list.

Sessions created before you upgrade stay visible — they were written with random ids that cannot be told apart from yours, so nothing can safely single them out. They also remain in claude --resume, which is Claude’s own history. What 2.5.3 changes is that the pile stops growing. Cleaning up what is already there is tracked in #1010.

Send raw keys to the terminal (keymap.send)

This one is opt-in. It started with wanting Cmd+→ to jump to end-of-line on a Mac.

Every other keymap entry points a key at an app action. send is different: it puts bytes into the focused terminal, so you can bind whatever your shell or editor already understands.

  1. Open ~/.mulmoterminal/config.json.

  2. Add a send list inside keymap:

    {
  "keymap": {
    "send": [
      { "key": "Cmd+ArrowRight", "bytes": "\u0005" },
      { "key": "Cmd+ArrowLeft",  "bytes": "\u0001" }
    ]
  }
}
  3. Restart mulmoterminal, then reload the browser tab.
  4. Click into a terminal and press Cmd+→ — the cursor jumps to the end of the line.

bytes reaches the PTY verbatim. Control characters are written the way JSON writes them, so "\u0005" is Ctrl+E (end of line) and "\u0001" is Ctrl+A (start of line) — nothing re-escapes them for you. Cmd, Command and Meta all name the same modifier; Option is Alt.

If a binding is wrong, MulmoTerminal says so at startup rather than binding something surprising.

Full reference, including every action you can bind and how modifier names are parsed: Keyboard shortcuts.

What this project already decided (decisionDigest)

Also opt-in, and newly documented in the guide with this release.

An agent that asks you something you settled last week is not learning. Turn this on and MulmoTerminal keeps a Markdown digest of the questions this project’s sessions actually asked — the options each offered and which one you picked — for an agent to read before asking something similar.

  1. Open ~/.mulmoterminal/config.json.

  2. Add:

    { "decisionDigest": true }
  3. Restart mulmoterminal — this key has no Settings screen, and the file is read once at startup.
  4. Look for ~/.mulmoterminal/decisions/<project>.md. It is written at startup and refreshed every 6 hours, for the directories this host is actually working in.

It never writes into your repository. The digest holds dated facts, not inferred rules — “you always pick the recommended option” reads convincingly and can be wrong, and a wrong lesson applied silently is worse than none. Decisions where you rejected every option and wrote your own answer are kept too; those are the ones worth reading, because the question was wrong.

Agents reach it through the bundled mulmoterminal-decisions skill, mirrored into ~/.claude/skills/ like the other bundled skills.

Reference: What this project already decided.

Fixes you do not have to do anything about

What was broken How to tell you have the fix
Project colours only reached Claude cells. The six chrome colours in .mulmoterminal.json did nothing in Shell (launcher) and Command cells — they silently fell back to the defaults Open a Shell or Run cell in a directory with chrome colours set. It is now tinted like the Claude cells beside it
A cwd with a trailing slash broke live reload. Editing .mulmoterminal.json did not reach a cell opened as /path/to/repo/ — the path was two names for one directory, and the announcement went to the other one Edit .mulmoterminal.json and watch the cell change without a reload, whichever way the path was written
Sessions that survived a server restart lost their folder on the phone. A session still alive in tmux showed up with no cwd and no work item Restart the server with a session running, then open the phone view — the row still knows its folder

Also in this release: the phone session list now carries the issue / PR each cell is working on (number, title and phase) as data for a phone client to show, and this repo’s own CI stops waiting 15 minutes on a review job that has hung.

This site uses Just the Docs, a documentation theme for Jekyll.