How mod-one/macc works
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: src/lib.rs Core · coordinator.rs Coordinator · src/lib.rs Registry · src/lib.rs Shared adapter
Components 19
Frontends
User entry points for terminal and browser interaction
Core backend
Canonical Rust services that own project state, planning, and coordination
- Core · Main Rust backend for project lifecycle, plan/apply, and runtime services
core/src/lib.rs - Project state · Canonical project configuration and .macc control-plane state
core/src/service/project.rs - Plan engine · Builds diffs, previews, and side-effecting apply operations
core/src/plan/mod.rs - Coordinator · Task dispatch, retries, rate limiting, sessions, and state transitions
core/src/coordinator.rs - Worktrees · Git worktree lifecycle and per-worker isolation
core/src/service/worktree.rs - Safety · Secret scanning, backups, atomic writes, restore, and cleanup
core/src/security/mod.rs - Registry · Built-in tool definitions and adapter contract surface
registry/src/lib.rs - Catalogs · 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 · Common catalog, schema, merge, render, and capability utilities
adapters/shared/src/lib.rs - Claude · Claude-specific emitters, doctor checks, and error mapping
adapters/claude/src/lib.rs - Codex · Codex-specific emitters, doctor checks, and error mapping
adapters/codex/src/lib.rs - Gemini · Gemini-specific emitters, doctor checks, and error mapping
adapters/gemini/src/lib.rs
Automation
Coordinator scripts, worktree execution, and runtime isolation
- Automat · Shell wrappers for coordinator and performer execution
automat/coordinator.sh - Worker state · Per-task sessions, logs, and worker slots under the control plane
- Git worktrees · Branch and worktree isolation used by parallel performers
- AI tools · Installed Claude, Codex, and Gemini CLIs invoked by MACC
Connections 26
- 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