🌀 OBLIVION AI
The Open-Source Terminal AI Coding Agent — Voice-Native, Self-Hosted, Zero Lock-In
A privacy-first, zero-cost alternative to Cursor, GitHub Copilot, and Claude Code — running entirely in your terminal.
"Code is conversation. Make it natural." — M.E.E.R.A.
Quick Start • Why Oblivion • Architecture • Comparison • MCP Integration • Roadmap
🧭 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
| 🤖 M.E.E.R.A. Core | A ReAct-loop reasoning engine, not a single-shot autocomplete — plans, calls tools, observes results, and iterates. |
| ⚡ 13-Model Fallback Chain | Auto-cascades across Ollama Cloud, Gemini, Groq, OpenRouter and more with smart rate-limit cooldowns, so you rarely hit a dead end. |
| 🎙️ Real Voice I/O | Wake-word activation ("Hey Jarvis"), silence-based auto-stop, and 8 neural voice personas via Edge-TTS / ElevenLabs. |
| 🔍 3-Layer Hybrid Search | Exact symbol lookup (SQLite FTS5) + full-text search + vector semantic embeddings (ChromaDB) with AST-aware chunking. |
| 🔌 Built-in MCP Server | Exposes 10 read-only code-intelligence tools directly to Claude Desktop, Cursor, and Zed — Oblivion augments your other tools too. |
| 🛡️ 3-Tier Safety System | Read / Mutate / Destructive action tiers, with unified diff previews before anything touches disk. |
| 🧰 38 Agent Tools | Full Git suite, test runners, atomic multi-file batch_edit, web search, PyPI/npm lookups, background server management. |
| 📚 14 Domain Knowledge Packs | Auto-detected, context-aware packs (React, Next.js, Django, Security, and more), capped at 2 per request to stay lean. |
| 💻 Runs on Modest Hardware | Developed and validated end-to-end on a 13GB RAM laptop with no GPU. |
| 📟 Bonus: Intel 8085 Emulator | A full microprocessor simulator and assembler, tucked inside the same TUI. |
🆚 Oblivion vs. The Rest
| Capability | Oblivion AI | Cursor | GitHub Copilot | Claude Code |
|---|---|---|---|---|
| Open source | ✅ MIT | ❌ | ❌ | ❌ |
| Cost to run | Free (local/free-tier LLMs) | Subscription | Subscription | Usage-based |
| Runs fully in terminal | ✅ | ❌ (IDE fork) | ❌ (IDE plugin) | ✅ |
| Multi-model fallback chain | ✅ 13 backends | ❌ single provider | ❌ single provider | ❌ single provider |
| Local-model support | ✅ Ollama | ❌ | ❌ | ❌ |
| Native voice I/O | ✅ wake-word + TTS/STT | ❌ | ❌ | ❌ |
| Hybrid symbol + semantic search | ✅ 3-layer (FTS5 + ChromaDB) | Semantic only | Limited | Semantic only |
| Exposes its own MCP server | ✅ 10 tools | ❌ | ❌ | ❌ |
| Tiered write-safety with diff previews | ✅ 3-tier | Partial | ❌ | ✅ |
| Data leaves your machine | Optional (local mode available) | Yes | Yes | Yes |
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
Query: "Where is parse_llm_output defined?"
The same query fans out to all three layers in parallel, then gets merged into one ranked result:
| Layer | Engine | What it catches |
|---|---|---|
| 1 — Symbol | SQLite table | Exact function/class/variable names — always ranked first when matched |
| 2 — Full-text | SQLite FTS5 | Literal text matches anywhere in the codebase |
| 3 — Vector | ChromaDB + MiniLM | Conceptual/semantic matches, even with no shared keywords |
Merge & rank: exact line ranges are deduplicated → symbol hits always win rank #1 → vector context fills in as fallback for anything the first two layers missed.
Reasoning & Execution Loop
- User prompt goes to M.E.E.R.A., which runs a ReAct loop — reason, act, observe, repeat.
- M.E.E.R.A. selects from its 38 tools and routes the request through the 13-model fallback chain (Ollama Cloud → Gemini → Groq → …) for the actual completion.
- Any tool call that touches your code passes through the 3-tier safety gate — Read / Mutate / Destructive.
- Read-tier actions run immediately. Mutate and Destructive actions generate a diff preview first, and only execute (atomically, via
batch_edit) once approved.
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-whisperfor 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:
| Tier | Examples | Confirmation |
|---|---|---|
| Read (22 tools) | File search, symbol lookup, git log, test discovery | None needed |
| Mutate (13 tools) | Multi-file batch_edit, git commit, dependency install |
Diff preview shown |
| Destructive (1 tool) | File/branch deletion | Explicit confirmation required |
🗺️ 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
⭐ If Oblivion saves you a subscription or two, consider starring the repo. ⭐
Metadata
Release files for oblivion-agent 3.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| oblivion_agent-3.5.0.tar.gz | 267.5 kB | Without provenance | Details for oblivion_agent-3.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| oblivion_agent-3.5.0-py3-none-any.whl | Python 3 | none | any | Details for oblivion_agent-3.5.0-py3-none-any.whl |
Total release size: 574.1 kB
Release files / oblivion_agent-3.5.0.tar.gz
| Download URL | oblivion_agent-3.5.0.tar.gz |
|---|---|
| Size | 267.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
232f599c579d9f44f1ecc46f0cba72777d4d73204ff6740c712be9499c0dc66a
|
|
BLAKE2b-256 checksum How to use checksums |
7287ab096a57563813c1c4dab26f3e951b9cdd91458926313b8ee3e81caf35e7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / oblivion_agent-3.5.0-py3-none-any.whl
| Download URL | oblivion_agent-3.5.0-py3-none-any.whl |
|---|---|
| Size | 306.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ec25728e59111f9c01aee886f9183ff369237e9af91cb86ca14016582b5cbc7f
|
|
BLAKE2b-256 checksum How to use checksums |
ee8bad8f7adee4b5c1ce4b7f4d4e5c8b67a11e5f050192816cbc16b7e0650c37
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Security for oblivion-agent 3.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.