matterbox / Docs / Configuration

Configuration — config.yaml

matterbox writes its own configuration file on first run, with a comment over every key. This is that file, key by key.

Everything matterbox lets you change lives in one YAML file. It is written for you on first run with every key at its default and a comment block explaining each one, so the file itself is the quickest reference — this document is the long version: what each key does, what it defaults to, when a change takes effect, and which keys interact.

Nothing here is required. A config with a single server_url line is a complete config; the rest exists so you can change your mind about a default.

Where it lives

MATTERBOX_CONFIG_DIR names the directory verbatim — nothing is appended — and relocates everything matterbox keeps on disk, not just the config. That makes it the way to run a second profile against another server:

$ MATTERBOX_CONFIG_DIR=~/.config/matterbox-work matterbox

The rest of the directory:

Your Mattermost credentials are not in config.yaml — the session token lives in mm_token.json. The config does hold the Jira, GitLab and Telegram secrets, which is why it is owner-only; matterbox tightens the permissions every time it reads the file, not only when it rewrites it.

First run, and when matterbox rewrites the file

• No file? Defaults are written to disk, so you can discover what is configurable by opening it.
• Missing a section? When a build adds settings, the first load fills them in and rewrites the file, so new keys show up as editable defaults rather than staying invisible.
• A syntax error is fatal. matterbox reports the YAML error and exits instead of silently falling back to defaults — a typo should not quietly change how your client behaves.
• An unknown key is ignored. The loader skips keys it doesn’t recognise, so a misspelled setting fails silently at runtime. Your editor is what catches those (see below) — the schema rejects unknown keys.

A rewrite keeps your values but regenerates the file from scratch: the header comments come back, keys are re-ordered canonically, and any comments you added are lost. Four things trigger one:

1. the file did not exist;
2. a section or key from a newer build was missing;
3. matterbox welcome saved your answers;
4. you reordered the team tabs in the TUI with < / > (which persists team_order).

So treat the file as data rather than a place to keep notes, and if you want commentary that survives, keep it in a copy under version control.

Editor autocomplete

matterbox drops a JSON Schema next to the config and puts a modeline at the top of the file:

# yaml-language-server: $schema=config.schema.json

Any editor running the YAML language server (VS Code’s YAML extension, Neovim’s yamlls, Helix, …) then gives you key completion, hover docs, enum values, and a warning on unknown or mistyped keys — with no per-editor setup, because the schema path is relative to the config itself. The file is refreshed on every load, so it always describes the build you are running.

What takes effect when

• The TUI reads the config once, at startup. Restart it after an edit.
• matterbox listen re-reads the config on SIGHUP, but only swaps the rules: block in place (systemctl --user reload matterbox-listen). Changing any other listen:/telegram: option needs a restart of the daemon.
• CLI subcommands read the config per invocation, so they pick up an edit immediately.

Values that name a fixed set of choices (nav_modifier, vim_nav, emoji_images, image_thumbnails, code_theme) fall back to their default when you write something unrecognised — a typo costs you the setting, not the app. Keybinding overrides are the exception: an unknown action id, an unparseable chord, or a binding that collides with another action is a hard startup error, because a silently shadowed key is worse than a failure to launch.

Minimal config

server_url: https://mattermost.example.com

Then matterbox login. Everything below is optional.

Reference

The server

The default is a placeholder: commands that need a real server (login) treat a server_url still equal to it as “not configured yet” and send you to matterbox welcome.

Reading and display

Attachments, images and motion

animations: groups the motion toggles, so movement you find distracting can go away one piece at a time:

native_gif_protocol is the former name of native_animation and is still read, so an old config keeps working; the next rewrite drops it in favour of the new key.

keybindings

keybindings:
  nav_modifier: ctrl
  vim_nav: global
  bindings:
    compose: [i, a]
    delete_post: shift+d
    quit: []

On macOS ctrl+arrows collide with Mission Control — shift is the most broadly compatible alternative, and super (⌘) works on terminals that speak the Kitty keyboard protocol (Ghostty, kitty, WezTerm) but not on Terminal.app or iTerm2. Some chords only arrive at all on a Kitty-protocol terminal: shift+enter, for instance, sends on a legacy terminal instead of inserting a newline — use alt+enter there.

