# rohith-s-hub/oblivion-agent architecture

> Architecture diagram of the GitHub repository rohith-s-hub/oblivion-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rohith-s-hub/oblivion-agent
- Repository: https://github.com/rohith-s-hub/oblivion-agent

## Overview

Oblivion is a terminal-native AI coding agent: a user submits a prompt through the TUI, M.E.E.R.A. reasons with an LLM, parses tool actions, applies safety controls, and returns an answer or performs code work. Its hybrid code search, voice interaction, MCP server, and 8085 simulator are distinct product capabilities. Several connections below are documented in the README or SOURCE INDEX; unsampled implementation details are not inferred.

Main entry points: [`agent/core.py`](https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/core.py) (M.E.E.R.A. loop), [`tools/registry.py`](https://github.com/rohith-s-hub/oblivion-agent/blob/main/tools/registry.py) (Tool registry), [`ui/app.py`](https://github.com/rohith-s-hub/oblivion-agent/blob/main/ui/app.py) (Terminal UI), [`ui/sim_screen.py`](https://github.com/rohith-s-hub/oblivion-agent/blob/main/ui/sim_screen.py) (8085 simulator UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_tui["Terminal UI<br/>[app.py]"]
  node_sim_screen["8085 simulator UI<br/>[sim_screen.py]"]
end

subgraph group_agent["Agent reasoning"]
  node_agent_core["M.E.E.R.A. loop<br/>[core.py]"]
  node_runtime["Agent runtime<br/>[runtime.py]"]
  node_llm["Model fallback<br/>[llm.py]"]
  node_parser["Response parser<br/>[parser.py]"]
  node_brain["Reasoning prompts<br/>[brain.py]"]
  node_plan_guard["Plan guard<br/>[plan_guard.py]"]
  node_permissions["Action permissions<br/>[permissions.py]"]
  node_knowledge["Knowledge packs<br/>[injector.py]"]
end

subgraph group_work["Coding and search"]
  node_registry["Tool registry<br/>[registry.py]"]
  node_file_tools["Workspace tools<br/>[filesystem.py]"]
  node_diff["Diff previews<br/>[diff.py]"]
  node_batch_edit["Atomic editing<br/>[batch_edit.py]"]
  node_rag["Hybrid search<br/>[rag.py]"]
  node_chunker["AST chunking<br/>[code_chunker.py]"]
  node_symbol_index[("Symbol index<br/>[symbol_index.py]")]
end

subgraph group_integrations["Voice and MCP"]
  node_voice["Voice interaction<br/>[voice.py]"]
  node_wake_word["Wake-word listener<br/>[wake_word.py]"]
  node_mcp_server["MCP tool service<br/>[core.py]"]
  node_mcp_transport["MCP transports"]
end

subgraph group_state["State and simulator"]
  node_session_store[("Session storage<br/>[store.py]")]
  node_assembler["Assembler<br/>[assembler.py]"]
  node_cpu["8085 CPU<br/>[cpu8085.py]"]
end

node_user(("Developer"))
node_editor(("External editor"))
node_llm_services["LLM providers"]

node_user -->|"submits prompt"| node_tui
node_tui -->|"starts agent"| node_agent_core
node_agent_core -->|"requests completion"| node_llm
node_llm -->|"calls models"| node_llm_services
node_agent_core -->|"parses response"| node_parser
node_agent_core -->|"builds reasoning prompt"| node_brain
node_agent_core -->|"dispatches tools"| node_registry
node_agent_core -->|"checks plans"| node_plan_guard
node_runtime -->|"checks action tier"| node_permissions
node_runtime -->|"dispatches tools"| node_registry
node_registry -->|"invokes workspace tools"| node_file_tools
node_registry -->|"invokes batch edits"| node_batch_edit
node_agent_core -->|"previews changes"| node_diff
node_registry -->|"uses code search"| node_rag
node_rag -->|"chunks source"| node_chunker
node_rag -->|"updates symbols"| node_symbol_index
node_agent_core -->|"adds domain context"| node_knowledge
node_tui -->|"stores sessions"| node_session_store
node_tui -->|"starts voice input"| node_voice
node_tui -->|"controls listening"| node_wake_word
node_editor -->|"connects over MCP"| node_mcp_transport
node_mcp_transport -->|"routes requests"| node_mcp_server
node_mcp_server -->|"dispatches tools"| node_registry
node_user -->|"opens simulator"| node_sim_screen
node_sim_screen -->|"assembles programs"| node_assembler
node_sim_screen -->|"runs instructions"| node_cpu

click node_tui "https://github.com/rohith-s-hub/oblivion-agent/blob/main/ui/app.py"
click node_agent_core "https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/core.py"
click node_runtime "https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/runtime.py"
click node_llm "https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/llm.py"
click node_parser "https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/parser.py"
click node_brain "https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/brain.py"
click node_plan_guard "https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/plan_guard.py"
click node_permissions "https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/permissions.py"
click node_registry "https://github.com/rohith-s-hub/oblivion-agent/blob/main/tools/registry.py"
click node_file_tools "https://github.com/rohith-s-hub/oblivion-agent/blob/main/tools/filesystem.py"
click node_diff "https://github.com/rohith-s-hub/oblivion-agent/blob/main/tools/diff.py"
click node_batch_edit "https://github.com/rohith-s-hub/oblivion-agent/blob/main/tools/batch_edit.py"
click node_rag "https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/rag.py"
click node_chunker "https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/code_chunker.py"
click node_symbol_index "https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/symbol_index.py"
click node_knowledge "https://github.com/rohith-s-hub/oblivion-agent/blob/main/knowledge/injector.py"
click node_session_store "https://github.com/rohith-s-hub/oblivion-agent/blob/main/db/store.py"
click node_voice "https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/voice.py"
click node_wake_word "https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/wake_word.py"
click node_mcp_server "https://github.com/rohith-s-hub/oblivion-agent/blob/main/mcp_server/core.py"
click node_mcp_transport "https://github.com/rohith-s-hub/oblivion-agent/tree/main/mcp_server/transports"
click node_sim_screen "https://github.com/rohith-s-hub/oblivion-agent/blob/main/ui/sim_screen.py"
click node_assembler "https://github.com/rohith-s-hub/oblivion-agent/blob/main/simulator/assembler.py"
click node_cpu "https://github.com/rohith-s-hub/oblivion-agent/blob/main/simulator/cpu8085.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tui,node_sim_screen toneBlue
class node_agent_core,node_runtime,node_llm,node_parser,node_brain,node_plan_guard,node_permissions,node_knowledge toneAmber
class node_registry,node_file_tools,node_diff,node_batch_edit,node_rag,node_chunker,node_symbol_index toneMint
class node_voice,node_wake_word,node_mcp_server,node_mcp_transport toneRose
class node_session_store,node_assembler,node_cpu,node_user,node_editor,node_llm_services toneIndigo
```

## Components

### User interfaces

- [Terminal UI](https://github.com/rohith-s-hub/oblivion-agent/blob/main/ui/app.py): `ui/app.py`
- [8085 simulator UI](https://github.com/rohith-s-hub/oblivion-agent/blob/main/ui/sim_screen.py): `ui/sim_screen.py`

### Agent reasoning

- [M.E.E.R.A. loop](https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/core.py): `agent/core.py`
- [Agent runtime](https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/runtime.py): `agent/runtime.py`
- [Model fallback](https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/llm.py): `agent/llm.py`
- [Response parser](https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/parser.py): `agent/parser.py`
- [Reasoning prompts](https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/brain.py): `agent/brain.py`
- [Plan guard](https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/plan_guard.py): `agent/plan_guard.py`
- [Action permissions](https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/permissions.py): `agent/permissions.py`
- [Knowledge packs](https://github.com/rohith-s-hub/oblivion-agent/blob/main/knowledge/injector.py): `knowledge/injector.py`

### Coding and search

- [Tool registry](https://github.com/rohith-s-hub/oblivion-agent/blob/main/tools/registry.py): `tools/registry.py`
- [Workspace tools](https://github.com/rohith-s-hub/oblivion-agent/blob/main/tools/filesystem.py): `tools/filesystem.py`
- [Diff previews](https://github.com/rohith-s-hub/oblivion-agent/blob/main/tools/diff.py): `tools/diff.py`
- [Atomic editing](https://github.com/rohith-s-hub/oblivion-agent/blob/main/tools/batch_edit.py): `tools/batch_edit.py`
- [Hybrid search](https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/rag.py): `agent/rag.py`
- [AST chunking](https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/code_chunker.py): `agent/code_chunker.py`
- [Symbol index](https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/symbol_index.py): `agent/symbol_index.py`

### Voice and MCP

- [Voice interaction](https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/voice.py): `agent/voice.py`
- [Wake-word listener](https://github.com/rohith-s-hub/oblivion-agent/blob/main/agent/wake_word.py): `agent/wake_word.py`
- [MCP tool service](https://github.com/rohith-s-hub/oblivion-agent/blob/main/mcp_server/core.py): `mcp_server/core.py`
- [MCP transports](https://github.com/rohith-s-hub/oblivion-agent/tree/main/mcp_server/transports): `mcp_server/transports`

### State and simulator

- [Session storage](https://github.com/rohith-s-hub/oblivion-agent/blob/main/db/store.py): `db/store.py`
- [Assembler](https://github.com/rohith-s-hub/oblivion-agent/blob/main/simulator/assembler.py): `simulator/assembler.py`
- [8085 CPU](https://github.com/rohith-s-hub/oblivion-agent/blob/main/simulator/cpu8085.py): `simulator/cpu8085.py`

### Other components

- **Developer**
- **External editor**
- **LLM providers**

## Connections

- Developer → Terminal UI: submits prompt
- Terminal UI → M.E.E.R.A. loop: starts agent (evidence: `ui/app.py`)
- M.E.E.R.A. loop → Model fallback: requests completion (evidence: `agent/core.py`)
- Model fallback → LLM providers: calls models (evidence: `agent/llm.py`)
- M.E.E.R.A. loop → Response parser: parses response (evidence: `agent/core.py`)
- M.E.E.R.A. loop → Reasoning prompts: builds reasoning prompt (evidence: `agent/core.py`)
- M.E.E.R.A. loop → Tool registry: dispatches tools (evidence: `agent/core.py`)
- M.E.E.R.A. loop → Plan guard: checks plans (evidence: `agent/core.py`)
- Agent runtime → Action permissions: checks action tier (evidence: `agent/runtime.py`)
- Agent runtime → Tool registry: dispatches tools (evidence: `agent/runtime.py`)
- Tool registry → Workspace tools: invokes workspace tools (evidence: `tools/registry.py`)
- Tool registry → Atomic editing: invokes batch edits (evidence: `tools/registry.py`)
- M.E.E.R.A. loop → Diff previews: previews changes (evidence: `agent/core.py`)
- Tool registry → Hybrid search: uses code search (evidence: `tools/registry.py`)
- Hybrid search → AST chunking: chunks source (evidence: `agent/rag.py`)
- Hybrid search → Symbol index: updates symbols (evidence: `agent/rag.py`)
- M.E.E.R.A. loop → Knowledge packs: adds domain context (evidence: `agent/core.py`)
- Terminal UI → Session storage: stores sessions (evidence: `ui/app.py`)
- Terminal UI → Voice interaction: starts voice input (evidence: `ui/app.py`)
- Terminal UI → Wake-word listener: controls listening (evidence: `ui/app.py`)
- External editor → MCP transports: connects over MCP
- MCP transports → MCP tool service: routes requests (evidence: `mcp_server/transports/sse.py`)
- MCP tool service → Tool registry: dispatches tools (evidence: `mcp_server/core.py`)
- Developer → 8085 simulator UI: opens simulator
- 8085 simulator UI → Assembler: assembles programs (evidence: `ui/sim_screen.py`)
- 8085 simulator UI → 8085 CPU: runs instructions (evidence: `ui/sim_screen.py`)
