🧭 What is Oblivion?

Oblivion AI is a terminal-native, fully open-source AI coding agent built around M.E.E.R.A. (Multi-modal Engineering and Reasoning Assistant) — an autonomous ReAct-style engineering partner that lives in your CLI, understands your codebase semantically, edits multiple files atomically, and talks back with a real voice if you want it to.

It was built on the premise that the best coding agent shouldn't require a subscription, a cloud account, or your code leaving your machine to be genuinely useful. Oblivion runs against free and local LLM backends by default, indexes your repository with a three-layer hybrid search engine, and exposes its own code-intelligence tools to other editors over MCP — so it plays well with the tools you already use instead of competing with them.

⚡ Quick Start

# Basic text-only install
pip install oblivion-agent

# With local Voice STT + Neural TTS support (recommended)
pip install "oblivion-agent[voice]"

# With premium ElevenLabs voice support
pip install "oblivion-agent[all]"

# Launch the Terminal UI
oblivion

# Launch the MCP server (for Claude Desktop / Cursor / Zed)
oblivion mcp

# Open the MCP Inspector in your browser
oblivion inspect

No API keys required to get started — Oblivion's default fallback chain runs on free-tier and local models out of the box.

🌟 Why Oblivion

🆚 Oblivion vs. The Rest

Oblivion doesn't aim to replace every workflow — it aims to be the agent that works the same way whether you have a $0 budget or an enterprise API key, and hands its own code intelligence to whichever other tool you're already using.

🏗️ Architecture

3-Layer Hybrid Search Engine

                    ┌─────────────────────────────────────────┐
                    │               USER QUERY                 │
                    │   "Where is parse_llm_output defined?"    │
                    └────────────────────┬──────────────────────┘
                                          │
                   ┌──────────────────────┼──────────────────────┐
                   │                      │                      │
                   ▼                      ▼                      ▼
        ┌───────────────────┐  ┌────────────────────┐  ┌───────────────────┐
        │  LAYER 1: SYMBOL  │  │  LAYER 2: FTS5 TEXT│  │  LAYER 3: VECTOR   │
        │   SQLite Table    │  │    SQLite FTS5      │  │  ChromaDB + MiniLM │
        │  Exact Names Only │  │  Full-Text Match     │  │  Concept Matcher    │
        └─────────┬─────────┘  └─────────┬───────────┘  └─────────┬──────────┘
                  │                       │                        │
                  └───────────────────────┼────────────────────────┘
                                          │
                                          ▼
                   ┌──────────────────────────────────────────┐
                   │            MERGE & RANK ENGINE             │
                   │  1. Deduplicates exact line ranges         │
                   │  2. Symbol matches ALWAYS win rank #1      │
                   │  3. Merges vector context for fallback     │
                   └──────────────────────────────────────────┘

Reasoning & Execution Loop

 User Prompt ──▶ M.E.E.R.A. (ReAct Loop) ──▶ Tool Selection (38 tools)
                       │                              │
                       │                              ▼
                       │                    ┌─────────────────────┐
                       │                    │  3-Tier Safety Gate  │
                       │                    │  Read / Mutate /     │
                       │                    │  Destructive          │
                       │                    └──────────┬──────────┘
                       │                               │
                       ▼                               ▼
              Model Fallback Chain            Diff Preview + Execute
        (Ollama Cloud → Gemini → Groq → …)     (atomic batch_edit)

Tech stack: Python 3.11+, Textual TUI framework with cyberpunk styling, SQLite (FTS5), ChromaDB, faster-whisper (STT), Edge-TTS / ElevenLabs (TTS), Model Context Protocol (MCP).

Scale (v3.1.0, Aug 2026): ~45 Python files · ~12,000+ lines of code · 4,000+ downloads on PyPI · 38 tools (22 read-tier, 13 mutate-tier, 1 destructive, 1 special) · 6-model smart-cooldown fallback for the default configuration, expandable to 13 supported backends.

🔌 MCP Server Integration

Oblivion isn't just a standalone agent — it also serves its code-intelligence layer to other editors over the Model Context Protocol. Add this to your claude_desktop_config.json to give Claude Desktop, Cursor, or Zed direct access to Oblivion's 3-layer search and symbol index:

{
  "mcpServers": {
    "oblivion": {
      "command": "oblivion",
      "args": ["mcp"],
      "env": {
        "WORKSPACE_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

This exposes 10 read-only tools — symbol lookup, semantic search, file structure inspection, and more — so your existing editor gets Oblivion's understanding of the codebase without needing to run the full agent inside it.

🎙️ Voice-First Workflow

• Wake-word activation: say "Hey Jarvis" to start a session hands-free.
• Silence-based auto-stop: a 3-second pause automatically ends your utterance — no push-to-talk needed.
• 8 neural voice personas via Edge-TTS (free) or ElevenLabs (premium), so M.E.E.R.A. can sound however you want it to.
• Built on faster-whisper for local speech-to-text, keeping voice interaction private by default.

🛡️ Safety Model

Every action Oblivion can take falls into one of three tiers, and nothing in the Mutate or Destructive tiers runs without a unified diff preview first:

🗺️ Roadmap

• Jarvis-style voice personality: barge-in interruption, proactive unprompted commentary, emotion-aware tone adjustment
• Continued expansion of the free-model fallback chain (Kimi K2, GLM-5.2, Qwen3-Coder and beyond)
• Refactor of the TUI dashboard into smaller, more maintainable modules
• Deeper MCP tool surface for third-party editor integrations

📄 License

Distributed under the MIT License — free for personal, academic, and commercial use.

👨‍💻 Creator & Community

Oblivion AI is designed and built by R. Rohith (@Rohith-s-hub), a final-year B.Sc. Computer Science student from Tamil Nadu, India.

• 🌐 Website: oblivion.run.place
• 🐙 GitHub: @Rohith-s-hub
• 💼 LinkedIn: Rohith Rajkumar
• 📦 PyPI: oblivion-agent