Reference

01Keys & commands

There are no modes, so every key below does the same thing whenever you press it, like VS Code or Emacs and unlike vim or helix. The keys come in three families: function keys, Ctrl and Alt. Remember what each family is for and the rest follows. These are the defaults (the obelus layout below), and you can rebind any of them: see settings.

Four layouts

Which keys you start from is the keys_from setting, and there are four. obelus is the tables on this page. mnemonic moves the twelve function keys onto Ctrl and Alt by the letter of the word, for a keyboard without the row, and nothing else. vscode and textmate use the keys those editors taught you wherever Obelus has the same command, and have no function keys at all; the rest of Ctrl and Alt stays as below. They adapt those editors' keys to what Obelus has; they are not a copy of either.

Shift on a letter is written out: Ctrl+Shift+p. Most terminals can't send Ctrl with Shift on a letter, and send plain Ctrl+p instead, which is why each of those has an Alt key beside it that every terminal can send. obg gets them as they are. In obg on a Mac, Ctrl is Cmd, in every layout: press Cmd+p where this page says Ctrl+p, and the screen says Cmd too. Ctrl itself still works there, and the settings file still says Ctrl, because ob in a terminal reads the same file and a terminal keeps Cmd for itself. Elsewhere the Super or Windows key is never read as Ctrl; it belongs to the desktop.

On a Mac, a terminal sends Alt only when Option is set to act as Meta: in Terminal, Use Option as Meta key under Settings → Profiles → Keyboard; in iTerm2, Left Option key: Esc+ under Settings → Profiles → Keys. Otherwise Option types a character instead (Option+Shift+p is ∏) and every Alt key in Obelus does nothing. obg needs no setting.

To choose, open open-settings and pick Layout under Keys. Each row shows what that layout puts the files and the palette on. The very first time Obelus starts with no settings file, it asks; Esc keeps obelus and asks again next time, and any choice is saved straight away, obelus included, so it never asks again. Whatever you have under [keys] is laid over the layout, so switching layouts keeps your own keys.

Function keys open something to look at

Three groups of four, the way they sit on the keyboard: F1–F4 open things to read, F5–F8 search, F9–F12 are Git's history, go-to-definition, and the pull requests and issues. None of them takes a modifier, because terminals disagree about what something like Shift+F5 sends, so a binding like that works on one machine and not the next.

Control does something to the file in front of you

Alt asks about the cursor, or jumps between results

And two without a modifier

Insert is toggle-replace: what you type replaces the character under the cursor instead of going in front of it, and the status row says Replacing while it is on. Esc clears the selection, or closes whatever is on top.

Moving, and inside a list

Moving around isn't a command, so it isn't in the tables above: the arrow keys, PageUp/PageDown, Home/End for the start and end of a line, Ctrl+Home/Ctrl+End for the start and end of the file, Ctrl+↑/Ctrl+↓ to scroll the view a row and leave the cursor where it is. Up and down go by the rows you see, so a wrapped line moves the way it looks. Shift is never a command of its own: it only extends the selection.

In any list (a picker, the settings, the line counts): type to filter, ↑↓ to pick, PageUp/PageDown to move a page, Home/End to jump to either end, Enter on the row you're on, and Esc to cancel. A list with a preview under it shares the keys with it: ↑↓ and Ctrl+PageUp/Ctrl+PageDown move the list, and PageUp/PageDown and Ctrl+↑/Ctrl+↓ scroll the preview. A list with keys of its own says what they do along the bottom. Function keys work inside a full-screen view too, and swap it for the view they open: F6 from the file list goes to search, and F3 is the file list's other tab.

In a conversation

Enter sends, and Alt+Enter starts a new line (Shift+Enter does too, in terminals that support it). In a conversation about a note, → in the empty box fills in a suggested first message. Shift+Tab switches between the agent's own modes, shown along the bottom. Esc stops the agent, along with any command it is running. Alt+t takes you to the note the conversation is about. When the agent asks you something, it's a card: ↑↓ to move, Enter to answer.

