Omatate

A floating notes panel for Omarchy. Group notes into sections and attach screen clips beside your work.

Each project is a folder you choose, with notes.md, records in .data/, and screen clips in assets/.

Install

Omatate needs Omarchy Quattro with its Quickshell shell running. No build or setup is needed for typing notes.

omarchy plugin add https://github.com/cordrogue/omatate.git --enable

Open the panel from the shell's plugin controls, or from a terminal:

~/.config/omarchy/plugins/cordrogue.omatate/bin/omatate open

The examples below use this alias:

alias omatate="$HOME/.config/omarchy/plugins/cordrogue.omatate/bin/omatate"

The launcher uses Python 3 and omarchy-shell. Storage uses Python 3, coreutils, and findutils. The analysis wrapper also uses Bash and coreutils. The process supervisor runs /usr/bin/python3 in isolated mode and needs no Python packages or build step.

Service tools use fixed paths under /usr/bin. Codex uses /usr/bin/codex if present, otherwise ~/.local/share/mise/installs/codex/latest/bin/codex, the Omarchy mise installation. Omatate resolves that installation to an absolute path before launching it. Commands elsewhere on PATH are not used by the service.

Feature	Tools
Screen clips	grim, slurp
Dictation	voxtype, configured for your microphone
AI screen descriptions	grim, hyprctl, an authenticated codex CLI

Use

omatate open restores the last project or shows the project selector. Drafts and edits save after a typing pause and before switching projects or closing. Submit a draft with Ctrl+Return or Ctrl+S to turn it into a note.

Action	Shortcut
Save a new note	Ctrl+Return or Ctrl+S
Delete the focused note	Ctrl+Delete
Search notes and descriptions	Ctrl+F
Show projects	Ctrl+P
Add a section	Ctrl+Shift+S
Capture a screen clip	Ctrl+Shift+C
Expand the focused note	Alt+Shift+Return
Cycle panel opacity	Ctrl+Shift+O
Show help	Ctrl+H or F1

Useful commands:

omatate open-project /path/to/project   # open a folder as a project
omatate clip                           # attach a selected screen rectangle
omatate screenshot                     # attach if active; use Omarchy otherwise
omatate stop                           # save and end the session
omatate help                           # list every command

A clip is saved inside the project and linked from notes.md. Deleting a note keeps its image file.

Bind keys in Hyprland

Add these to ~/.config/hypr/bindings.lua. They replace the listed bindings; omit HOME if you do not dictate. Reload with hyprctl reload, then check hyprctl configerrors.

local omatate = os.getenv("HOME") .. "/.config/omarchy/plugins/cordrogue.omatate/bin/omatate"
hl.layer_rule({ match = { namespace = "^omatate" }, no_anim = true, animation = "none" })
hl.unbind("SUPER + SHIFT + U")
o.bind("SUPER + SHIFT + U", "Omatate session", omatate .. " toggle")
hl.unbind("SUPER + U")
o.bind("SUPER + U", "Omatate keyboard focus", omatate .. " focus-toggle")
hl.unbind("F10")
o.bind("F10", "Screenshot to active notes or Pictures", omatate .. " screenshot")
hl.unbind("PRINT")
o.bind("PRINT", "Screenshot to active notes or Pictures", omatate .. " screenshot")
hl.unbind("HOME")
o.bind("HOME", "Start dictation", omatate .. " ptt start")
o.bind("HOME", "Stop dictation", omatate .. " ptt stop", { release = true })

F10 or Print Screen selects a rectangle and attaches it to the active project. The panel hides during capture. The image stays in the project's assets/, with a link in notes.md; Escape cancels. A hidden panel still has an active session until you end it. With no active session or an unavailable plugin, the key uses Omarchy's normal screenshot flow and configured Pictures folder. Some keyboards send PRINT from the F10 screenshot key, so both are bound.

Super+U switches focus between the panel and the previous window. HOME dictates into the new-note editor when it has focus; elsewhere it uses plain Voxtype.

Configure

Colors and fonts use Ghostty's configuration, with Omarchy theme fallbacks. Icons use the Omarchy accent or Ghostty's blue. Theme changes apply automatically.

To change shortcuts, copy share/keys.toml to ~/.config/omatate/keys.toml and keep only the actions you want to override. An empty array disables a shortcut. Invalid or conflicting entries fall back to the defaults.

Privacy

Omatate runs as your user inside the Omarchy shell. Installation does not change desktop configuration or install a system service. Clips capture your selected rectangle. Voxtype's configuration determines whether dictation audio stays local.

AI descriptions are off by default. Turn them on with omatate ai on. When on, a push-to-talk press in the new-note editor screenshots the whole focused monitor, including other windows, with the panel hidden. Omatate passes it to codex exec using your CLI account and a read-only sandbox. Codex can read the project folder, which is its working directory. The temporary screenshot is deleted after about five minutes. Turn analysis off with omatate ai off.

Set OMATATE_MODEL and OMATATE_REASONING in the shell's environment to override the defaults, gpt-5.6-sol and low. The service reads these settings and passes them as command arguments.

Child processes receive a closed environment containing HOME, the XDG storage paths, Wayland and Hyprland connection settings, the session bus address, and CODEX_HOME when set. PATH is /usr/bin and the locale is C.UTF-8. Other shell variables, including startup hooks, interpreter options, and proxies, are not inherited. Codex uses its saved login under HOME or CODEX_HOME. The CLI additionally preserves OMARCHY_PATH, X11 connection settings, and screenshot directory settings for Omarchy. Both CLI entry points use isolated Python startup and fixed executable paths, including screenshot and dictation fallbacks.

Ordinary command stdout and stderr are limited to 1 MiB each. Exceeding either limit fails the command. Project and configuration text files have an 8 MiB read and write limit; oversized saves fail before replacing the existing file. The reader rejects devices, pipes, and invalid UTF-8. AI analysis has a four-minute deadline; cancellation or timeout stops and reaps its descendants as well as the direct process.

Files

Location	Contents
<project>/notes.md	Markdown generated from the records
<project>/.data/	Note records, draft, transcripts, analysis results, logs
<project>/assets/	Screen clips
~/.config/omatate/ai	AI opt-in
~/.config/omatate/keys.toml	Shortcut overrides
~/.local/state/omatate/projects.json	Known projects
$XDG_RUNTIME_DIR/omatate/	Active project pointer and temporary files

Omatate honors XDG_CONFIG_HOME and XDG_STATE_HOME. Back up the whole project, including .data/ and assets/. Edit notes in the panel; saves overwrite notes.md with Markdown generated from the records.

Update and remove

omarchy plugin update cordrogue.omatate
omarchy plugin remove cordrogue.omatate

Finish dictation and analysis before you remove the plugin. Removal leaves your project folders and preferences in place. Remove any alias or keybindings you added.

Development

docs/testing.md covers the service, QML, and Quickshell checks and the startup benchmark. CONTRACT.md describes the file format and service behavior.

MIT licensed. Icon attribution is in qml/icons/README.md.