Batteries-included workflow layer for Gemini CLI. Zero learning curve, maximum power.

Inspired by oh-my-claudecode, reimagined for the Gemini ecosystem with deterministic workflow enforcement.

AI agents in large codebases face two problems: they don't follow rules reliably, and they lose context across sessions. oh-my-gemini solves both — hook-based enforcement makes behavior deterministic, and Conductor gives agents persistent, structured context so they know what to build, how to build it, and where they left off.

Step 1: Install

gemini extensions install https://github.com/richardcb/oh-my-gemini

Step 2: Set Up Your Project

/omg:setup

Step 3: Build Something

/omg:autopilot build a dashboard that shows how much mass I've gained since I started coding with AI

oh-my-gemini uses Gemini CLI's hook system for deterministic behavior:

Agents working on large codebases need more than instructions — they need project knowledge. Research on codified context infrastructure shows that structured context files are associated with 29% faster agent runtime and 17% fewer tokens. Conductor implements this pattern as a three-layer context system:

The before-agent hook automatically injects the active track's context into every prompt. The phase-gate hook parses plan.md after each response, tracking task completion and advising the agent on current phase progress. No manual context management needed.

/omg:setup              # Initialize project (includes Conductor option)
/omg:track "feature"    # Start a new feature track
/omg:plan               # Plan with native plan mode
/omg:implement          # Execute the plan
/omg:review             # Review your changes
/omg:status             # Check progress

Workflow: PRD → Technical Plan → Implementation → Review

Never give up until the task is complete:

ralph: fix all TypeScript errors in this project

The ralph-retry hook automatically:

• Reads verification state from after-tool.js to validate success claims
• Denies premature "success" when typecheck/lint is actually failing
• Tracks error signatures — detects when the agent is stuck on the same error
• Generates error-aware retry messages with actual error details
• Forces retries (up to configurable max), then escalates to user
• Suggests the ralph-mode skill for structured persistence guidance

Track-aware memory captures key observations at phase and verification boundaries, then exposes query tools via the omg-memory server:

• omg_memory_search for compact indexed retrieval
• omg_memory_get for full observation hydration
• omg_memory_timeline for chronological context
• omg_memory_drift for checksum + git-based drift checks
• omg_memory_status for quick track summaries

Manual commands:

• /omg:remember
• /omg:memory-status
• /omg:memory-prune

Prefix your prompts with keywords for deterministic mode selection (< 1ms, no LLM call):

No keyword = implement mode. Prompts without keywords default to full tool access. See docs/MODES.md for details.

Customize hook behavior via .gemini/omg-config.json:

{
  "phaseGates": {
    "enabled": true
  },
  "autoVerification": {
    "enabled": true,
    "typecheck": true,
    "lint": true
  },
  "security": {
    "gitCheckpoints": true
  },
  "ralph": {
    "enabled": true,
    "maxRetries": 5,
    "stuckThreshold": 3
  },
  "modes": {
    "enabled": true,
    "default": "implement"
  }
}

See docs/HOOKS.md for full configuration reference.

oh-my-gemini/
├── gemini-extension.json    # Extension manifest
├── commands/omg/            # Slash commands
├── .gemini/agents/          # Agent definitions (SubAgent format)
├── skills/                  # Skill definitions
│   ├── ralph-mode/          # Persistence mode skill
│   ├── research-methodology/# Research mode skill
│   ├── code-review/         # Review mode skill
│   └── ...
├── src/lib/                 # TypeScript source modules
│   ├── keyword-registry.ts  # Magic keyword detection
│   ├── mode-state.ts        # Mode state persistence
│   ├── mode-config.ts       # Mode profile definitions
│   └── mode-types.ts        # Shared type definitions
├── dist/lib/                # Compiled JS (built via esbuild)
├── hooks/                   # Hook scripts
│   ├── hooks.json           # Hook definitions (documentation-only)
│   ├── lib/                 # Shared utilities
│   ├── session-start.js
│   ├── before-agent.js
│   ├── tool-filter.js
│   ├── before-tool.js
│   ├── after-tool.js
│   ├── phase-gate.js
│   └── ralph-retry.js
├── policies/                # TOML policy files
├── conductor/templates/     # Conductor workflow templates
├── mcp/                     # MCP server configurations
├── templates/               # Project templates
├── docs/                    # Documentation
└── examples/                # Real-world examples

• Gemini CLI v0.31.0+
• Google AI API key or Vertex AI credentials
• Node.js (for hook execution; Node versions with built-in node:sqlite are recommended for memory features)
• If your Node runtime lacks node:sqlite, install better-sqlite3 to enable memory fallback

• Getting Started
• Mode System
• Hooks Reference
• Memory System
• Conductor Workflow
• Contributing

• v0.x: Core hooks infrastructure + agent simplification
• v1.0: Skills, policies, plan mode integration, v0.30.0 alignment
• v1.1: Mode system, keyword registry, enhanced Ralph v2
• v2.0: Multi-agent orchestration (when subagents stabilize)

See CONTRIBUTING.md for development setup.

MIT

• oh-my-claudecode - Original inspiration
• Gemini CLI - Hook system that makes OMG possible
• "Codified Context" - Research validating the structured context approach

Hook-enforced workflows. Codified context. OMG.