On the notes page

The notes page is always ready for typing: letters go straight in, Enter starts a new note, and Alt+Enter or Shift+Enter starts a new line inside one. Tab moves a note under the one above it, and Shift+Tab moves it back out. Everything else you do to a note is under Alt: Alt+Space ticks it, Alt+o goes to the line it points at, Alt+a opens its conversation, Alt+↑Alt+↓ move it, and Alt+← removes it.

In a terminal

open-terminal opens your shell in the project, as a document of its own. When an agent needs you to sign in, its sign-in runs in one of these too. While a program is running, it gets the keys, Esc and Ctrl+c included. Obelus keeps only the function keys, the palette (Ctrl+p, or in the vscode and textmate layouts Ctrl+Shift+p and Alt+Shift+p, which have no function keys and leave Ctrl+p to the program), Ctrl+q to quit, Ctrl+v or Shift+Insert to paste, and Ctrl+w to close the terminal (it asks first if the program is still running).

To look back at output that has scrolled away, use the mouse wheel, PageUp/PageDown for a screen at a time, or Ctrl+Home/Ctrl+End for the very top and bottom; those keys are Obelus's and never reach the program. Drag to select what was printed, then Ctrl+c or Ctrl+Insert to copy it; with nothing selected, Ctrl+c goes to the program as usual. If the program uses the mouse itself (an editor, a process list), it gets the left button and the wheel; hold Shift to select anyway. Quitting while a program is running asks first, and once it ends the keys are Obelus's again.

Commands

Press Ctrl+p and type the name. Every name starts with what it does, so type the verb first. The palette sorts them into six tabs, roughly in the order you'd use them: open something, find your way around, ask what the code means, change it, look at what changed, and Obelus's own housekeeping last.

02The agent's tools

Through ACP an agent can already read files and ask for permission, but it can't get at your notes. So Obelus gives it a few extra tools over MCP. The tools themselves never ask you anything: the agent is the one who asks, on a card, before it calls one.

Three more: open_file opens a file at a line once you say yes (Alt+← takes you back); read_workflow tells the agent which workflow this project uses before it changes anything; and close_conversation closes the conversation once you say yes.

03Settings & themes

Two files

No file means the defaults, and so does a line Obelus doesn't recognise: a typo should still leave you with a working editor, not an error message. The one exception is a file Obelus can't parse at all. Then it stops writing to that file, so it doesn't save over settings it couldn't read, tells you so, and carries on as soon as the file parses again.

It also tells you which line. A settings file that won't parse, a key binding that doesn't work, a setting the project isn't allowed to set, a theme with no file: each is marked on its own line, in the same list as the language server's errors, so Alt+e and Alt+[ Alt+] find them like any other problem.

The settings

A few settings only apply to the window or only to the terminal. The settings page only shows the ones that apply to the version you're in, so you never change something and see nothing happen. The file keeps all of them, because the other version on the same machine reads it too.

Rebinding