bindings rules of the road. A value is a single chord (shift+d) or a list ([i, a]); an empty list or the string none unbinds the action. Modifiers are ctrl, alt, shift, super, meta, hyper. Rebinding a navigation action drops its modifier-arrow alias too. ctrl+c always quits, no matter what you do to quit. An unknown action id, an unparseable chord, or an override that makes two actions collide in layers active at the same time is reported at startup, with the full list of valid ids.

matterbox keys prints every action, its default keys, your effective keys, and marks the ones you overrode — the authoritative list. In the TUI, ? expands the footer into every key active right now and f1 › Keys opens the full scrollable cheatsheet. The action ids, by layer:

• Focus / motion — focus_next, focus_prev, up, down, left, right, top, bottom, page_up, page_down, input_up, input_down
• Navigation — team_prev, team_next, channel_prev, channel_next, goto_team, goto_dm, goto_feed, switcher, command_picker, load_team, move_team_left, move_team_right
• Sidebar — filter, clear_filter, open_channel, mark_read, channel_info
• Messages — open_thread, reply_in_thread, goto_parent, edit_post, delete_post, react, collapse_message, close_thread, prev_own_message, copy_markdown, copy_code_block, edit_history, open_attachment, download_attachment, open_reference, preview_image
• Search — search_here, search_all, next_match, prev_match
• Feed — feed_mark_all_read, feed_toggle_muted, feed_reply, refresh
• Composer — compose, send, newline, leave_input, clear_input, undo, redo, paste, attachment_remove, apply_open, cancel_edit
• Reference panel — jira_status, jira_priority, jira_points, jira_assignee, jira_comment, jira_reply, gitlab_approve, gitlab_merge, gitlab_jobs
• Misc — confirm_yes, confirm_no, sheet_remove, help, quit

The jump-to actions (goto_team = alt+1…9, goto_dm = alt+d, goto_feed = alt+u) need alt to reach the app at all; on macOS that means macos-option-as-alt = true in Ghostty, or rebinding them here (goto_team: [super+1, super+2, …]).

Search, summaries and AI

All of it is optional and all of it talks to OpenAI-compatible endpoints, so a local llama.cpp server keeps your chat history on your machine. Leave the sections alone and the features simply stay unused; when a server is down, semantic search degrades to keyword and summaries fall back to raw text.

summary: — the > Summarize command (ctrl+k), and the chat model the listen daemon and agentic search reuse:

ai_search: — agentic search, triggered by ending a Search-tab query with ?. It reuses summary.endpoint and summary.model; these keys tune the agent:

embeddings: — semantic search. A separate server from summary, because an embedding model has to be loaded with --embeddings; see scripts/llama-embeddings.sh.

Vectors are stored tagged with model@dim, so changing either key makes the existing ones “not ours”: every message is re-pended for embedding rather than compared against vectors from a different model. Expect a full re-index after such a change (matterbox embed, or let the background indexer catch up).

search: — ranking for both the Search tab and AI search:

Composer helpers

giphy: — turn a pasted Giphy link into an inline ![alt](url) image. The expansion happens instantly and offline from the link’s id; with a key, the line is then upgraded in place with the GIF’s real title.

language_tool: — grammar and spell check in the composer. Off by default; when on, your draft is checked as you type and mistakes are underlined in place, with alt+g opening the suggestions for the one under the cursor.

The listen daemon

matterbox listen holds a WebSocket open, keeps the local cache warm, and bridges mentions and DMs to Telegram. telegram: is the delivery channel:

listen: is the behaviour:

These options are not only about the built-in behaviour: every notify action passes the same gate, including ones you write in rules:. So notify_dms: false silences a rule’s notify on a direct message too; summarize is the default a rule’s own summarize: overrides; and respect_mutes / respect_dnd / quiet_hours are skipped only for an action marked urgent: true. notify_on_mention is the exception — it decides whether the built-in rule exists at all, and has no effect once you write your own rules.

