/mulmoterminal-header

name: mulmoterminal-header
description: Put your own action buttons and info chips in a MulmoTerminal session header — either everywhere (`buttons` / `chips` in `~/.mulmoterminal/config.json`; the global chips, global buttons of every `run` type, and folders can also be changed in Settings → Header buttons and chips) or for one project (`<project>/.mulmoterminal.json`, also editable in Settings → Directory settings). Buttons run a shell command in a new cell, type text into the running agent (`/compact`), or open a URL, the file explorer, a diff/PR/wiki overlay, or a new terminal. Chips show live context — branch, context left, diff counts, the PR or issue being worked on. `commands` are written exactly like buttons but appear only in the command palette. Use when the user wants to add, remove, reorder or hide header buttons or chips, wants a one-click build/test/deploy on a session, wants the header to show something it doesn't, or asks why a button is missing or does nothing. For colours and grid order use mulmoterminal-dirs; for keyboard shortcuts use mulmoterminal-keys.

Header buttons and chips

A session header carries **buttons** (things you can do) and **chips** (things you can read). Both are configured in two places and merged, and **the two merge by different rules** — that asymmetry is the thing to get right, and it has no UI anywhere.

Where to write it

| File | Applies to | Settings UI | |---|---|---| | `~/.mulmoterminal/config.json` → `buttons` | every directory | Settings → Header buttons and chips: add a `shell`, `input`, `open` or `action` button, edit one in place (id, `order` and `emoji` kept), remove or move any top-level entry, put a button in a folder (existing or new) or take it out, change a folder's name / icon / `when`, back to the built-in set. Reordering inside a folder is written here | | `~/.mulmoterminal/config.json` → `chips` | every directory | Settings → Header buttons and chips (add, remove, reorder, back to the default set) | | `<project>/.mulmoterminal.json` → `buttons` / `chips` / `commands` | that project | Settings → Directory settings → Change here → Header: the same editors as the global ones, on that project's lists (commands have no folders). An unset list there is empty, not the built-in set |

Ask which the user means. "A button for `yarn build`" is usually per-project (the command only exists there); "show me the branch everywhere" is global.

Global writes are a **partial `POST /api/config` merge** — send only `buttons` / `chips`. Per-project writes go through your Write/Edit tool, and **writing the file is itself the live-reload signal**; there is no filesystem watcher.

**"Partial" is per TOP-LEVEL key, and `buttons` / `chips` are each replaced WHOLE.** The merge is `body[key] !== undefined ? sanitize(body[key]) : current` (`server/config/app-config.ts`), so posting

{ "buttons": [{ "id": "build", "icon": "build", "label": "Build", "run": "shell", "cmd": "yarn build" }] }

does not add a button — it **makes that the entire global set**, deleting every other button the user had. Nothing warns, and the reply is a success.

So a global write always sends the **complete** array: read the current one first, add or change your entry in memory, and post the whole thing. Every example below shows the entries under discussion on their own for readability — none of them is a body to post as-is unless the user genuinely has no others.

Three different "replace" rules live here and are easy to run together:

| | | |---|---| | writing `buttons` to the **global config** | replaces the whole global array — **the one this section is about** | | listing `buttons` **at any level** | replaces `DEFAULT_BUTTONS`; the built-ins are not merged in | | **project** vs **global** | merged, keyed by `id` — a project adds or overrides without restating |

How the two are merged — not the same rule

**Buttons merge by `id`.** Global buttons load first, then the project's: a project button with the same `id` **replaces** the global one, a new `id` is **added**. The result sorts by `order` (lower first, unset last), ties keeping insertion order. So a project can override one button without restating the rest.

**Chips replace wholesale.** A project that sets `chips` **discards** the global list entirely; one that omits the key inherits it. There is no per-chip override.

**`null` (absent) and `[]` are different.**

• `buttons` absent at *both* levels → the built-in starter set below.
• `buttons: []` → **no buttons at all**, not "the defaults". And setting it globally means a project

that configures nothing also gets nothing, since the empty list is what it inherits.

• `chips` absent → the client's default chip set. `chips: []` → every chip hidden.

**Omit the key you were not asked about.** Writing `chips: []` to a user who only wanted a button silently strips their header.

The built-in buttons

With `buttons` unset anywhere, these show. Each is an ordinary config button, so the way to trim or reorder them is to **list the ones you want** — there is no "remove" syntax.

| id | Label | What it does | |---|---|---| | `pr` | Open this branch's PR | Git repos only; **hidden when the branch has no open PR** |

The five that are no longer buttons

Insert a file path, Reveal in the file manager, the in-app file explorer, a new terminal here, and Open on GitHub used to be default buttons. They are now items in the **path menu** — click the directory path on any cell's header and they are all there. Open on GitHub became the menu's repository section, headed **GitHub** (Repository / Issues / Pull requests / Actions) or **GitLab** (Repository / Issues / Merge requests / Pipelines — gitlab.com or a host in `gitlabHosts`).

They moved because every one of them is a file operation on the directory this cell is in, which is the question the path itself asks; `reveal` was the path's own click outright. A permanent icon in a tiled cell for each o