🧠 Omni Cortex

The Headless Strategy Engine for AI Coding Agents

Omni Cortex is an MCP server that gives Claude access to 62 advanced reasoning frameworks through Gemini-powered orchestration. Gemini thinks deeply about your problem and generates ultra-efficient execution briefs for Claude.

"Gemini orchestrates. Claude executes. You ship faster."

🏗️ Architecture: Gemini Orchestrates, Claude Executes

User Query → Claude → Gemini (via MCP) → Structured Context → Claude Executes
                          ↓
              1. Analyze intent & extract keywords
              2. Discover relevant files (with scoring)
              3. Search code (grep/ripgrep/git)
              4. Fetch documentation from web
              5. Query ChromaDB knowledge base (16K+ examples)
              6. Structure everything into organized brief

How It Works

1. User asks Claude a question
2. Claude calls Omni-Cortex (MCP tool)
3. Gemini Context Gateway does the heavy lifting:
   • Analyzes query to understand intent
   • Discovers relevant files with relevance scoring
   • Searches codebase via grep/git
   • Fetches web documentation if needed
   • Queries ChromaDB for similar past solutions (16K+ examples)
   • Selects optimal framework chain (62 available)
   • Generates token-efficient execution brief (20% format savings)
4. Claude receives structured context and executes

Key Design

• Gemini burns tokens freely (1M context) - does ALL the heavy thinking
• Claude gets full context with 20% token savings via efficient formatting
• Cost: ~$0.0001 per query (virtually free with Gemini's free tier)

🔮 Vibe-Based Routing

You don't need to ask for "Active Inference" or "Chain of Verification." Just speak naturally:

🔗 Framework Chaining

For complex tasks, Omni chains multiple frameworks together in a pipeline:

Category Router → Specialist Agent → Framework Chain → Pipeline Executor
      ↓                   ↓                  ↓               ↓
  "debug"         Debug Detective      [fw1 → fw2 → fw3]   Execute each
  "code_gen"      Code Architect               ↓           in sequence
  "refactor"      Refactor Surgeon     Pass state between
      ...                              frameworks

Example: Complex Bug Fix

When you say "This async handler crashes randomly under load":

1. Category Match → debug (vibe: "crashes", "randomly")
2. Specialist Decision → Debug Detective selects chain
3. Pipeline Execution:

   self_ask         →  "What exactly are we debugging?"
   active_inference →  Hypothesis testing loop
   verify_and_edit  →  Validate fix, patch only what's wrong
   

📋 ClaudeCodeBrief Format (NEW)

The structured handoff protocol optimizes for Claude Max subscriptions:

[DEBUG] Fix user auth failing after password reset
→ auth/password.py:L45-67 auth/session.py
  • authentication
  ⊘ auth/oauth.py

1. Check reset_password() return value
2. Verify session invalidation after reset
3. Add token refresh call after password change

✓ pytest tests/auth/ -v
• All tests pass
• Auth flow works

⚠ Preserve existing functionality
⚠ Do not break API

• [FILE] auth/password.py:L45
  → returns None instead of new token
• [FILE] auth/session.py:L78
  → does not invalidate old tokens

⛔ If required inputs missing, request them

20% token savings via bullet points, full information preserved.

⚡ Installation

Option 1: Docker Pull

docker pull vzwjustin/omni-cortex:latest

📚 Pre-Seeded Knowledge: The :latest image ships with an embedded knowledge base including:

• LLM Debugging: Prompt engineering, error recovery, hallucination handling
• Reasoning Frameworks: When to use CoT, Tree-of-Thoughts, ReAct, etc.
• Best Practices: Tool calling, memory management, cost optimization
• Curated llms.txt: Anthropic, LangChain, Pydantic, Docker, and more

No setup required - knowledge is pre-loaded in ChromaDB.

Option 2: Add to MCP Config

Add to your IDE's MCP settings (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "omni-cortex": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/path/to/your/code:/code",
        "vzwjustin/omni-cortex:latest"
      ]
    }
  }
}

🧩 Framework Architecture (Modular)

The 62 frameworks are organized into a clean, modular structure:

Single Source of Truth

app/frameworks/
├── __init__.py         # Exposes FRAMEWORKS dict
└── registry.py         # ALL 62 framework definitions (76KB)

Each framework is defined as a FrameworkDefinition dataclass:

FrameworkDefinition(
    name="active_inference",
    display_name="Active Inference",
    category=FrameworkCategory.ITERATIVE,
    description="Debugging loop: hypothesis → predict → compare → update",
    best_for=["debugging", "error analysis", "root cause investigation"],
    vibes=["why is this broken", "wtf is wrong", "find the bug", ...],
    steps=["HYPOTHESIS: Form hypothesis", "PREDICT: Expected behavior", ...],
    complexity="medium",
    task_type="debug",
)

Node Implementations (By Category)

app/nodes/
├── common.py           # Shared logic for all nodes
├── generator.py        # Dynamic prompt generator (uses registry)
│
├── strategy/           # ReasonFlux, Self-Discover, Plan-and-Solve...
├── search/             # Tree of Thoughts, Graph of Thoughts, MCTS...
├── iterative/          # Active Inference, Reflexion, Self-Refine...
├── code/               # Program of Thoughts, Chain of Code, TDD...
├── context/            # Chain of Note, Step-Back, Buffer of Thoughts...
├── fast/               # System1, Scaffolding (quick responses)
├── verification/       # Chain of Verification, Self-Consistency...
├── agent/              # SWE-Agent, ReWOO, LATS...
└── rag/                # HyDE, RAG-Fusion, RAPTOR, GraphRAG...

How It Works

1. User query → HyperRouter matches vibes in registry.py
2. Category identified → Specialist selects framework(s)
3. Framework chain selected → generator.py builds prompts from steps
4. Node executes → Category-specific logic in nodes/{category}/
5. Result returned → Formatted as ClaudeCodeBrief

Why This Structure?

• Single Source of Truth: Add/modify frameworks in ONE file
• Vibe Matching: Natural language → framework selection
• Modular Nodes: Category-specific execution logic
• Prompt Generation: Steps are templates, generator fills in context

Categories

🔧 Recent Changes

v1.0.0 - Initial Release (January 2026)

Production Hardening

• P0/P1 Fixes Complete: All critical code review issues resolved
• 280+ Tests Passing: Comprehensive test coverage for core modules
• Defensive Error Handling: GeminiResponse never throws, graceful degradation
• Dead Code Removed: Consolidated duplicate functions, wired up unused parameters

Code Quality

• Single Registry: All 62 frameworks in app/frameworks/registry.py
• Config Unified: Single source of truth in core/settings.py
• Token-Efficient Briefs: 20% savings via ClaudeCodeBrief.to_surgical_prompt()
• Async-Safe Cache: Thundering herd protection, 90% reduction in duplicate API calls

Architecture

• Gemini Orchestration: Task analysis, context prep, framework selection
• ChromaDB Integration: 16K+ examples for cross-session learning
• Multi-Repo Support: Context discovery across multiple repositories
• Structured Handoff Protocol: GeminiRouterOutput → ClaudeCodeBrief

🧪 Testing

# Run all tests
cd omni_cortex
python -m pytest tests/ -v

# Run smoke tests only
python -m pytest tests/unit/test_refactor_smoke.py -v

📄 License

MIT License. Open source and free to use.

🙏 Contributing

Contributions welcome! Please read the CLAUDE.md for development guidelines.

Built with ❤️ by Justin Adams