# hubsx/mkx architecture

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

- Interactive diagram: https://gitdiagram.com/hubsx/mkx
- Repository: https://github.com/hubsx/mkx

## Overview

1. This repository is a clean-room Rust reimplementation of a terminal AI coding agent. The architecture is split into a human-facing CLI/TUI shell, an orchestration core, a large tool/plugin layer, and provider-specific API adapters. The `spec/` directory is the design source of truth; `src-rust/` contains the implementation.

2. The main executable entrypoint is `crates/cli`. It bootstraps the app, handles startup and OAuth flows, loads the system prompt, and hands control to the interactive runtime. The CLI is the outer boundary for local users and is the first place where auth, mode selection, and environment setup occur.

3. The user experience is primarily rendered by `crates/tui`, which is a terminal UI layer with views for messages, dialogs, settings, model selection, session browsing, overlays, diff viewing, voice capture, and plugin/MCP panels. It consumes state from the runtime and emits user actions back into the command/query pipeline.

4. `crates/core` is the shared application backbone. It owns persistent state, settings, auth storage, session storage, migrations, prompt history, token budgeting, feature flags, git/file history utilities, remote-session state, analytics, and system-prompt construction. Most other crates depend on core for policy, configuration, and durable state.

5. `crates/query` is the central orchestration engine. It coordinates the agent loop, compaction/context management, session memory, background scheduling, and worker/agent coordination. This is where requests become multi-step agent work: plan, gather context, invoke tools, summarize results, and continue or stop.

6. `crates/tools` is the main action surface exposed to the model. It contains filesystem tools, shell tools, search tools, web fetch/search, LSP, notebook editing, REPL, patch/apply tools, task and cron tools, worktree management, user-question prompts, message sending, MCP access, and remote-trigger/computer-use style integrations. These tools are filtered by permissions and feature gates before being offered to the model.

7. `crates/api` abstracts model-provider connectivity. It includes provider implementations for Anthropic, OpenAI-compatible endpoints, Google, Azure, Bedrock, Cohere, Minimax, Copilot, Codex, and others, plus auth, model registry, request transformation, streaming parsing, normalization, and provider-specific error handling. This layer converts internal agent/tool state into provider API requests and turns streamed responses back into agent events.

8. `crates/mcp` and parts of `crates/tools` form the external capability bridge. MCP connection management, registry, OAuth, and resource access let the agent talk to third-party tool servers. The tools layer uses these services to expose MCP resources and authentication as first-class agent actions.

9. `crates/plugins` provides the extension boundary. It includes plugin manifests, loading, registries, hooks, and marketplace-related logic, so runtime behavior can be extended without changing the core agent loop. This is separate from MCP: plugins modify the host app, while MCP extends the tool surface.

10. `crates/bridge` is the remote/session integration layer. It supports bridge-style interaction with remote or browser-mediated sessions and sits apart from the local terminal loop. Related remote-session and settings-sync functionality is in core, showing that the architecture supports both local and remotely coordinated work.

11. `crates/buddy` is an optional feature-gated companion subsystem. It is isolated as its own crate, which is a strong signal that it is not part of the default agent loop but an add-on with its own state/rendering/behavior rules.

12. `crates/commands` holds named slash commands and command registration, while the spec files document the behavioral contract for entry/query, tools, components, hooks, terminal behavior, bridge/remote modes, utilities, special systems, and Rust-specific implementation details. Tests in `core` and `tui` focus on parity and rendering snapshots, which suggests correctness is validated at subsystem boundaries rather than only end-to-end.

13. Infrastructure-wise, the repo includes GitHub Pages and release workflows, but the runtime architecture is fundamentally local-first and terminal-centric. Network dependencies are mainly model providers, MCP servers, web access tools, and optional remote/bridge services; the rest of the system is layered around filesystem, shell, and session state.

14. For an architecture diagram, the most important flow is: user input enters CLI/TUI, the query engine builds context from core state, the model is called through api providers, the model selects tools from tools/MCP/plugins, results feed back into query/session state, and TUI renders the evolving interaction. Core sits underneath as the shared persistence and policy layer that every other subsystem depends on.

