# mod-one/macc architecture

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

- Interactive diagram: https://gitdiagram.com/mod-one/macc
- Repository: https://github.com/mod-one/macc

## Overview

1. **What this repository is**
   MACC is a Rust-based orchestration system for configuring and operating multiple agentic coding tools. It is not a single-purpose CLI: the repo contains a core engine, a command-line frontend, a TUI, a web UI, tool adapters, and a coordinator that can run autonomous multi-step coding workflows across git worktrees.

2. **Top-level architecture**
   The cleanest mental model is:
   - **frontends**: `cli`, `tui`, and `web`
   - **domain/runtime**: `core`
   - **tool integrations**: `adapters/*`
   - **tool catalog and contracts**: `registry`
   - **shared helper library**: `adapters/shared`
   - **automation assets**: `automat/`
   The frontends mostly orchestrate user interaction and delegate to `core`; the core owns the actual project state, plan/apply logic, and coordinator execution.

3. **Core engine as the system boundary**
   `core/` is the main backend and contains the project model, config lifecycle, tool registry, plan/diff generation, apply logic, backups, worktree management, security checks, and the coordinator runtime. It is where the authoritative `.macc/` project state is read and written. The CLI, TUI, and web UI are thin shells over these services.

4. **Configuration generation flow**
   The central workflow is deterministic: the system reads project config and tool/catalog state, builds a **plan**, then **applies** it. Generated artifacts include tool-specific config files, context files, catalogs, automation scripts, and supporting metadata under `.macc/`. The plan/apply split is important for architecture diagrams because it separates preview/diff computation from side-effecting filesystem writes.

5. **Tool adapter layer**
   `adapters/claude`, `adapters/codex`, and `adapters/gemini` are separate Rust crates that translate MACC’s canonical model into each tool’s specific file formats and conventions. Each adapter has:
   - emitters for the tool’s config/context files
   - a `doctor` module for health checks
   - error normalization for tool/provider failures
   - mapping/merge helpers for user-owned MCP or settings content
   This is the boundary where canonical MACC config becomes Claude/Codex/Gemini-specific output.

6. **Shared adapter infrastructure**
   `adapters/shared` contains common machinery used by the adapters: catalog loading, capability checks, schema handling, templating/rendering, fetch/merge utilities, diagnostics, and URL parsing. In a diagram, this is the shared support layer between the core canonical model and the tool-specific emitters.

7. **Registry and catalogs**
   `registry/` packages built-in tool definitions and contract tests for adapters and error normalization. The repository also ships catalog data under `catalog/` and docs about skills/MCP catalogs. This layer supplies the “known tool/spec inventory” that the core and adapters use when deciding what can be installed, generated, or validated.

8. **Automation coordinator and performer model**
   The automation subsystem is built around a coordinator/performer split. The coordinator manages task dispatch, state transitions, retries, rate limiting, and reconciliation. Performers run in isolated git worktrees and execute tool-specific runner scripts. The repo includes embedded shell wrappers in `automat/` and generated assets under `.macc/automation/`. This is the main concurrency boundary: one coordinator can supervise many parallel worktree workers.

9. **Worktree-based isolation**
   Parallel task execution is achieved through git worktrees rather than in-place editing. Each worker gets its own branch/worktree, session state, and logs. MACC keeps reusable worker slots and tracks task/worktree/session state in `.macc/state/`. This matters architecturally because it prevents agent sessions from contaminating the main repo or each other.

10. **CLI, TUI, and web UI roles**
   - `cli/` is the command surface for init/plan/apply/coordinator/tool/worktree operations.
   - `tui/` provides the local interactive terminal UI.
   - `web/` is a React/Vite frontend for the same backend, with dashboard, logs, worktrees, registry, diagnostics, and live coordinator views.
   The web app communicates with the backend over HTTP and uses live channels for streaming events and terminal sessions. The backend serves the app either from built assets or embedded assets.

11. **Core data paths**
   The primary data flow is:
   canonical config and project metadata in `.macc/macc.yaml` and related state files → core services compute plans or runtime actions → adapters render tool-specific files → apply writes backups and managed artifacts → coordinator/performers operate on worktrees → logs/events feed the TUI/web live views. The system is therefore filesystem-centric, with `.macc/` acting as the persistent control plane.

