How hubsx/mkx works
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: coordinator.rs Query · src/lib.rs Core · src/lib.rs Tools · app.rs TUI
Components 18
Interface
Local user entry and terminal experience
Runtime
Shared state and agent orchestration
- Query · Coordinates the agent loop, context management, scheduling, and worker flow
src-rust/crates/query/src/coordinator.rs - Core · Persistent state, settings, auth, sessions, prompts, budgeting, and policy
src-rust/crates/core/src/lib.rs - Prompt · Builds the system prompt and related runtime instructions
src-rust/crates/core/src/system_prompt.rs - Sessions · Session storage, migrations, SQLite persistence, and shared memory
src-rust/crates/core/src/session_storage.rs - Context · Compaction, token budgeting, truncation, and context analysis
src-rust/crates/query/src/compact.rs - Memory · Session memory, away summaries, and durable recall helpers
src-rust/crates/query/src/session_memory.rs - Commands · Named commands and command registration
src-rust/crates/commands/src/named_commands.rs
Capabilities
Tools and external action surfaces
Integrations
Provider and remote-session adapters
- MCP · Connection management, registry, and OAuth for third-party tool servers
src-rust/crates/mcp/src/lib.rs - API · Provider abstraction, model registry, auth, streaming, and normalization
src-rust/crates/api/src/lib.rs - Providers · Anthropic, OpenAI-compatible, Google, Azure, Bedrock, Cohere, Copilot, Codex, and others
src-rust/crates/api/src/providers/mod.rs - Bridge · Remote or browser-mediated session integration layer
src-rust/crates/bridge/src/lib.rs - ACP · Auxiliary protocol integration layer used by the wider runtime
src-rust/crates/acp/src/lib.rs
Connections 21
- 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