# liorlxl/miracode architecture

> Architecture diagram of the GitHub repository liorlxl/miracode, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/liorlxl/miracode
- Repository: https://github.com/liorlxl/miracode

## Overview

MiraCode is a terminal AI coding assistant: a user submits a coding request in the TUI, the agent streams model responses, invokes tools under permission controls, and presents results. Separate branches cover context and memory, extensibility, collaboration, and workspace safety. The README documents these capabilities; sampled source confirms several internals, but unsampled wiring is represented only where documentation supports it.

Main entry points: [`miracode/agent.py`](https://github.com/liorlxl/miracode/blob/main/miracode/agent.py) (Agent loop), [`miracode/commands/registry.py`](https://github.com/liorlxl/miracode/blob/main/miracode/commands/registry.py) (Slash commands), [`miracode/app.py`](https://github.com/liorlxl/miracode/blob/main/miracode/app.py) (Terminal UI), [`miracode/tools/__init__.py`](https://github.com/liorlxl/miracode/blob/main/miracode/tools/__init__.py) (Tool registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Interaction and agent"]
  node_tui["Terminal UI<br/>[app.py]"]
  node_agent["Agent loop<br/>[agent.py]"]
  node_commands["Slash commands<br/>[registry.py]"]
  node_client["Model clients<br/>[client.py]"]
end

subgraph group_execution["Tools and safety"]
  node_tools["Tool registry<br/>[__init__.py]"]
  node_tool_search["Tool search<br/>[tool_search.py]"]
  node_permissions["Permission checks<br/>[checker.py]"]
  node_coding_tools["Coding tools<br/>[base.py]"]
end

subgraph group_context["Context and persistence"]
  node_context["Context manager<br/>[manager.py]"]
  node_memory["Memory and instructions<br/>[auto_memory.py]"]
  node_sessions[("Session history<br/>[session.py]")]
  node_file_history[("Edit snapshots<br/>[history.py]")]
end

subgraph group_extensions["Extensions"]
  node_skills["Skills<br/>[executor.py]"]
  node_hooks["Hook engine<br/>[engine.py]"]
  node_mcp["MCP manager<br/>[manager.py]"]
end

subgraph group_collaboration["Collaboration"]
  node_subagents["Subagents<br/>[task_manager.py]"]
  node_teams["Agent teams<br/>[manager.py]"]
  node_worktrees["Worktree isolation<br/>[manager.py]"]
end

node_user(("Developer"))
node_providers(("Model providers"))
node_project[("Project files")]
node_command_exec["Command execution"]
node_hook_targets{{"Hook actions"}}
node_mcp_servers{{"MCP servers"}}

node_user -->|"submits request"| node_tui
node_tui -->|"runs request"| node_agent
node_tui -->|"dispatches commands"| node_commands
node_tui -->|"manages session"| node_sessions
node_agent -->|"requests completion"| node_client
node_client -->|"streams responses"| node_providers
node_agent -->|"dispatches tools"| node_tools
node_agent -->|"compacts context"| node_context
node_agent -->|"uses instructions and recall"| node_memory
node_agent -->|"runs lifecycle hooks"| node_hooks
node_agent -->|"launches background agents"| node_subagents
node_agent -->|"coordinates teammates"| node_teams
node_tools -->|"searches tools"| node_tool_search
node_tools -->|"checks access"| node_permissions
node_coding_tools -->|"reads and edits"| node_project
node_coding_tools -->|"runs commands"| node_command_exec
node_coding_tools -->|"records edits"| node_file_history
node_commands -->|"manages worktrees"| node_worktrees
node_commands -->|"compacts history"| node_context
node_commands -->|"manages memory"| node_memory
node_commands -->|"manages skills"| node_skills
node_commands -->|"manages servers"| node_mcp
node_hooks -->|"executes actions"| node_hook_targets
node_mcp -->|"connects and invokes"| node_mcp_servers
node_mcp -->|"registers wrappers"| node_tools
node_skills -->|"provides skill execution"| node_agent
node_teams -.->|"spawns teammates"| node_subagents
node_worktrees -->|"isolates workspace"| node_project

click node_tui "https://github.com/liorlxl/miracode/blob/main/miracode/app.py"
click node_agent "https://github.com/liorlxl/miracode/blob/main/miracode/agent.py"
click node_commands "https://github.com/liorlxl/miracode/blob/main/miracode/commands/registry.py"
click node_client "https://github.com/liorlxl/miracode/blob/main/miracode/client.py"
click node_tools "https://github.com/liorlxl/miracode/blob/main/miracode/tools/__init__.py"
click node_tool_search "https://github.com/liorlxl/miracode/blob/main/miracode/tools/impl/tool_search.py"
click node_permissions "https://github.com/liorlxl/miracode/blob/main/miracode/permissions/checker.py"
click node_coding_tools "https://github.com/liorlxl/miracode/blob/main/miracode/tools/base.py"
click node_context "https://github.com/liorlxl/miracode/blob/main/miracode/context/manager.py"
click node_memory "https://github.com/liorlxl/miracode/blob/main/miracode/memory/auto_memory.py"
click node_sessions "https://github.com/liorlxl/miracode/blob/main/miracode/memory/session.py"
click node_file_history "https://github.com/liorlxl/miracode/blob/main/miracode/filehistory/history.py"
click node_skills "https://github.com/liorlxl/miracode/blob/main/miracode/skills/executor.py"
click node_hooks "https://github.com/liorlxl/miracode/blob/main/miracode/hooks/engine.py"
click node_mcp "https://github.com/liorlxl/miracode/blob/main/miracode/mcp/manager.py"
click node_subagents "https://github.com/liorlxl/miracode/blob/main/miracode/agents/task_manager.py"
click node_teams "https://github.com/liorlxl/miracode/blob/main/miracode/teams/manager.py"
click node_worktrees "https://github.com/liorlxl/miracode/blob/main/miracode/worktree/manager.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_agent,node_commands,node_client toneBlue
class node_tools,node_tool_search,node_permissions,node_coding_tools,node_project toneAmber
class node_context,node_memory,node_sessions,node_file_history,node_mcp_servers toneMint
class node_skills,node_hooks,node_mcp toneRose
class node_subagents,node_teams,node_worktrees,node_user,node_providers,node_command_exec,node_hook_targets toneIndigo
```

## Components

### Interaction and agent

- [Terminal UI](https://github.com/liorlxl/miracode/blob/main/miracode/app.py): `miracode/app.py`
- [Agent loop](https://github.com/liorlxl/miracode/blob/main/miracode/agent.py): `miracode/agent.py`
- [Slash commands](https://github.com/liorlxl/miracode/blob/main/miracode/commands/registry.py): `miracode/commands/registry.py`
- [Model clients](https://github.com/liorlxl/miracode/blob/main/miracode/client.py): `miracode/client.py`

### Tools and safety

- [Tool registry](https://github.com/liorlxl/miracode/blob/main/miracode/tools/__init__.py): `miracode/tools/__init__.py`
- [Tool search](https://github.com/liorlxl/miracode/blob/main/miracode/tools/impl/tool_search.py): `miracode/tools/impl/tool_search.py`
- [Permission checks](https://github.com/liorlxl/miracode/blob/main/miracode/permissions/checker.py): `miracode/permissions/checker.py`
- [Coding tools](https://github.com/liorlxl/miracode/blob/main/miracode/tools/base.py): `miracode/tools/base.py`

### Context and persistence

- [Context manager](https://github.com/liorlxl/miracode/blob/main/miracode/context/manager.py): `miracode/context/manager.py`
- [Memory and instructions](https://github.com/liorlxl/miracode/blob/main/miracode/memory/auto_memory.py): `miracode/memory/auto_memory.py`
- [Session history](https://github.com/liorlxl/miracode/blob/main/miracode/memory/session.py): `miracode/memory/session.py`
- [Edit snapshots](https://github.com/liorlxl/miracode/blob/main/miracode/filehistory/history.py): `miracode/filehistory/history.py`

### Extensions

- [Skills](https://github.com/liorlxl/miracode/blob/main/miracode/skills/executor.py): `miracode/skills/executor.py`
- [Hook engine](https://github.com/liorlxl/miracode/blob/main/miracode/hooks/engine.py): `miracode/hooks/engine.py`
- [MCP manager](https://github.com/liorlxl/miracode/blob/main/miracode/mcp/manager.py): `miracode/mcp/manager.py`

### Collaboration

- [Subagents](https://github.com/liorlxl/miracode/blob/main/miracode/agents/task_manager.py): `miracode/agents/task_manager.py`
- [Agent teams](https://github.com/liorlxl/miracode/blob/main/miracode/teams/manager.py): `miracode/teams/manager.py`
- [Worktree isolation](https://github.com/liorlxl/miracode/blob/main/miracode/worktree/manager.py): `miracode/worktree/manager.py`

### Other components

- **Developer**
- **Model providers**
- **Project files**
- **Command execution**
- **Hook actions**
- **MCP servers**

## Connections

- Developer → Terminal UI: submits request
- Terminal UI → Agent loop: runs request
- Terminal UI → Slash commands: dispatches commands
- Terminal UI → Session history: manages session
- Agent loop → Model clients: requests completion
- Model clients → Model providers: streams responses
- Agent loop → Tool registry: dispatches tools
- Agent loop → Context manager: compacts context
- Agent loop → Memory and instructions: uses instructions and recall
- Agent loop → Hook engine: runs lifecycle hooks
- Agent loop → Subagents: launches background agents
- Agent loop → Agent teams: coordinates teammates
- Tool registry → Tool search: searches tools
- Tool registry → Permission checks: checks access
- Coding tools → Project files: reads and edits
- Coding tools → Command execution: runs commands
- Coding tools → Edit snapshots: records edits
- Slash commands → Worktree isolation: manages worktrees
- Slash commands → Context manager: compacts history
- Slash commands → Memory and instructions: manages memory
- Slash commands → Skills: manages skills
- Slash commands → MCP manager: manages servers
- Hook engine → Hook actions: executes actions
- MCP manager → MCP servers: connects and invokes
- MCP manager → Tool registry: registers wrappers
- Skills → Agent loop: provides skill execution
- Agent teams → Subagents: spawns teammates
- Worktree isolation → Project files: isolates workspace