Agent-assisted setup#

Give your agent a public URL: this website or the GitHub repository. The agent fetches the setup instructions, downloads and verifies the matching release, and prepares local files while guiding you through Google Console and consent one step at a time. You provide feedback after each Google step and approve access in your browser. No checkout or folder preparation is needed before asking the agent to install Omagma.

The root AGENTS.md directs installation/onboarding requests to skills/omagma-setup/SKILL.md. The agent can follow that workflow directly; installing it as a global skill is optional.

Add your account addresses, existing Chrome profile directories, and whether you want five-minute background refresh. Provide a downloaded Google OAuth registration JSON's local path when available; do not paste its contents or account tokens into chat. The agent can prepare and validate local configuration while you approve Google consent in Chrome.

The preferred installation needs no Zig compiler. On Mac, use brew install renerocksai/tap/omagma; the Mac guide also covers verified Apple Silicon/Intel bundles. Linux x86_64 and arm64 bundles include the static musl backend and bar UI. Only the Linux bar requires Omarchy/Quickshell. Live authorization uses Chrome; the default credential store needs an unlocked platform keyring. ARM backend build/test checks do not establish ARM desktop integration.

If no compatible release asset exists, use a source checkout with exact Zig 0.17.0. Omarchy may still ship 0.16.x: download the verified 0.17.0 archive matching the host OS/CPU from the versioned release directory, extract it, prepend its directory to the task's PATH, and confirm zig version. Keep the system compiler unchanged, follow the source-build instructions using safe, and verify the resulting binary's version.

Mac setup choice#

Starting from the public URL is enough. On a new Mac setup, the agent asks which variant you want before connecting accounts:

• Interactive (default): native Keychain, for the TUI/CLI in a local unlocked terminal.
• Agent-enabled: the same TUI/CLI binary, with private owner-only, unencrypted token files, avoiding Keychain audit-session restrictions for agent subprocesses.

An existing explicit choice persists during repairs; the agent does not ask again or silently change it. File credentials still require your agent sandbox to allow the selected config, grants, cache and credential files and Google network access. This choice does not grant those permissions automatically. See Mac setup and migration for credentialStore, credentialDirectory and the credential commands.

For fresh Agent-enabled setup, configure the file store before consent. For existing grants, run migration from a context that can access the source, normally a local unlocked Mac terminal. Migration verifies private copies before switching the config, retains the source copies and needs no new Google sign-in. Restart open sessions after switching. The agent then verifies live account/mail/contact reads through CLI subprocesses in its actual execution context; a working interactive TUI alone is insufficient.

Optional setup skill#

The repository, complete bundle and Homebrew package include omagma-setup. An agent can read it directly. The package supplies the skill but does not automatically register it with your agents.

For a Homebrew installation, make it discoverable in Codex with:

omagma_skill="$(brew --prefix)/opt/omagma/share/doc/omagma/skills/omagma-setup"
mkdir -p ~/.codex/skills
ln -s "$omagma_skill" ~/.codex/skills/omagma-setup

The opt/omagma link follows Homebrew upgrades. Claude Code can use the same target at ~/.claude/skills/omagma-setup; agents using the shared skills directory can use ~/.agents/skills/omagma-setup. Inspect an existing omagma-setup directory or link before changing it.

For an extracted release bundle or source checkout, use its persistent path:

mkdir -p ~/.codex/skills
ln -s /absolute/path/to/omagma/skills/omagma-setup ~/.codex/skills/omagma-setup

Restart your agent session after installation and ask it to use $omagma-setup. Other agents that support SKILL.md can use the same instructions. The skill stays alongside the included project docs. It does not grant permission to modify unrelated desktop settings or bypass Google consent.

Source builds use the compiler pin declared in build.zig.zon; complete release bundles need no compiler.

Terminal client and agents#

For omagma tui, the JSONL agent client, cached full mail, drafts and scoped write setup, read account permissions, TERMINAL.md and AGENT-CLI.md. Full access uses gmail.modify and contacts with per-account terminal consent. A fresh terminal-only installation needs one registration; if the bar already works, use a different registration and preserve its read-only grant. Existing bar credentials remain read-only. Install and authorize the requested interfaces; sending mail or changing contacts requires the user's separate request or explicit interaction.

For a fresh Mac/Linux terminal installation, or full access alongside an existing bar, use: