Gmail and Google Calendar in your Linux or Mac terminal, with a CLI for agents and a read-only Gmail widget for the Omarchy bar. Keep your mail accounts separate, combine selected calendars across up to three accounts, and join meetings in the right Chrome profile.
Explore the website and user documentation.
A real v0.2.10 terminal capture with fictional demo data. Calendar guide · Terminal guide.
Read and write mail, plan meetings, answer invitations and get meeting reminders in the native TUI. The optional encrypted vault and unlocked daemon serve the TUI and agent CLI, including over SSH. The Linux Omarchy bar stays a separate, read-only mail interface.
Recommended: agent-guided setup. Give your coding agent the website URL
or GitHub URL and ask it to install Omagma and walk you through Google Console and OAuth one
step at a time. Tell it your platform and whether you want the Linux read-only bar or full TUI/CLI
access. On macOS, Homebrew is preferred: brew install renerocksai/tap/omagma. It can prepare private configuration and open consent in each account's
Chrome profile while you complete the Google steps.
Copy a setup prompt.
For macOS, install with Homebrew or use the verified Apple Silicon (arm64) bundle from the latest release, then follow the terminal-only Google setup. Current releases require an Apple Silicon Mac with macOS 13 or later; v0.2.17 was the last release with an Intel build. The bar remains a Linux Omarchy integration.
For manual Linux setup:
- Download the latest release, choosing the complete Linux x86_64 or arm64 bundle and its
SHA256SUMS. - Follow installation to verify the download and put
omagmaon your PATH. Add the Omarchy widget only if you want the bar. - Follow account setup to create your Google OAuth registration, map each account to its Chrome profile, and approve access.
No Zig compiler is needed for a release. Linux bundles include a static musl backend and the Quickshell UI. Mac binaries use system libraries and default to Keychain. Live mail needs Chrome and authorized credentials in the selected credential store; the TUI needs a UTF-8 terminal. Only the Linux bar needs Omarchy/Quickshell. ARM backend builds are tested separately; ARM desktop integration has not been qualified. Mac installation · Linux installation.
AGENTS.md directs agents to the included setup workflow. They can read it directly; installing it as a global skill is optional.
For an existing installation, the Omagma usage skill guides mail, Calendar, drafts, attachment delivery and CLI discovery. See skill registration to make it available to your agent.
The TUI and CLI are experimental. Launch the terminal client with omagma tui. It provides separate accounts, full mail and threads, a reader beside or below the list, Vim keys, mouse navigation, native HTML-to-text display, search, local drafts, replies/forwarding, contacts, custom labels, attachments, mailbox changes and invitation replies. Copy received text by dragging or using Vim visual selection, or open the message in $EDITOR. The editor takes over the terminal and returns to the TUI; compose edits return to the draft, while received-message snapshots are discarded. No tmux is required. Permanent mail deletion and contact deletion remain outside the current scope. CLI/TUI coverage describes their interface differences.
Calendar has Agenda, Day and Week views; Day and Week are a time grid of coloured event blocks sized by their duration, with overlapping events side by side and all-day events in a band above. Combine selected calendars across all three accounts, including read-only subscriptions such as holidays. Colours, visibility and your Priority calendar persist. A chooser lists overlapping events with full times, calendar and account names. See the combined Week capture.
Create a meeting, then review it. Choose a destination calendar, timed or all-day dates and an explicit time zone. Pick guests from that account's Contacts, select Google Meet or paste an existing meeting link, then review before confirming. Google generates a new Meet link after saving. Edit and reschedule organizer-owned events while preserving their guests and conference.
Get a reminder and join in the right profile. While the TUI is open, meeting reminders show minutes until the start, then minutes remaining. Join opens the meeting in its account's configured Chrome profile; Dismiss is deliberate.
Handle invitations from Mail. The invitation card shows the meeting beside the message. Review Accept, Tentative or Decline; supported Accept/Tentative replies also save to Calendar when that account has Calendar write permission. Local Follow-ups and Gmail draft handoff remain available.
Calendar is optional per account. Existing write grants cover the editor and Meet. Read the event guide, Calendar setup and 0.2.10 release notes. Optional encrypted storage uses one unlocked native daemon for the TUI and agent CLI; see vault setup.
The running TUI adopts background cache updates, preserving your reading spot. A New mail card accumulates arrivals per account and clears on interaction. gg jumps to the first cached mail. Long links use compact colored labels with complete destinations available through L; HTML images use text placeholders. During the send countdown, Send now or Ctrl+S submits the reviewed message immediately. 0.2.8 release notes.
T opens the theme picker: choose the orange Omagma palette or Follow
Omarchy, with live preview and a saved preference. Unread subjects, stars and
label names stay visible. Help is searchable with /; dialog buttons support
Tab/Shift+Tab and Enter. See all features and
next priorities.
The v0.2.6 Linux x86_64 TUI settled at approximately 12 MB of RAM with three fictional accounts in its 1,000-cycle workload. Markdown composition settled around 13 MB in a separate lifecycle workload. These are complete Omagma processes, excluding the terminal emulator, editor and separately running bar; larger bodies have separate measurements. Memory details.
Available cached mail appears immediately while Gmail refreshes in the background. The default disk cache keeps the newest 2,000 messages within 256 MiB per account, evicting the oldest tail. The default cache is owner-only plaintext storage, separate from the bar’s memory-only cache. The optional vault encrypts retained data after explicit migration and activation; original source files and explicit exports remain plaintext. / searches the cache, and \ explicitly searches Gmail. An optional five-minute Linux timer keeps the terminal cache ready while the TUI is closed; Mac installation does not add a background service.
omagma cli and omagma agent provide a JSONL interface. One-shot mail, draft, contacts, invitations, calendar, operation and cache commands share that interface’s account-scoped executor. Explicit pagination can fetch more than the bar’s 30 messages. See terminal workflows and keys and the agent CLI contract.
The TUI checks for stable releases every 24 hours and shows an Upgrade
available card with Dismiss and How to update. The guide follows the
actual Omarchy/Homebrew/manual installation and can hand the task to an agent.
The CLI shares omagma updates status|check|guide|dismiss; checks need no Google
authorization. Update controls and procedures.
Existing bar credentials allow read-only mail access. Sending, mailbox changes and contacts need terminal authorization. A terminal-only installation can start with one Google OAuth registration; if you already use the bar, keep its read-only registration and use a different one for the terminal. Choose your permissions and authorize each account separately.
Forward files, choose verified sending identities, recover drafts automatically, and search downloaded bodies. Folded threads, link and attachment pickers, bulk changes with undo, continuous cached-mail navigation, and saved working context keep daily mail work compact. See the feature catalogue for the complete overview.
Ctrl+P or :actions opens the action palette. Find within a message with
:find TEXT, move through cached unread mail, and reuse account-specific search
history or named searches. Labels have checked/mixed states and an explicit
Apply step; the label manager also sets colors. :scope message|thread makes
conversation triage deliberate and reviews its exact targets.
Compose offers Ctrl+Z/Y text undo/redo, a verified From chooser and named
recipient completion. :preview-browser opens a private, isolated outgoing
preview with scripts and remote fetches blocked. Select several files in one
visit, stream received files to new private destinations, or use Save All.
Ordinary outgoing files have a 25 MiB combined limit; the MIME upload limit is
35 MiB. Contacts preserve multiple addresses, and sender-to-contact, local
draft discard and Spam/Not spam are available from the TUI.
Markdown composition includes a rendered outgoing
preview, readable plain-text alternative and retained reply/forward context.
New TUI compositions use Markdown; Ctrl+T switches to Plain without changing
source, and normal-mode p selects preview/original/plain. Existing drafts keep
their format. The CLI opts in with --format markdown and can inspect both
alternatives through draft preview. Explicit send review starts a cancellable
ten-second countdown; Ctrl+Z, Enter or the Undo button cancels before submission.
:send-grace 0..30 changes that delay. A restarted pending send stays paused
until :resume-send; uncertain submissions are protected from automatic retry.
Compose workflow ·
Markdown CLI.
An optional -Dbrowser=true source build runs the same TUI controller in
WebAssembly. omagma server serves its embedded page, prints a private local
URL and chooses the next free port when needed. Connect uses existing configured
accounts; a private one-file credential export also supports static hosting.
The browser supports reading, contacts, completion, cached search and reviewed
plain/Markdown composition, reply/reply-all and forwarding, including retained
original HTML/resources and exact .eml forwarding within its quotas. Mailbox
actions use the shared review and undo rules. Drafts survive reload/disconnect
with verified account recovery; contact editing and local-file adding remain
unavailable. Build and try the browser
· Supported workflows and limits
· Shared controller and platform adapters.
Ordinary native builds keep their existing dependency selection.
To explore without Google credentials, use the optional fictional-mail demo:
omagma tui --fixtures
omagma mail list --fixtures --account personal@example.com --limit 100
omagma cli --fixturesFixture mode never contacts Google. It is optional and is not part of normal installation.
The compact bar dropdown shows each account’s unread count, sender, subject, time and message snippet. It keeps up to 30 recent Inbox messages per account in memory, with optional five-minute background refresh. The bar is read-only and does not save mail to disk.
Click the magma icon, choose an account, and select a message to preview its snippet. Activate a message or choose Open inbox to open the matching Gmail page in that account’s Chrome profile. Open TUI opens that account in a floating terminal. Refresh updates the selected account. Accounts have separate lists and counts; there is no combined Inbox.
Set refreshIntervalSeconds to 300 in your private account configuration to refresh every five minutes, including while the dropdown is closed. It defaults to 0, which disables scheduled refresh. Dropdown keys and states · Background refresh.
Omagma started because one Gmail tab was using roughly 2 GB of RAM on the author’s desktop. On 2026-10-05, Omagma’s backend and attributed UI share measured approximately 31 MB for three connected accounts in v0.2.2 on Linux x86_64. Chrome and unrelated shell widgets are excluded. These are approximate observations, not a controlled browser benchmark. Memory details.
- Documentation index and feature catalogue
- Install on Linux or macOS, connect accounts, and agent-assisted setup
- Bar behavior, terminal guide, and agent CLI
- Terminal cache and background terminal fetching
- Privacy and credentials and memory measurements
- Development and source builds, architecture and transport, and release publishing
- Public screenshots and social assets: Combined Calendar Week · Meeting review · Reminder with Join · Invitation in Mail · Gmail + Calendar social preview
Omarchy may still ship Zig 0.16.x. Source builds require Zig 0.17.0 exactly: download the archive matching your OS/CPU from the official 0.17.0 directory, select its extracted directory on PATH, and confirm zig version prints 0.17.0. Keep the system compiler unchanged. Build commands and developer checks are in development.
MIT licensed. Copyright technologylab.ai. Release distributions include third-party notices, including Zig, musl, libvaxis, zigimg and uucode.





