# tarkek/matrixcode architecture

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

- Interactive diagram: https://gitdiagram.com/tarkek/matrixcode
- Repository: https://github.com/tarkek/matrixcode

## Overview

matrixcode is a local coding assistant: a user enters a request in the Textual TUI, the agent sends context to an OpenAI-compatible llama-server, parses the response for tool calls, executes tools, and returns results to the model and chat. Its supporting capabilities include dynamically loaded tools, skills and slash commands; workspace safeguards and approvals; task plans and checkpoints; context compression, summaries and session continuation. Edges reflect the excerpts, SOURCE INDEX references and README; links for unsampled tool behavior are documented capabilities, not inspected call paths.

Main entry points: [`agent/agent.py`](https://github.com/tarkek/matrixcode/blob/main/agent/agent.py) (Agent loop), [`ui/app.py`](https://github.com/tarkek/matrixcode/blob/main/ui/app.py) (Textual TUI), [`main.py`](https://github.com/tarkek/matrixcode/blob/main/main.py) (Startup), [`core/registries.py`](https://github.com/tarkek/matrixcode/blob/main/core/registries.py) (Dynamic registries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Startup and interface"]
  node_main["Startup<br/>[main.py]"]
  node_tui["Textual TUI<br/>[app.py]"]
  node_callbacks["UI callbacks<br/>[callbacks.py]"]
  node_chat["Chat view<br/>[chat.py]"]
  node_stats["Status panels<br/>[stats.py]"]
end

subgraph group_agent["Agent and model"]
  node_agentloop["Agent loop<br/>[agent.py]"]
  node_client["LLM client<br/>[client.py]"]
  node_parser["Call parser<br/>[parser.py]"]
end

subgraph group_runtime["Tool runtime"]
  node_registries["Dynamic registries<br/>[registries.py]"]
  node_executor["Tool executor<br/>[executor.py]"]
  node_skills["Prompt skills"]
  node_commands["Slash commands"]
end

subgraph group_workspace["Workspace capabilities"]
  node_toolset["Workspace tools"]
  node_shell["Shell execution<br/>[run_shell.py]"]
  node_checkpoints["Checkpoints<br/>[checkpoint.py]"]
  node_todos["Task plans<br/>[todo.py]"]
  node_web["Web fetch<br/>[fetch_url.py]"]
  node_project["Project inspection<br/>[project_info.py]"]
  node_images["Image display<br/>[show_image.py]"]
  node_sandbox["Workspace sandbox<br/>[sandbox.py]"]
  node_childsandbox["Child sandbox<br/>[sitecustomize.py]"]
  node_verification["File post-checks<br/>[verify.py]"]
end

subgraph group_support["Session support"]
  node_context["Context and memory<br/>[context.py]"]
  node_compression["Context compression<br/>[compression.py]"]
  node_summary["History summary<br/>[summarize.py]"]
  node_policy["Approval policy<br/>[policy.py]"]
  node_logger[("Session log<br/>[logger.py]")]
end

node_user(("User"))
node_model["llama-server"]
node_workspacefiles[("Workspace files")]

node_user -->|"enters request"| node_tui
node_main -->|"loads modules"| node_registries
node_main -->|"starts UI"| node_tui
node_tui -->|"starts turn"| node_agentloop
node_tui -->|"dispatches slash command"| node_commands
node_tui -->|"uses callbacks"| node_callbacks
node_callbacks -->|"updates view"| node_chat
node_tui -->|"renders chat"| node_chat
node_tui -->|"updates status"| node_stats
node_agentloop -->|"requests completion"| node_client
node_client -->|"streams API"| node_model
node_agentloop -->|"parses calls"| node_parser
node_agentloop -->|"executes tool"| node_executor
node_executor -->|"resolves tool"| node_registries
node_registries -->|"loads tools"| node_toolset
node_registries -->|"loads skills"| node_skills
node_registries -->|"loads commands"| node_commands
node_executor -->|"guards tool access"| node_sandbox
node_executor -->|"reads before edits"| node_workspacefiles
node_toolset -->|"reads and edits"| node_workspacefiles
node_shell -->|"uses sandbox"| node_sandbox
node_sandbox -->|"configures child Python"| node_childsandbox
node_checkpoints -->|"checks paths"| node_sandbox
node_checkpoints -->|"snapshots workspace"| node_workspacefiles
node_todos -->|"stores task plan"| node_workspacefiles
node_web -.->|"fetches external URL"| node_model
node_toolset -.->|"post-checks writes"| node_verification
node_agentloop -->|"builds prompt context"| node_context
node_agentloop -->|"compresses history"| node_compression
node_agentloop -->|"summarizes history"| node_summary
node_main -->|"summarizes resumed history"| node_summary
node_main -->|"sets startup policy"| node_policy
node_agentloop -->|"records events"| node_logger
node_main -->|"opens session log"| node_logger
node_project -->|"inspects project"| node_workspacefiles
node_images -->|"displays image"| node_workspacefiles

click node_main "https://github.com/tarkek/matrixcode/blob/main/main.py"
click node_tui "https://github.com/tarkek/matrixcode/blob/main/ui/app.py"
click node_callbacks "https://github.com/tarkek/matrixcode/blob/main/ui/callbacks.py"
click node_chat "https://github.com/tarkek/matrixcode/blob/main/ui/chat.py"
click node_stats "https://github.com/tarkek/matrixcode/blob/main/ui/stats.py"
click node_agentloop "https://github.com/tarkek/matrixcode/blob/main/agent/agent.py"
click node_client "https://github.com/tarkek/matrixcode/blob/main/llm/client.py"
click node_parser "https://github.com/tarkek/matrixcode/blob/main/core/parser.py"
click node_registries "https://github.com/tarkek/matrixcode/blob/main/core/registries.py"
click node_executor "https://github.com/tarkek/matrixcode/blob/main/execution/executor.py"
click node_toolset "https://github.com/tarkek/matrixcode/tree/main/tools"
click node_shell "https://github.com/tarkek/matrixcode/blob/main/tools/run_shell.py"
click node_checkpoints "https://github.com/tarkek/matrixcode/blob/main/tools/checkpoint.py"
click node_todos "https://github.com/tarkek/matrixcode/blob/main/tools/todo.py"
click node_web "https://github.com/tarkek/matrixcode/blob/main/tools/fetch_url.py"
click node_project "https://github.com/tarkek/matrixcode/blob/main/tools/project_info.py"
click node_images "https://github.com/tarkek/matrixcode/blob/main/tools/show_image.py"
click node_sandbox "https://github.com/tarkek/matrixcode/blob/main/core/sandbox.py"
click node_childsandbox "https://github.com/tarkek/matrixcode/blob/main/core/childsandbox/sitecustomize.py"
click node_verification "https://github.com/tarkek/matrixcode/blob/main/core/verify.py"
click node_skills "https://github.com/tarkek/matrixcode/tree/main/skills"
click node_commands "https://github.com/tarkek/matrixcode/tree/main/commands"
click node_context "https://github.com/tarkek/matrixcode/blob/main/agent/context.py"
click node_compression "https://github.com/tarkek/matrixcode/blob/main/core/compression.py"
click node_summary "https://github.com/tarkek/matrixcode/blob/main/core/summarize.py"
click node_policy "https://github.com/tarkek/matrixcode/blob/main/core/policy.py"
click node_logger "https://github.com/tarkek/matrixcode/blob/main/core/logger.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_main,node_tui,node_callbacks,node_chat,node_stats,node_user toneBlue
class node_agentloop,node_client,node_parser,node_workspacefiles toneAmber
class node_registries,node_executor,node_skills,node_commands,node_model toneMint
class node_toolset,node_shell,node_checkpoints,node_todos,node_web,node_project,node_images,node_sandbox,node_childsandbox,node_verification toneRose
class node_context,node_compression,node_summary,node_policy,node_logger toneIndigo
```

## Components

### Startup and interface

- [Startup](https://github.com/tarkek/matrixcode/blob/main/main.py): `main.py`
- [Textual TUI](https://github.com/tarkek/matrixcode/blob/main/ui/app.py): `ui/app.py`
- [UI callbacks](https://github.com/tarkek/matrixcode/blob/main/ui/callbacks.py): `ui/callbacks.py`
- [Chat view](https://github.com/tarkek/matrixcode/blob/main/ui/chat.py): `ui/chat.py`
- [Status panels](https://github.com/tarkek/matrixcode/blob/main/ui/stats.py): `ui/stats.py`

### Agent and model

- [Agent loop](https://github.com/tarkek/matrixcode/blob/main/agent/agent.py): `agent/agent.py`
- [LLM client](https://github.com/tarkek/matrixcode/blob/main/llm/client.py): `llm/client.py`
- [Call parser](https://github.com/tarkek/matrixcode/blob/main/core/parser.py): `core/parser.py`

### Tool runtime

- [Dynamic registries](https://github.com/tarkek/matrixcode/blob/main/core/registries.py): `core/registries.py`
- [Tool executor](https://github.com/tarkek/matrixcode/blob/main/execution/executor.py): `execution/executor.py`
- [Prompt skills](https://github.com/tarkek/matrixcode/tree/main/skills): `skills`
- [Slash commands](https://github.com/tarkek/matrixcode/tree/main/commands): `commands`

### Workspace capabilities

- [Workspace tools](https://github.com/tarkek/matrixcode/tree/main/tools): `tools`
- [Shell execution](https://github.com/tarkek/matrixcode/blob/main/tools/run_shell.py): `tools/run_shell.py`
- [Checkpoints](https://github.com/tarkek/matrixcode/blob/main/tools/checkpoint.py): `tools/checkpoint.py`
- [Task plans](https://github.com/tarkek/matrixcode/blob/main/tools/todo.py): `tools/todo.py`
- [Web fetch](https://github.com/tarkek/matrixcode/blob/main/tools/fetch_url.py): `tools/fetch_url.py`
- [Project inspection](https://github.com/tarkek/matrixcode/blob/main/tools/project_info.py): `tools/project_info.py`
- [Image display](https://github.com/tarkek/matrixcode/blob/main/tools/show_image.py): `tools/show_image.py`
- [Workspace sandbox](https://github.com/tarkek/matrixcode/blob/main/core/sandbox.py): `core/sandbox.py`
- [Child sandbox](https://github.com/tarkek/matrixcode/blob/main/core/childsandbox/sitecustomize.py): `core/childsandbox/sitecustomize.py`
- [File post-checks](https://github.com/tarkek/matrixcode/blob/main/core/verify.py): `core/verify.py`

### Session support

- [Context and memory](https://github.com/tarkek/matrixcode/blob/main/agent/context.py): `agent/context.py`
- [Context compression](https://github.com/tarkek/matrixcode/blob/main/core/compression.py): `core/compression.py`
- [History summary](https://github.com/tarkek/matrixcode/blob/main/core/summarize.py): `core/summarize.py`
- [Approval policy](https://github.com/tarkek/matrixcode/blob/main/core/policy.py): `core/policy.py`
- [Session log](https://github.com/tarkek/matrixcode/blob/main/core/logger.py): `core/logger.py`

### Other components

- **User**
- **llama-server**
- **Workspace files**

## Connections

- User → Textual TUI: enters request (evidence: `README.md`)
- Startup → Dynamic registries: loads modules (evidence: `README.md`)
- Startup → Textual TUI: starts UI (evidence: `main.py`)
- Textual TUI → Agent loop: starts turn (evidence: `ui/app.py`)
- Textual TUI → Slash commands: dispatches slash command (evidence: `ui/app.py`)
- Textual TUI → UI callbacks: uses callbacks (evidence: `ui/app.py`)
- UI callbacks → Chat view: updates view (evidence: `ui/callbacks.py`)
- Textual TUI → Chat view: renders chat (evidence: `ui/app.py`)
- Textual TUI → Status panels: updates status (evidence: `ui/app.py`)
- Agent loop → LLM client: requests completion (evidence: `agent/agent.py`)
- LLM client → llama-server: streams API (evidence: `README.md`)
- Agent loop → Call parser: parses calls (evidence: `agent/agent.py`)
- Agent loop → Tool executor: executes tool (evidence: `agent/agent.py`)
- Tool executor → Dynamic registries: resolves tool (evidence: `execution/executor.py`)
- Dynamic registries → Workspace tools: loads tools (evidence: `README.md`)
- Dynamic registries → Prompt skills: loads skills (evidence: `README.md`)
- Dynamic registries → Slash commands: loads commands (evidence: `README.md`)
- Tool executor → Workspace sandbox: guards tool access (evidence: `execution/executor.py`)
- Tool executor → Workspace files: reads before edits (evidence: `execution/executor.py`)
- Workspace tools → Workspace files: reads and edits (evidence: `README.md`)
- Shell execution → Workspace sandbox: uses sandbox (evidence: `tools/run_shell.py`)
- Workspace sandbox → Child sandbox: configures child Python (evidence: `core/sandbox.py`)
- Checkpoints → Workspace sandbox: checks paths (evidence: `tools/checkpoint.py`)
- Checkpoints → Workspace files: snapshots workspace (evidence: `README.md`)
- Task plans → Workspace files: stores task plan (evidence: `README.md`)
- Web fetch → llama-server: fetches external URL (evidence: `README.md`)
- Workspace tools → File post-checks: post-checks writes (evidence: `README.md`)
- Agent loop → Context and memory: builds prompt context (evidence: `agent/agent.py`)
- Agent loop → Context compression: compresses history (evidence: `agent/agent.py`)
- Agent loop → History summary: summarizes history (evidence: `agent/agent.py`)
- Startup → History summary: summarizes resumed history (evidence: `main.py`)
- Startup → Approval policy: sets startup policy (evidence: `main.py`)
- Agent loop → Session log: records events (evidence: `agent/agent.py`)
- Startup → Session log: opens session log (evidence: `main.py`)
- Project inspection → Workspace files: inspects project (evidence: `README.md`)
- Image display → Workspace files: displays image (evidence: `README.md`)