Main entry points: [`src-rust/crates/query/src/coordinator.rs`](https://github.com/hubsx/mkx/blob/main/src-rust/crates/query/src/coordinator.rs) (Query), [`src-rust/crates/core/src/lib.rs`](https://github.com/hubsx/mkx/blob/main/src-rust/crates/core/src/lib.rs) (Core), [`src-rust/crates/tools/src/lib.rs`](https://github.com/hubsx/mkx/blob/main/src-rust/crates/tools/src/lib.rs) (Tools), [`src-rust/crates/tui/src/app.rs`](https://github.com/hubsx/mkx/blob/main/src-rust/crates/tui/src/app.rs) (TUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_interface["Interface"]
  node_cli["CLI<br/>entrypoint/bootstrap<br/>[main.rs]"]
  node_tui_app["TUI<br/>terminal-ui<br/>[app.rs]"]
end

subgraph group_grp_runtime["Runtime"]
  node_query["Query<br/>agent-orchestrator<br/>[coordinator.rs]"]
  node_core_state[("Core<br/>state-policy<br/>[lib.rs]")]
  node_system_prompt["Prompt<br/>[system_prompt.rs]"]
  node_session_store[("Sessions<br/>storage<br/>[session_storage.rs]")]
  node_context_mgr["Context<br/>[compact.rs]"]
  node_memory["Memory<br/>[session_memory.rs]"]
  node_commands["Commands<br/>[named_commands.rs]"]
end

subgraph group_grp_capabilities["Capabilities"]
  node_tools["Tools<br/>action-surface<br/>[lib.rs]"]
  node_tools_mcp["MCP Tools<br/>tool-bridge<br/>[mcp_resources.rs]"]
end

subgraph group_grp_integrations["Integrations"]
  node_mcp["MCP<br/>external-capability-bridge<br/>[lib.rs]"]
  node_api["API<br/>model-adapters<br/>[lib.rs]"]
  node_providers["Providers<br/>provider-impls<br/>[mod.rs]"]
  node_bridge["Bridge<br/>remote-session<br/>[lib.rs]"]
  node_acp["ACP<br/>integration-lib<br/>[lib.rs]"]
end

subgraph group_grp_extension["Extensions"]
  node_plugins["Plugins<br/>extension-host<br/>[lib.rs]"]
  node_buddy["Buddy<br/>feature-addon<br/>[lib.rs]"]
end

node_cli -->|"loads config/state"| node_core_state
node_cli -->|"loads prompt"| node_system_prompt
node_cli -->|"starts UI"| node_tui_app
node_tui_app -->|"user actions"| node_query
node_query -->|"reads/writes"| node_core_state
node_query -->|"builds context"| node_context_mgr
node_query -->|"recalls state"| node_memory
node_query -->|"dispatches"| node_commands
node_query -->|"invokes tools"| node_tools
node_query -->|"calls model"| node_api
node_api -->|"adapts to"| node_providers
node_tools -->|"uses MCP"| node_mcp
node_tools -->|"exposes resources"| node_tools_mcp
node_plugins -.->|"extends surface"| node_tools
node_plugins -.->|"hooks runtime"| node_query
node_bridge -->|"shares session state"| node_core_state
node_buddy -.->|"adds panels"| node_tui_app
node_acp -.->|"protocol support"| node_api
node_core_state -->|"persists"| node_session_store
node_core_state -->|"constructs"| node_system_prompt
node_core_state -->|"shares settings"| node_tui_app

click node_cli "https://github.com/hubsx/mkx/blob/main/src-rust/crates/cli/src/main.rs"
click node_tui_app "https://github.com/hubsx/mkx/blob/main/src-rust/crates/tui/src/app.rs"
click node_query "https://github.com/hubsx/mkx/blob/main/src-rust/crates/query/src/coordinator.rs"
click node_core_state "https://github.com/hubsx/mkx/blob/main/src-rust/crates/core/src/lib.rs"
click node_system_prompt "https://github.com/hubsx/mkx/blob/main/src-rust/crates/core/src/system_prompt.rs"
click node_session_store "https://github.com/hubsx/mkx/blob/main/src-rust/crates/core/src/session_storage.rs"
click node_context_mgr "https://github.com/hubsx/mkx/blob/main/src-rust/crates/query/src/compact.rs"
click node_memory "https://github.com/hubsx/mkx/blob/main/src-rust/crates/query/src/session_memory.rs"
click node_commands "https://github.com/hubsx/mkx/blob/main/src-rust/crates/commands/src/named_commands.rs"
click node_tools "https://github.com/hubsx/mkx/blob/main/src-rust/crates/tools/src/lib.rs"
click node_tools_mcp "https://github.com/hubsx/mkx/blob/main/src-rust/crates/tools/src/mcp_resources.rs"
click node_mcp "https://github.com/hubsx/mkx/blob/main/src-rust/crates/mcp/src/lib.rs"
click node_api "https://github.com/hubsx/mkx/blob/main/src-rust/crates/api/src/lib.rs"
click node_providers "https://github.com/hubsx/mkx/blob/main/src-rust/crates/api/src/providers/mod.rs"
click node_bridge "https://github.com/hubsx/mkx/blob/main/src-rust/crates/bridge/src/lib.rs"
click node_plugins "https://github.com/hubsx/mkx/blob/main/src-rust/crates/plugins/src/lib.rs"
click node_buddy "https://github.com/hubsx/mkx/blob/main/src-rust/crates/buddy/src/lib.rs"
click node_acp "https://github.com/hubsx/mkx/blob/main/src-rust/crates/acp/src/lib.rs"

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_cli,node_tui_app toneBlue
class node_query,node_core_state,node_system_prompt,node_session_store,node_context_mgr,node_memory,node_commands toneAmber
class node_tools,node_tools_mcp toneMint
class node_mcp,node_api,node_providers,node_bridge,node_acp toneRose
class node_plugins,node_buddy toneIndigo
```

## Components

### Interface

Local user entry and terminal experience

- [CLI](https://github.com/hubsx/mkx/blob/main/src-rust/crates/cli/src/main.rs): entrypoint/bootstrap · Bootstraps startup, auth flows, system prompt loading, and interactive handoff · `src-rust/crates/cli/src/main.rs`
- [TUI](https://github.com/hubsx/mkx/blob/main/src-rust/crates/tui/src/app.rs): terminal-ui · Terminal UI shell, dialogs, views, overlays, and input/render loop · `src-rust/crates/tui/src/app.rs`

### Runtime

Shared state and agent orchestration

- [Query](https://github.com/hubsx/mkx/blob/main/src-rust/crates/query/src/coordinator.rs): agent-orchestrator · Coordinates the agent loop, context management, scheduling, and worker flow · `src-rust/crates/query/src/coordinator.rs`
- [Core](https://github.com/hubsx/mkx/blob/main/src-rust/crates/core/src/lib.rs): state-policy · Persistent state, settings, auth, sessions, prompts, budgeting, and policy · `src-rust/crates/core/src/lib.rs`
- [Prompt](https://github.com/hubsx/mkx/blob/main/src-rust/crates/core/src/system_prompt.rs): prompt-builder · Builds the system prompt and related runtime instructions · `src-rust/crates/core/src/system_prompt.rs`
- [Sessions](https://github.com/hubsx/mkx/blob/main/src-rust/crates/core/src/session_storage.rs): storage · Session storage, migrations, SQLite persistence, and shared memory · `src-rust/crates/core/src/session_storage.rs`
- [Context](https://github.com/hubsx/mkx/blob/main/src-rust/crates/query/src/compact.rs): context-management · Compaction, token budgeting, truncation, and context analysis · `src-rust/crates/query/src/compact.rs`
- [Memory](https://github.com/hubsx/mkx/blob/main/src-rust/crates/query/src/session_memory.rs): session-memory · Session memory, away summaries, and durable recall helpers · `src-rust/crates/query/src/session_memory.rs`
- [Commands](https://github.com/hubsx/mkx/blob/main/src-rust/crates/commands/src/named_commands.rs): slash-commands · Named commands and command registration · `src-rust/crates/commands/src/named_commands.rs`

### Capabilities

Tools and external action surfaces

- [Tools](https://github.com/hubsx/mkx/blob/main/src-rust/crates/tools/src/lib.rs): action-surface · Model-facing filesystem, shell, search, editing, and utility tools · `src-rust/crates/tools/src/lib.rs`
- [MCP Tools](https://github.com/hubsx/mkx/blob/main/src-rust/crates/tools/src/mcp_resources.rs): tool-bridge · MCP resources, auth, and server-backed tool exposure · `src-rust/crates/tools/src/mcp_resources.rs`

### Integrations

Provider and remote-session adapters

- [MCP](https://github.com/hubsx/mkx/blob/main/src-rust/crates/mcp/src/lib.rs): external-capability-bridge · Connection management, registry, and OAuth for third-party tool servers · `src-rust/crates/mcp/src/lib.rs`
- [API](https://github.com/hubsx/mkx/blob/main/src-rust/crates/api/src/lib.rs): model-adapters · Provider abstraction, model registry, auth, streaming, and normalization · `src-rust/crates/api/src/lib.rs`
- [Providers](https://github.com/hubsx/mkx/blob/main/src-rust/crates/api/src/providers/mod.rs): provider-impls · Anthropic, OpenAI-compatible, Google, Azure, Bedrock, Cohere, Copilot, Codex, and others · `src-rust/crates/api/src/providers/mod.rs`
- [Bridge](https://github.com/hubsx/mkx/blob/main/src-rust/crates/bridge/src/lib.rs): remote-session · Remote or browser-mediated session integration layer · `src-rust/crates/bridge/src/lib.rs`
- [ACP](https://github.com/hubsx/mkx/blob/main/src-rust/crates/acp/src/lib.rs): integration-lib · Auxiliary protocol integration layer used by the wider runtime · `src-rust/crates/acp/src/lib.rs`

### Extensions

Host and server extension points

- [Plugins](https://github.com/hubsx/mkx/blob/main/src-rust/crates/plugins/src/lib.rs): extension-host · Plugin manifests, loading, hooks, registry, and marketplace logic · `src-rust/crates/plugins/src/lib.rs`
- [Buddy](https://github.com/hubsx/mkx/blob/main/src-rust/crates/buddy/src/lib.rs): feature-addon · Optional feature-gated companion subsystem · `src-rust/crates/buddy/src/lib.rs`

## Connections

- CLI → Core: loads config/state · Startup and auth depend on durable core state
- CLI → Prompt: loads prompt · CLI assembles the system prompt before starting the runtime
- CLI → TUI: starts UI · Hands control to the terminal interface
- TUI → Query: user actions · UI emits prompts, commands, and control events into orchestration
- Query → Core: reads/writes · Agent coordination uses persistent settings, sessions, and policy
- Query → Context: builds context · Compaction and token management shape what the model sees
- Query → Memory: recalls state · Session memory and summaries feed the agent loop
- Query → Commands: dispatches · Named commands are routed through the runtime
- Query → Tools: invokes tools · Agent actions are executed through the tool layer
- Query → API: calls model · Orchestration sends requests to model providers
- API → Providers: adapts to · Provider-specific request/stream handling lives behind the API layer
- Tools → MCP: uses MCP · Tool implementations delegate to external capability connections
- Tools → MCP Tools: exposes resources · MCP resources and auth are surfaced as tools
- Plugins → Tools: extends surface · Plugins can add or modify host capabilities exposed to the agent
- Plugins → Query: hooks runtime · Hooks and registry can influence orchestration behavior
- Bridge → Core: shares session state · Remote-session features rely on core persistence and settings
- Buddy → TUI: adds panels · Companion subsystem integrates as an optional UI/runtime feature
- ACP → API: protocol support · Auxiliary protocol support complements provider connectivity
- Core → Sessions: persists · Sessions, migrations, and storage are centralized in core
- Core → Prompt: constructs · Core owns prompt assembly and related policy inputs
- Core → TUI: shares settings · UI reads user preferences, auth, and feature flags from core
