OMGA CLI

A polished, keyboard-first AI coding assistant for your terminal.
Fast · Minimal · Beautiful · Developer-focused

---

What is OMGA?

OMGA is an AI coding assistant that lives inside your terminal. It reads, writes and searches your codebase, runs commands, inspects Git state, explains code, fixes bugs and implements features — all with a clean, modern, fully keyboard-driven interface.

◆ OMGA

Highlights

🧠 Agentic coding	Reads, writes, searches and runs in your project
🔌 Multi-provider	OpenRouter, OmniRouter and 9Router behind one interface
🎨 Themes	Dark, Light, Dracula, Nord, Minimal — a central token system
🟥🟩 Real diffs	Added lines in green, removed in red, before applying
⌨️ Keyboard-first	Arrow keys, Enter, Escape, search filtering, Ctrl+C
🪄 First-run wizard	Provider → API key → model → theme in one guided flow
🔒 Secure keys	Keys are never logged, printed or committed (chmod 600)
🩺 Doctor	One command to diagnose config, keys, network, terminal
⚡ Fast	Lazy module loading, streaming, no startup bloat

---

Installation

Requires Python 3.10+.

pip install omga-cli

That's it. The omga command is now available.

---

First launch

Run:

omga

On the very first run OMGA detects that no configuration exists and launches an interactive setup wizard automatically:

Welcome to OMGA.

Let's configure your AI provider.

The wizard walks you through, in order:

1. Provider — choose OpenRouter, OmniRouter or 9Router
2. API key — enter your key (input is hidden, never echoed or logged)
3. Model — pick from the live model list (with search), or type one manually
4. Theme — choose the terminal theme you prefer

When the wizard finishes you drop straight into the coding assistant. No config files to edit by hand.

---

Usage

Interactive coding assistant

omga

You are greeted with a session header showing the working directory, model and provider, then a prompt:

What would you like me to do?
❯ write a fastapi endpoint for user auth

OMGA will inspect your project, make changes, and show you a red/green diff before applying it — you approve each significant change.

Type exit / quit or press Ctrl+C twice to leave.

Commands

omga                 Launch the interactive coding assistant
omga init            Run (or re-run) the setup wizard
omga config          Show current configuration
omga config provider Change the AI provider
omga config model    Change the default model
omga config key      Update the API key for the active provider
omga config theme    Change the theme
omga config reset    Reset configuration to defaults
omga doctor          Run diagnostics
omga version         Show version
omga help            Show help

---

Configuration

Configuration lives under an OS-appropriate directory:

Path	Content
~/.config/omga/config.json	user configuration (no secrets)
~/.config/omga/secrets.json	API keys only, mode-restricted (chmod 600)
~/.config/omga/history.txt	shell history
~/.config/omga/logs/omga.log	diagnostic logs (secrets redacted)

API keys are stored separately from configuration and never appear in config.json. Precedence for any value:

CLI arguments  →  environment variables  →  user config  →  defaults

Environment variables

Variable	Purpose
OMGA_API_KEY	Generic API key (any provider)
OMGA_OPENROUTER_API_KEY	API key for the OpenRouter provider
OMGA_OMNIROUTER_API_KEY	API key for the OmniRouter provider
OMGA_9ROUTER_API_KEY	API key for the 9Router provider
OMGA_<PROVIDER>_BASE_URL	Override a provider's base URL
OMGA_THEME	Force a theme (e.g. light)
OMGA_DEBUG=1	Enable debug logging

---

Providers

OMGA routes to multiple provider services through a single AIProvider interface. Each provider implements the same contract:

interface AIProvider:
    id, name, base_url
    validate_credentials() -> bool
    list_models() -> list[Model]
    chat(messages, **kwargs) -> AsyncIterable[ChatEvent]

Providers are selected during setup (omga init) or with omga config provider.

Note on OmniRouter and 9Router: these are OpenAI-compatible AI gateways. Their exact public endpoints were not reachable from the environment used to build OMGA, so their default base URLs are best-effort placeholders. If yours differs, set the corresponding OMGA_OMNIROUTER_BASE_URL / OMGA_9ROUTER_BASE_URL environment variable.

---

Themes

Themes are a central token system — the UI never hard-codes a colour, it references semantic tokens (added, removed, error, success, muted, ...).

Built-in themes: Dark, Light, Dracula, Nord, Minimal.

Change anytime with omga config theme or omga init.

---

Security

• API keys are stored in a mode-restricted file (chmod 600) and are never printed, logged, echoed, or committed.
• The logger redacts secret-looking values defensively.
• Shell commands the agent proposes go through a safety layer: rm -rf / and other filesystem-rooting commands are hard-blocked; git reset --hard, git clean, rm, mv, destructive shell commands require explicit approval.
• File edits are shown as a diff and require approval before being applied.
• Path-traversal outside the project root is rejected.
• OMGA never commits to Git automatically.

A note about the old codebase

An earlier version of this project accidentally contained a hard-coded OpenRouter API key in core/config.py. It was purged in the rewrite. If you ever used that key, treat it as compromised and rotate it. Anyone who clones the old history can read it.

---

Development

git clone https://github.com/isPoori/omga-cli
cd omga-cli
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,test]"

omga --version            # run the CLI from source
pytest                    # run the test suite
python -m build           # build sdist + wheel

Project layout

omga/
├── cli/            command wiring, entry point
├── config/         configuration store + secrets
├── providers/      AIProvider protocol + OpenRouter/OmniRouter/9Router
├── tools/          filesystem, search, shell, git, safety layer
├── agent/          the coding agent loop + hooks + REPL interface
├── ui/             theme tokens, menus, rendering, console facade
├── project.py      project discovery
├── wizard.py       first-run setup wizard
├── doctor.py       `omga doctor` diagnostics
└── paths.py        OS-appropriate state locations

Testing

pytest

Coverage includes configuration precedence & secret isolation, theme token completeness, command-safety rules, diff rendering, provider streaming (mocked), the agent loop (fake provider), path-traversal rejection, and CLI wiring. No test requires a real API key — external calls are mocked.

Contributing

Contributions, bug reports and feature requests are welcome. Please open an issue or pull request on the repository. Follow the existing structure and add tests for new behaviour.

License

MIT © Pouria Hosseini