Omamd

A Markdown renderer for the agentic era. Point it at .md files agents write — chat exports, generated docs, READMEs, notes — and it follows your palette, reloads as the file grows, renders in the terminal over SSH, and converts to HTML when you need a page.

Linux (GTK), macOS, and iOS share one C core. The floating overlay is the same on every shell: preview/source top-right, Open / Theme / Follow bottom-right.

Repo: https://github.com/gbyx3/omamd

Install via an agent

Paste that URL into your agent and tell it to install omamd. The agent should follow this procedure exactly, without skipping steps or asking for a different prefix.

1. Clone

git clone https://github.com/gbyx3/omamd.git
cd omamd

SSH if the environment already uses it: git@github.com:gbyx3/omamd.git

2. Dependencies

Need gcc and make. The GTK window also needs pkgconf, gtk3, and webkit2gtk-4.1. --html and --term build without those.

On Omarchy they are already installed. If a check fails:

omarchy pkg add gtk3 webkit2gtk-4.1

On other Arch:

sudo pacman -S --needed gcc make pkgconf gtk3 webkit2gtk-4.1

3. Build

./bin/build

Expect Built …/omamd/build/omamd. Run ./bin/test if you want the --html / --term smoke check (no GTK needed).

4. User-local install (no sudo)

make install

This installs:

Path	What
~/.local/bin/omamd	binary
~/.local/share/applications/omamd.desktop	launcher entry
~/.local/share/icons/hicolor/scalable/apps/omamd.svg	icon
~/.local/share/omamd/fonts/	iA Writer Mono S (OFL)

~/.local/bin is on PATH on Omarchy. If command -v omamd fails, prepend it: export PATH="$HOME/.local/bin:$PATH".

Do not use ./bin/install unless the user asked for a system-wide Arch package. That path runs makepkg and needs sudo.

5. Verify

command -v omamd
omamd --html examples/welcome.md | grep -q '<h1>'
omamd --term examples/welcome.md | grep -q Welcome
test -f "$HOME/.local/share/applications/omamd.desktop"

All four should succeed. Then:

omamd examples/welcome.md

The Omarchy launcher should list omamd. Markdown files can be opened with it from the file manager.

Later updates: git pull && ./bin/build && make install from the clone.

Viewer

omamd notes.md

Bare window, no title bar. The round button in the top-right switches Preview and Source and stays put while you scroll. Open, Theme, and Follow sit in the bottom-right corner. Follow is a pin: when it is on, a file change eases down to the new bottom. Drop a .md on the window to open it. Relative links to other Markdown files in the same folder open in omamd; http/https links go to the browser.

The preview uses the active palette (see Palette) and reloads when that file changes.

Key	Action
Ctrl+O	Open
Ctrl+R / F5	Reload
Ctrl+1 / Ctrl+2	Preview / Source
Ctrl+Q	Quit

macOS and iOS

The Apple app is apple/Omamd.xcodeproj, bundle id rocks.gurra.omamd. Same overlay as Linux. Theme picks a bundled Omarchy palette or a colors.toml you choose. Follow is the pin.

On macOS, drop a Markdown file on the window. Settings (⌘,) holds the theme, a window opacity slider, and Hide title bar.

On iOS, open a .md from Files or Open with omamd. Palettes live in the app container.

make test-mac
make test-ios

Those build the Mac app and the iPhone simulator app. The Mac CLI (omamd --html / omamd --term) is make without GTK.

Terminal (SSH)

omamd --term notes.md
omamd -t notes.md

No GTK window. Markdown is rendered as colour text in the terminal, using the same palette as the viewer. Over SSH — no WAYLAND_DISPLAY or DISPLAY — omamd notes.md does this by itself.

A TTY opens a pager. If the file is being written — an agent appending to it — omamd reloads. Follow starts on: the view jumps to the new bottom. f pins the view where you are; f again jumps to the end and keeps chasing it.

Key	Action
j / k / arrows	Scroll
space / b	Page down / up
g / G	Top / end
f	Toggle follow
q	Quit

Piped stdout is just ANSI (omamd --term notes.md | less -R). Set NO_COLOR for plain text.

Markdown to HTML converter

omamd --html notes.md > notes.html
omamd --html < notes.md > notes.html

Turns Markdown into a full HTML document (styled with the active palette) on stdout. No window. Useful when a pipeline already has .md and you want a page you can archive or attach.

Unsafe URL schemes (javascript:, file:, data:text/html, rooted /etc/... paths) are stripped so the HTML is fit to open in a browser.

Palette

The file format is Omarchy's colors.toml. omamd reads background, foreground, muted (or dark_foreground), accent (or blue), dark_background (or darker_background), lighter_background, selection, and mode. Extra keys are ignored.

Lookup order:

1. omamd --theme PATH — a file, or a directory that contains colors.toml
2. $OMAMD_THEME — the same
3. Omarchy live theme — ~/.local/state/omarchy/current/theme/colors.toml (follows omarchy theme set)
4. A file you paste — $XDG_CONFIG_HOME/omamd/colors.toml, or ~/.config/omamd/colors.toml
5. Built-in dark palette

To supply a palette by hand, copy a theme from a machine that has one, or start from the example:

mkdir -p ~/.config/omamd
cp examples/colors.toml ~/.config/omamd/colors.toml

make install also puts a copy at ~/.local/share/omamd/colors.toml as a template. The viewer reloads if you edit the active file while it is open. The overlay Theme button picks a bundled palette or a file; on Linux that pin is stored in ~/.config/omamd/ui.ini so it does not fight omarchy theme set.

One-shot, without installing a config file:

omamd --theme examples/colors.toml notes.md
OMAMD_THEME=~/.config/omamd/colors.toml omamd --html notes.md

Markdown it understands

Headings, bold, italic, strike, code, fenced and indented blocks, lists, task boxes, quotes, tables, links, images, autolinks. Everyday README Markdown, not every corner of CommonMark.

Reading the code

Written in C, commented for someone new to the language.

1. core/omamd.h — the C ABI (markdown_to_html, palette, omamd_document)
2. core/markdown.h / core/markdown.c — Markdown → HTML
3. core/theme.h / core/theme.c — colors.toml lookup and palette
4. core/html.h / core/html.c — palette + fragment → full HTML page
5. core/util.h / core/util.c — file and path helpers
6. core/fonts.h / core/fonts.c — bundled iA Writer Mono S search
7. core/term.h / core/term.c — ANSI render and the SSH pager
8. cli/cli.h / cli/cli.c / cli/main.c — --html, --term, argv
9. linux/gtk.c — GTK window
10. apple/ — macOS SwiftUI + WKWebView app (rocks.gurra.omamd)
11. Makefile — how gcc is invoked
12. bin/ — build, test, install
13. pkgbuild/ — Arch package, desktop entry, and icon
14. fonts/ — iA Writer Mono S (SIL Open Font License 1.1; see fonts/OFL.txt)
15. examples/colors.toml — a paste-ready palette
16. examples/themes/ — Omarchy quattro colors.toml files plus Paper, for the theme picker
17. docs/iphone.png — iPhone screenshot (PNG32, phone only)

The preview and source views use the same iA Writer Mono that omawrite bundles. It is an OFL font: we may bundle and redistribute it with the app; we do not rename it.