Independent of all of the above, the daemon stays quiet about what you are looking at right now: before notifying it asks the TUI on this machine what is on screen and skips the push if that channel is open in a focused window. Rules gate on the same signal with viewing: false.

rules

With no rules: block the daemon behaves exactly as the listen: options describe — that default is a rule. Add a rules: list to take over: match on team, channel, author, message text, mention, bot, channel type, time of day or thread status, and run actions (notify, exec, webhook, send, react, mark_read, log, and the persistent-ledger state_* actions). Rules can fire on new messages, edits, deletions, reactions, or on the clock (cron: "0 9 * * 1-5").

It is the largest thing in the config by far and has its own reference: the rules engine. matterbox rules test says which rules a message would fire and why the rest wouldn’t, and matterbox rules list / stats / state show what loaded, what has fired, and what the ledger remembers.

Rules are compiled when they load, so a bad glob, regexp or action type is a startup error rather than a rule that silently never fires — and a SIGHUP reload that fails to compile changes nothing: the daemon logs the error and keeps the ruleset it already had, so a half-written edit can’t disarm a working daemon.

Integrations: Jira and GitLab

Both are opt-in and both hang off one key: v on a message that names a Jira issue or links a GitLab merge request opens it in a side panel — read-only, with inline editing when the token allows it.

jira:
  base_url: https://your-instance.atlassian.net
  email: you@example.com
  api_token: …
  projects: [ABC, PROJ]
gitlab:
  base_url: https://git.example.com
  token: glpat-…

Jira targets Cloud (/rest/api/3); Server/Data Center instances won’t work as-is. What a token needs:

• GitLab — read_api for everything read-only (the panel, !iid badges, pipeline and approval state); api for the approve and merge actions, since GitLab has no narrower scope for MR writes.
• Jira, classic token — unscoped, so access follows your project permissions: Browse Projects to view, plus Transition / Assign / Edit Issues for the inline edits.
• Jira, scoped token — read:jira-work + read:jira-user to view, plus write:jira-work for the edits.

Environment variables

Recipes

A calm terminal. No motion, no mouse capture, every message in full:

mouse: false
collapse_long_messages: 0
animations:
  custom_emoji: false
  image_preview: false
  inline_images: false

macOS-friendly navigation, avoiding the Mission Control collision and alt-key trouble:

keybindings:
  nav_modifier: shift
  vim_nav: reading
  bindings:
    goto_team: [super+1, super+2, super+3, super+4, super+5]
    goto_dm: super+d
    goto_feed: super+u

A quiet daemon — keep the cache warm and search fresh, notify nothing:

listen:
  notify_on_mention: false

Local AI, all of it — chat model on :8321, embeddings on :8322, background indexing on:

summary:
  endpoint: http://127.0.0.1:8321
  model: your-chat-model.gguf
embeddings:
  endpoint: http://127.0.0.1:8322
  model: embeddinggemma-300m-qat-Q8_0.gguf
  auto_index: true

Then matterbox embed to backfill, and matterbox search --semantic or the Search tab to use it.

Troubleshooting

“parse config …: yaml: line N” — a syntax error; matterbox refuses to start rather than guess. Indentation is the usual culprit. Your editor flags most of these before you save if the schema modeline is in place.

A setting does nothing. Check the spelling: unknown keys are ignored at load time. matterbox keys shows the effective keybindings, and the schema in your editor marks unknown keys as errors — an unrecognised value for an enum-ish key (nav_modifier, code_theme, …) silently reverts to the default.

It won’t start after a keybinding change. That is by design: unknown action ids, bad chords, and collisions fail loudly, and the error lists the valid action ids. matterbox keys prints the same list.

My comments vanished. matterbox rewrote the file — see First run, and when matterbox rewrites the file.

Start over. Move the file aside and let matterbox write a fresh one:

$ mv ~/.config/matterbox/config.yaml{,.bak}
$ matterbox welcome

The message cache, token and stats are separate files, so a fresh config costs you nothing but your settings.