Write only what you want to change: rebind one key and everything else keeps its default, including keys Obelus adds later. A command can be on several keys: write them as a list, and the first is the one the screen shows. An empty string or an empty list removes its keys. Any key may be bound, whether or not every terminal can send it, except the few Obelus never hands to the table: a plain character, Esc, Enter (but Alt+Enter may be), Tab, Backspace, Delete, and the moving keys without Alt. Use the command names from above, and write keys the way the screen shows them (case doesn't matter: Ctrl+P is ctrl+p, and Shift is written as shift+). Your lines are laid over whichever layout keys_from names, so they survive a change of layout.

theme = "light"
wrap = true
blame_margin = false

[keys]
open-file = "Ctrl+o"
show-change = "Alt+g"
run-command = ["Ctrl+Shift+p", "Alt+Shift+p"]   # on both
quit = ""            # taken away

On the settings page, the Keys tab lists every key a command is on, one to a row. Enter changes a key: it waits for the one to put in its place. Ctrl+Enter on any of a command's rows adds one more key, and is how a command with no key gets its first. A terminal without the keyboard protocol sends Ctrl+Enter as Enter; there, add a key in the file, a command's first included. Alt+Backspace takes the key on that row away, Alt+r puts the command back on its layout's keys, and Alt+Shift+r puts every command back, after asking. On alt because the filter takes nothing there: Backspace and Delete are the filter's. A command whose keys are not its layout's says Changed beside its name, and the keys at the foot are offered only where they would do something.

Themes

dark, light and a shelf of well-known palettes are built in; choose-theme switches between themes instantly. Any .toml file in ~/.config/obelus/themes/ is also a theme, named after the file (mine.toml → mine), and so is a directory there holding a theme.toml, named after the directory — which is how a theme keeps a picture beside its colours. A theme of yours by a built-in name comes first. Every colour is optional: anything you leave out comes from the built-in theme yours is based on, so an old theme file keeps working when Obelus adds a colour.

Comments are drawn italic. A theme says which kinds of code are slanted under [syntax], by the names its colours have there: italic = ["comment", "keyword"], or italic = [] for none. A theme that does not say keeps the set of the one it is based on.

In a window, a theme may carry a wallpaper under the page. The file names it in a table of its own; everything but file may be left out:

[wallpaper]
file = "rain.jpg"     # beside theme.toml
opacity = 85          # how much of the page covers it, 0 to 100
fit = "cover"         # cover, contain, stretch, center or tile
anchor = "center"     # what stays put: top-left, top, top-right, left,
                      # center, right, bottom-left, bottom or bottom-right

How much of the picture you see is also up to you: picture_strength in your settings is a percentage of what opacity lets through, so opacity = 85 with picture_strength = 200 lets thirty through instead of fifteen. A terminal has no pixels to put one in, so ob wears the colours alone. A line Obelus can't use is marked and left at its default, and a picture that isn't there is marked too.

More themes are on the settings' Themes page: the ones made for Obelus, and omarchy's own, turned into Obelus themes. Enter installs or updates the one you are on — a theme you install for the first time is put on as soon as it arrives — and Delete takes it away again, except the one you are wearing; a theme the list no longer carries stays until you take it away, which takes Delete twice. What you install is kept apart from your own ~/.config/obelus/themes/, and a theme of yours by the same name comes first. Every list of themes ends in More themes, which goes there; and a name the list hasn't got is taken there with Enter, already typed into its filter.

omarchy is offered wherever omarchy has written a theme for Obelus; contrib/omarchy/ in the repository is the template that makes it, so that changing your desktop theme changes Obelus's colours with it.

04Several windows

Obelus has no split panes, so it's normal to have several Obelus windows open at once: on one project, on different worktrees of it, next to your own shell. Here's what that means in practice.

• All the worktrees of a repository share one set of notes. What one window writes shows up in the others by itself.
• Two windows editing the same file don't erase each other: every change is made against what's on disk at that moment. Before saving, Obelus checks whether another window, an agent or a formatter changed the file since you opened it.
• A conversation can be open in only one window at a time. That hold goes away when the window's process ends, so a crash never leaves a conversation stuck.
• Change the settings file in one window, or by hand, and every window picks it up.
• If the worktree a window is on is removed, from your shell or with git worktree remove, a page over the whole window says so. Enter lets go of everything that was open there (there is nowhere left to save it) and asks which project to open next; Ctrl+q quits.
• In the worktree list (F2, then Tab), a tree next to the main checkout is shown by its own name, one inside it by the path down to it, and anything else by its full path. A tree deleted without telling Git says Missing and can't be chosen.
• Each window runs its own language server and its own agent. Three windows on one Rust project means three rust-analyzers.