{
  "markdown": "# oh-my-gemini\r\n\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)\r\n\r\n**Batteries-included workflow layer for Gemini CLI. Zero learning curve, maximum power.**\r\n\r\n*Inspired by [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode), reimagined for the Gemini ecosystem with deterministic workflow enforcement.*\r\n\r\n---\r\n\r\n## Why oh-my-gemini?\r\n\r\nAI 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.\r\n\r\n| Feature | Without OMG | With OMG |\r\n|---------|-------------|----------|\r\n| Tool sandboxing | \"Don't use write tools\" | `tool-filter` hook blocks them |\r\n| Security gates | \"Avoid dangerous commands\" | `before-tool` hook + policy engine reject them |\r\n| Auto-verification | \"Remember to typecheck\" | `after-tool` hook runs it |\r\n| Phase gates | \"Wait for confirmation\" | `phase-gate` hook advises you |\r\n| Context management | \"Here's our project...\" (every session) | Conductor persists specs, plans, and project knowledge |\r\n| Cross-session memory | Manual recap every session | Conductor memory + on-demand retrieval (`omg_memory_*`) |\r\n| Persistence | Manual retry prompts | `ralph-retry` hook forces retries |\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n**Step 1: Install**\r\n\r\n```bash\r\ngemini extensions install https://github.com/richardcb/oh-my-gemini\r\n```\r\n\r\n**Step 2: Set Up Your Project**\r\n\r\n```\r\n/omg:setup\r\n```\r\n\r\n**Step 3: Build Something**\r\n\r\n```\r\n/omg:autopilot build a dashboard that shows how much mass I've gained since I started coding with AI\r\n```\r\n\r\n---\r\n\r\n## Core Features\r\n\r\n### 🪝 Hook-Enforced Workflows\r\n\r\noh-my-gemini uses Gemini CLI's hook system for deterministic behavior:\r\n\r\n| Hook | Event | What It Does |\r\n|------|-------|--------------|\r\n| `session-start` | SessionStart | Loads Conductor state, shows project status |\r\n| `before-agent` | BeforeAgent | Injects context (git history, current task) |\r\n| `tool-filter` | BeforeToolSelection | Sandboxes tools by agent mode |\r\n| `before-tool` | BeforeTool | Security gates, git checkpoints |\r\n| `after-tool` | AfterTool | Auto-verification (typecheck, lint) |\r\n| `phase-gate` | AfterAgent | Conductor phase enforcement |\r\n| `ralph-retry` | AfterAgent | Persistence mode retry logic |\r\n\r\n### 🤖 Specialized Agents\r\n\r\n| Agent | Purpose | Tool Access |\r\n|-------|---------|-------------|\r\n| **Orchestrator** | Task coordination and routing | Full |\r\n| **Researcher** | Web search, documentation lookup | Read + Web (enforced by hook) |\r\n| **Architect** | System design, debugging | Read only (enforced by hook) |\r\n| **Executor** | Code implementation | Full (with security gates) |\r\n\r\n### 📋 Conductor — Codified Context\r\n\r\nAgents 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](https://arxiv.org/abs/2602.20478). Conductor implements this pattern as a three-layer context system:\r\n\r\n| Layer | Contents | Purpose |\r\n|-------|----------|---------|\r\n| **Project knowledge** | `product.md`, `tech-stack.md`, `workflow.md` | Persistent conventions, stack decisions, and process — loaded every session |\r\n| **Feature specs** | Per-track `spec.md` with requirements, UX flows, invariants | What to build, scoped to a single feature |\r\n| **Phased plans** | Per-track `plan.md` with task checklists and verification gates | How to build it, with hook-enforced phase progression |\r\n\r\nThe `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.\r\n\r\n```bash\r\n/omg:setup              # Initialize project (includes Conductor option)\r\n/omg:track \"feature\"    # Start a new feature track\r\n/omg:plan               # Plan with native plan mode\r\n/omg:implement          # Execute the plan\r\n/omg:review             # Review your changes\r\n/omg:status             # Check progress\r\n```\r\n\r\n**Workflow:** PRD → Technical Plan → Implementation → Review\r\n\r\n### 🔄 Persistence Mode (Ralph)\r\n\r\nNever give up until the task is complete:\r\n\r\n```\r\nralph: fix all TypeScript errors in this project\r\n```\r\n\r\nThe `ralph-retry` hook automatically:\r\n- Reads verification state from `after-tool.js` to validate success claims\r\n- Denies premature \"success\" when typecheck/lint is actually failing\r\n- Tracks error signatures — detects when the agent is stuck on the same error\r\n- Generates error-aware retry messages with actual error details\r\n- Forces retries (up to configurable max), then escalates to user\r\n- Suggests the `ralph-mode` skill for structured persistence guidance\r\n\r\n### 🧠 Conductor Memory (v2.0)\r\n\r\nTrack-aware memory captures key observations at phase and verification boundaries, then exposes query tools via the `omg-memory` server:\r\n\r\n- `omg_memory_search` for compact indexed retrieval\r\n- `omg_memory_get` for full observation hydration\r\n- `omg_memory_timeline` for chronological context\r\n- `omg_memory_drift` for checksum + git-based drift checks\r\n- `omg_memory_status` for quick track summaries\r\n\r\nManual commands:\r\n\r\n- `/omg:remember`\r\n- `/omg:memory-status`\r\n- `/omg:memory-prune`\r\n\r\n---\r\n\r\n## Commands\r\n\r\n| Command | Description |\r\n|---------|-------------|\r\n| `/omg:setup` | Initialize oh-my-gemini in your project |\r\n| `/omg:status` | Show current orchestration state |\r\n| `/omg:plan` | Activate plan mode with OMG context |\r\n| `/omg:autopilot` | Autonomous task execution |\r\n| `/omg:review` | Trigger structured code review |\r\n| `/omg:track` | Start a new feature track |\r\n| `/omg:implement` | Execute the current plan |\r\n| `/omg:remember` | Record a manual decision to memory |\r\n| `/omg:memory-status` | Show memory health for current track |\r\n| `/omg:memory-prune` | Prune older memory observations |\r\n\r\n---\r\n\r\n## Magic Keywords\r\n\r\nPrefix your prompts with keywords for deterministic mode selection (< 1ms, no LLM call):\r\n\r\n| Keyword | Mode | Type | Effect |\r\n|---------|------|------|--------|\r\n| `research:`, `@researcher` | research | Primary | Research mode (read + web tools) |\r\n| `review:`, `@architect` | review | Primary | Review mode (read-only tools) |\r\n| `implement:`, `build:`, `@executor` | implement | Primary | Implement mode (full tools) |\r\n| `quickfix:`, `qf:` | quickfix | Primary | Quick fix mode (full tools) |\r\n| `plan:`, `design:` | plan | Primary | Plan mode (read + web tools) |\r\n| `eco:`, `eco ` | eco | Modifier | Eco modifier (defaults to implement if no primary) |\r\n| `ralph:`, `persistent:`, `@ralph` | N/A | Ralph | Suggests persistence skill |\r\n| `don't give up`, `keep trying` | N/A | Ralph | Suggests persistence skill |\r\n\r\n**No keyword = implement mode.** Prompts without keywords default to full tool access. See [docs/MODES.md](docs/MODES.md) for details.\r\n\r\n---\r\n\r\n## Configuration\r\n\r\nCustomize hook behavior via `.gemini/omg-config.json`:\r\n\r\n```json\r\n{\r\n  \"phaseGates\": {\r\n    \"enabled\": true\r\n  },\r\n  \"autoVerification\": {\r\n    \"enabled\": true,\r\n    \"typecheck\": true,\r\n    \"lint\": true\r\n  },\r\n  \"security\": {\r\n    \"gitCheckpoints\": true\r\n  },\r\n  \"ralph\": {\r\n    \"enabled\": true,\r\n    \"maxRetries\": 5,\r\n    \"stuckThreshold\": 3\r\n  },\r\n  \"modes\": {\r\n    \"enabled\": true,\r\n    \"default\": \"implement\"\r\n  }\r\n}\r\n```\r\n\r\nSee [docs/HOOKS.md](docs/HOOKS.md) for full configuration reference.\r\n\r\n---\r\n\r\n## Project Structure\r\n\r\n```\r\noh-my-gemini/\r\n├── gemini-extension.json    # Extension manifest\r\n├── commands/omg/            # Slash commands\r\n├── .gemini/agents/          # Agent definitions (SubAgent format)\r\n├── skills/                  # Skill definitions\r\n│   ├── ralph-mode/          # Persistence mode skill\r\n│   ├── research-methodology/# Research mode skill\r\n│   ├── code-review/         # Review mode skill\r\n│   └── ...\r\n├── src/lib/                 # TypeScript source modules\r\n│   ├── keyword-registry.ts  # Magic keyword detection\r\n│   ├── mode-state.ts        # Mode state persistence\r\n│   ├── mode-config.ts       # Mode profile definitions\r\n│   └── mode-types.ts        # Shared type definitions\r\n├── dist/lib/                # Compiled JS (built via esbuild)\r\n├── hooks/                   # Hook scripts\r\n│   ├── hooks.json           # Hook definitions (documentation-only)\r\n│   ├── lib/                 # Shared utilities\r\n│   ├── session-start.js\r\n│   ├── before-agent.js\r\n│   ├── tool-filter.js\r\n│   ├── before-tool.js\r\n│   ├── after-tool.js\r\n│   ├── phase-gate.js\r\n│   └── ralph-retry.js\r\n├── policies/                # TOML policy files\r\n├── conductor/templates/     # Conductor workflow templates\r\n├── mcp/                     # MCP server configurations\r\n├── templates/               # Project templates\r\n├── docs/                    # Documentation\r\n└── examples/                # Real-world examples\r\n```\r\n\r\n---\r\n\r\n## Requirements\r\n\r\n- [Gemini CLI](https://geminicli.com) v0.31.0+\r\n- Google AI API key or Vertex AI credentials\r\n- Node.js (for hook execution; Node versions with built-in `node:sqlite` are recommended for memory features)\r\n- If your Node runtime lacks `node:sqlite`, install `better-sqlite3` to enable memory fallback\r\n\r\n---\r\n\r\n## Documentation\r\n\r\n- [Getting Started](docs/getting-started.md)\r\n- [Mode System](docs/MODES.md)\r\n- [Hooks Reference](docs/HOOKS.md)\r\n- [Memory System](docs/MEMORY.md)\r\n- [Conductor Workflow](conductor/README.md)\r\n- [Contributing](CONTRIBUTING.md)\r\n\r\n---\r\n\r\n## Roadmap\r\n\r\n- [x] v0.x: Core hooks infrastructure + agent simplification\r\n- [x] v1.0: Skills, policies, plan mode integration, v0.30.0 alignment\r\n- [x] v1.1: Mode system, keyword registry, enhanced Ralph v2\r\n- [ ] v2.0: Multi-agent orchestration (when subagents stabilize)\r\n\r\n---\r\n\r\n## Contributing\r\n\r\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup.\r\n\r\n---\r\n\r\n## License\r\n\r\nMIT\r\n\r\n---\r\n\r\n## Acknowledgments\r\n\r\n- [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) - Original inspiration\r\n- [Gemini CLI](https://geminicli.com) - Hook system that makes OMG possible\r\n- [\"Codified Context\"](https://arxiv.org/abs/2602.20478) - Research validating the structured context approach\r\n\r\n---\r\n\r\n**Hook-enforced workflows. Codified context. OMG.**\r\n",
  "bytes": 10533,
  "sha": "8c61af58bc921f40c8da81433cfc2e43d8528f3494e8f901436d1e372764712b",
  "repo_slug": "richardcb/oh-my-gemini",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_richardcb_oh_my_gemini_569f32eb/readme"
}