OMG (oh-my-gemini)

OMG is a workflow/runtime layer for Gemini CLI.

It aims to make day-to-day Gemini usage feel closer to the operator ergonomics of oh-my-codex / oh-my-claudecode:

• stronger session startup
• mode-driven defaults (smart, madmax, high)
• first-class workflow commands (setup, doctor, deep-interview, plan, ralph, team)
• persistent project state under .omg/
• tmux-backed team execution
• Gemini extension hooks, commands, and starter skills

Repo layout

packages/
  cli/        CLI entrypoint + command surface
  core/       orchestration/state/runtime engine
  extension/  Gemini extension bundle (hooks, commands, skills)

Install from npm

npm install -g @danielsilvaperez/oh-my-gemini
# or:
npx @danielsilvaperez/oh-my-gemini@latest setup

Setup

omg setup

omg setup does the following:

• creates ~/.omg/ and project .omg/ directories
• scaffolds project .gemini/GEMINI.md if missing
• mirrors the packaged extension into ~/.omg/extension
• validates and links the extension into Gemini CLI when gemini is available
• writes a helper script at ~/.omg/link-extension.sh for manual re-linking

Use omg setup --no-link if you want to stage the extension without touching your Gemini CLI config.

After install, you can confirm the packaged CLI version:

omg --version

Verify install

omg doctor
gemini extensions list

If the link is healthy, doctor will report Gemini extension link as passing and gemini extensions list will include oh-my-gemini.

Install from source

npm install
npm run build
node dist/packages/cli/bin/omg.js setup

Doctor

omg doctor

Checks:

• Node.js
• npm
• Gemini CLI
• tmux
• extension assets present
• project/global state writable
• OMG config present
• Gemini extension link health

First run

Normal Gemini session

omg
omg --smart
omg --madmax
omg --madmax --high

Without a task argument, OMG initializes project state and launches Gemini interactively with OMG environment variables so the extension hooks can inject mode-aware context.

One-shot task execution

omg "summarize this repo"
omg --madmax "ship the auth change"
omg --madmax --high "finish the approved implementation"

Behavior:

• smart: lightweight planning for non-trivial tasks, otherwise direct execution
• madmax: plans non-trivial tasks first, then executes autonomously
• high: uses the structured Ralph loop (plan -> execute one step -> verify -> continue)

tmux-backed session launch

omg --tmux --madmax --high

Starts a detached tmux session running Gemini (or Ralph for task-driven high mode) and prints the attach command.

Canonical workflow commands

omg deep-interview "clarify the auth change"
omg deep-interview --non-interactive "clarify the auth change"
omg plan "approve the safest implementation path"
omg ralph "carry the approved plan to completion"
omg team 3:executor "execute the approved plan in parallel"
omg team status <team-id>
omg team resume <team-id>
omg team shutdown <team-id>

Additional utility surfaces in v1:

omg hud --watch
omg explore --prompt "read-only repo question"
omg sparkshell "git status --short"

State layout

Global

~/.omg/
  config.json
  extension/
  logs/
  sessions/
  skills/
  artifacts/

Project

.omg/
  session.json
  mode.json
  plan-current.md
  plan-current.json
  test-spec-current.md
  test-spec-current.json
  project-memory.json
  notepad.md
  context/
  state/
  sessions/
  plans/
  logs/
  team/
  artifacts/
  skills/

Notable durable runtime files:

• .omg/state/*.json — workflow/runtime mode state snapshots
• .omg/logs/trace.jsonl — lightweight runtime trace of session, planning, Ralph, team, and hook events

Ralph loop

omg ralph is a real stepwise loop:

1. Generate a structured plan.
2. Execute one bounded step at a time with Gemini headless mode.
3. Run step verification commands.
4. Persist iteration history to .omg/artifacts/ralph-state.json and .omg/logs/ralph.jsonl.
5. Continue, retry, or stop based on structured execution + verification state.

It does not rely on brittle string matching like “contains complete”.

omg plan now writes both durable implementation planning artifacts and a companion test-spec artifact so Ralph and operators have an explicit verification contract to work from.

Team mode

omg team creates a durable tmux session and state under .omg/team/<team-id>/.

Current v1 behavior:

• worker 1 = primary delivery lane (writable)
• middle workers = support / analysis lanes
• final worker = verification lane
• each worker has config.json, status.json, result.json (on success), a summary/status trail, and a dedicated log file
• status, resume, and shutdown inspect or control the tmux session while preserving durable artifacts on disk

Gemini extension bundle

The packaged extension includes:

• gemini-extension.json
• hooks/hooks.json
• hooks/session-start.mjs, before-agent.mjs, after-agent.mjs, session-end.mjs
• slash commands: /deep-interview, /plan, /ralph, /team
• starter skills: planning, execution, verification, debugging, repo-onboarding

Notes / limitations

• OMG prefers extension/context-based behavior instead of forcing GEMINI_SYSTEM_MD, because Gemini’s system override is a full replacement of built-in firmware.
• Team mode is intentionally lane-based in v1 to avoid unsafe multi-writer conflicts in the same checkout.
• Extension hooks/commands depend on Gemini trusting the workspace and successfully loading the linked extension.

Publishing checklist

Before publishing a release:

npm test
npm run typecheck
npm run build
npm run smoke:pack
npm publish --access public

GitHub Actions automation is included:

• .github/workflows/ci.yml runs test/typecheck/build/pack smoke checks on pushes and PRs
• .github/workflows/publish.yml publishes to npm and creates a GitHub release when you push a v* tag (requires NPM_TOKEN)