12. **Safety and recovery boundaries**
   Safety is built into the core: atomic writes, backups, secret scanning, guardrails around user-scope writes, and controlled cleanup via `clear`/restore workflows. Coordinator errors are normalized into structured codes so retry and throttle behavior can be deterministic. This suggests an architecture that prioritizes recoverability and auditable state transitions over ephemeral in-memory orchestration.

13. **External dependencies that materially affect the design**
   The main external dependencies are the installed agentic coding tools themselves, git worktrees/branches, and the local filesystem. The web UI uses a Rust backend plus a TypeScript/Vite frontend, while coordinator execution relies on shell runner scripts and tool command invocations. GitHub Actions are used for CI/release, but they are ancillary rather than central to runtime architecture.

14. **How to draw the diagram**
   A good diagram would show:
   - three user entry points: CLI, TUI, Web UI
   - a central Rust core backend
   - a separate adapter layer per tool
   - a registry/catalog source feeding tool capability decisions
   - a coordinator/performer subsystem operating over git worktrees
   - persistent `.macc/` project state, logs, backups, and automation assets
   - external AI tools as invoked executables outside the Rust process
   The key boundary is that MACC does not implement the AI models; it orchestrates and normalizes them.

Main entry points: [`core/src/lib.rs`](https://github.com/mod-one/macc/blob/main/core/src/lib.rs) (Core), [`core/src/coordinator.rs`](https://github.com/mod-one/macc/blob/main/core/src/coordinator.rs) (Coordinator), [`registry/src/lib.rs`](https://github.com/mod-one/macc/blob/main/registry/src/lib.rs) (Registry), [`adapters/shared/src/lib.rs`](https://github.com/mod-one/macc/blob/main/adapters/shared/src/lib.rs) (Shared adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontends["Frontends"]
  node_cli["CLI<br/>frontend<br/>[main.rs]"]
  node_tui["TUI<br/>frontend<br/>[main.rs]"]
  node_webui["Web UI<br/>frontend<br/>[App.tsx]"]
end

subgraph group_core["Core backend"]
  node_core_service["Core<br/>backend<br/>[lib.rs]"]
  node_project_config["Project state<br/>config/runtime<br/>[project.rs]"]
  node_plan_engine["Plan engine<br/>planning<br/>[mod.rs]"]
  node_coordinator_runtime{{"Coordinator<br/>orchestration<br/>[coordinator.rs]"}}
  node_worktree_service["Worktrees<br/>isolation<br/>[worktree.rs]"]
  node_security_recovery["Safety<br/>guardrails<br/>[mod.rs]"]
  node_registry["Registry<br/>catalog<br/>[lib.rs]"]
  node_catalogs["Catalogs<br/>catalog-data<br/>[mcp.catalog.json]"]
end

subgraph group_adapters["Tool adapters"]
  node_adapter_shared["Shared adapter<br/>adapter-support<br/>[lib.rs]"]
  node_claude_adapter["Claude<br/>adapter<br/>[lib.rs]"]
  node_codex_adapter["Codex<br/>adapter<br/>[lib.rs]"]
  node_gemini_adapter["Gemini<br/>adapter<br/>[lib.rs]"]
end

subgraph group_automation["Automation"]
  node_automation_scripts["Automat<br/>runner-scripts<br/>[coordinator.sh]"]
  node_worker_state["Worker state<br/>runtime-state"]
  node_git_worktrees["Git worktrees<br/>external-isolation"]
  node_external_tools["AI tools<br/>external-executables"]
end

node_cli -->|"commands"| node_core_service
node_tui -->|"runtime ops"| node_core_service
node_webui -->|"HTTP/live"| node_core_service
node_core_service -->|"loads/saves"| node_project_config
node_core_service -->|"plan/apply"| node_plan_engine
node_core_service -->|"orchestrates"| node_coordinator_runtime
node_core_service -->|"manages"| node_worktree_service
node_core_service -->|"guards"| node_security_recovery
node_core_service -->|"tool contracts"| node_registry
node_core_service -->|"catalog data"| node_catalogs
node_plan_engine -->|"renders"| node_adapter_shared
node_adapter_shared -->|"supports"| node_claude_adapter
node_adapter_shared -->|"supports"| node_codex_adapter
node_adapter_shared -->|"supports"| node_gemini_adapter
node_registry -->|"contracts"| node_claude_adapter
node_registry -->|"contracts"| node_codex_adapter
node_registry -->|"contracts"| node_gemini_adapter
node_coordinator_runtime -->|"executes"| node_automation_scripts
node_automation_scripts -->|"invokes"| node_external_tools
node_coordinator_runtime -->|"tracks"| node_worker_state
node_worker_state -->|"isolates"| node_git_worktrees
node_coordinator_runtime -->|"operates on"| node_git_worktrees
node_claude_adapter -->|"targets"| node_external_tools
node_codex_adapter -->|"targets"| node_external_tools
node_gemini_adapter -->|"targets"| node_external_tools
node_webui -->|"views"| node_worker_state

click node_cli "https://github.com/mod-one/macc/blob/main/cli/src/main.rs"
click node_tui "https://github.com/mod-one/macc/blob/main/tui/src/main.rs"
click node_webui "https://github.com/mod-one/macc/blob/main/web/src/App.tsx"
click node_core_service "https://github.com/mod-one/macc/blob/main/core/src/lib.rs"
click node_project_config "https://github.com/mod-one/macc/blob/main/core/src/service/project.rs"
click node_plan_engine "https://github.com/mod-one/macc/blob/main/core/src/plan/mod.rs"
click node_coordinator_runtime "https://github.com/mod-one/macc/blob/main/core/src/coordinator.rs"
click node_worktree_service "https://github.com/mod-one/macc/blob/main/core/src/service/worktree.rs"
click node_security_recovery "https://github.com/mod-one/macc/blob/main/core/src/security/mod.rs"
click node_registry "https://github.com/mod-one/macc/blob/main/registry/src/lib.rs"
click node_catalogs "https://github.com/mod-one/macc/blob/main/catalog/mcp.catalog.json"
click node_adapter_shared "https://github.com/mod-one/macc/blob/main/adapters/shared/src/lib.rs"
click node_claude_adapter "https://github.com/mod-one/macc/blob/main/adapters/claude/src/lib.rs"
click node_codex_adapter "https://github.com/mod-one/macc/blob/main/adapters/codex/src/lib.rs"
click node_gemini_adapter "https://github.com/mod-one/macc/blob/main/adapters/gemini/src/lib.rs"
click node_automation_scripts "https://github.com/mod-one/macc/blob/main/automat/coordinator.sh"

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,node_webui toneBlue
class node_core_service,node_project_config,node_plan_engine,node_coordinator_runtime,node_worktree_service,node_security_recovery,node_registry,node_catalogs toneAmber
class node_adapter_shared,node_claude_adapter,node_codex_adapter,node_gemini_adapter toneMint
class node_automation_scripts,node_worker_state,node_git_worktrees,node_external_tools toneRose
```

## Components

### Frontends

User entry points for terminal and browser interaction

- [CLI](https://github.com/mod-one/macc/blob/main/cli/src/main.rs): frontend · Command surface for init, plan, apply, coordinator, tool, and worktree actions · `cli/src/main.rs`
- [TUI](https://github.com/mod-one/macc/blob/main/tui/src/main.rs): frontend · Local interactive terminal UI · `tui/src/main.rs`
- [Web UI](https://github.com/mod-one/macc/blob/main/web/src/App.tsx): frontend · Browser UI for dashboards, logs, worktrees, registry, and live ops · `web/src/App.tsx`

### Core backend

Canonical Rust services that own project state, planning, and coordination

- [Core](https://github.com/mod-one/macc/blob/main/core/src/lib.rs): backend · Main Rust backend for project lifecycle, plan/apply, and runtime services · `core/src/lib.rs`
- [Project state](https://github.com/mod-one/macc/blob/main/core/src/service/project.rs): config/runtime · Canonical project configuration and .macc control-plane state · `core/src/service/project.rs`
- [Plan engine](https://github.com/mod-one/macc/blob/main/core/src/plan/mod.rs): planning · Builds diffs, previews, and side-effecting apply operations · `core/src/plan/mod.rs`
- [Coordinator](https://github.com/mod-one/macc/blob/main/core/src/coordinator.rs): orchestration · Task dispatch, retries, rate limiting, sessions, and state transitions · `core/src/coordinator.rs`
- [Worktrees](https://github.com/mod-one/macc/blob/main/core/src/service/worktree.rs): isolation · Git worktree lifecycle and per-worker isolation · `core/src/service/worktree.rs`
- [Safety](https://github.com/mod-one/macc/blob/main/core/src/security/mod.rs): guardrails · Secret scanning, backups, atomic writes, restore, and cleanup · `core/src/security/mod.rs`
- [Registry](https://github.com/mod-one/macc/blob/main/registry/src/lib.rs): catalog · Built-in tool definitions and adapter contract surface · `registry/src/lib.rs`
- [Catalogs](https://github.com/mod-one/macc/blob/main/catalog/mcp.catalog.json): catalog-data · Skill and MCP catalog inputs used for tool selection and validation · `catalog/mcp.catalog.json`

### Tool adapters

Tool-specific emitters and normalization layers

- [Shared adapter](https://github.com/mod-one/macc/blob/main/adapters/shared/src/lib.rs): adapter-support · Common catalog, schema, merge, render, and capability utilities · `adapters/shared/src/lib.rs`
- [Claude](https://github.com/mod-one/macc/blob/main/adapters/claude/src/lib.rs): adapter · Claude-specific emitters, doctor checks, and error mapping · `adapters/claude/src/lib.rs`
- [Codex](https://github.com/mod-one/macc/blob/main/adapters/codex/src/lib.rs): adapter · Codex-specific emitters, doctor checks, and error mapping · `adapters/codex/src/lib.rs`
- [Gemini](https://github.com/mod-one/macc/blob/main/adapters/gemini/src/lib.rs): adapter · Gemini-specific emitters, doctor checks, and error mapping · `adapters/gemini/src/lib.rs`

### Automation

Coordinator scripts, worktree execution, and runtime isolation

- [Automat](https://github.com/mod-one/macc/blob/main/automat/coordinator.sh): runner-scripts · Shell wrappers for coordinator and performer execution · `automat/coordinator.sh`
- **Worker state**: runtime-state · Per-task sessions, logs, and worker slots under the control plane
- **Git worktrees**: external-isolation · Branch and worktree isolation used by parallel performers
- **AI tools**: external-executables · Installed Claude, Codex, and Gemini CLIs invoked by MACC

## Connections

- CLI → Core: commands · CLI delegates lifecycle, planning, apply, and coordination work to core
- TUI → Core: runtime ops · TUI consumes core services and live state
- Web UI → Core: HTTP/live · Web UI talks to backend APIs and streaming channels
- Core → Project state: loads/saves · Core owns canonical project and .macc state
- Core → Plan engine: plan/apply · Core computes previews and applies filesystem changes
- Core → Coordinator: orchestrates · Core exposes coordinator workflows and runtime control
- Core → Worktrees: manages · Core provisions and tracks isolated worktrees
- Core → Safety: guards · Core applies safety checks, backups, and restore flows
- Core → Registry: tool contracts · Core uses registry definitions for tool support and validation
- Core → Catalogs: catalog data · Core consults built-in catalog inputs for skills and MCP data
- Plan engine → Shared adapter: renders · Plan/apply uses shared rendering, merge, and schema helpers
- Shared adapter → Claude: supports · Shared adapter infrastructure feeds Claude-specific emitters
- Shared adapter → Codex: supports · Shared adapter infrastructure feeds Codex-specific emitters
- Shared adapter → Gemini: supports · Shared adapter infrastructure feeds Gemini-specific emitters
- Registry → Claude: contracts · Registry ships adapter definitions and normalization tests
- Registry → Codex: contracts · Registry ships adapter definitions and normalization tests
- Registry → Gemini: contracts · Registry ships adapter definitions and normalization tests
- Coordinator → Automat: executes · Coordinator uses shell runners for task execution
- Automat → AI tools: invokes · Performer scripts call installed agentic coding tools
- Coordinator → Worker state: tracks · Coordinator manages sessions, retries, logs, and worker slots
- Worker state → Git worktrees: isolates · Each worker is tied to its own worktree and branch
- Coordinator → Git worktrees: operates on · Coordinator schedules worktree-backed performer tasks
- Claude → AI tools: targets · Claude adapter emits tool-specific config and runner inputs
- Codex → AI tools: targets · Codex adapter emits tool-specific config and runner inputs
- Gemini → AI tools: targets · Gemini adapter emits tool-specific config and runner inputs
- Web UI → Worker state: views · Web UI displays live coordinator, logs, and worker status
