# diegoagd10/ai-harness architecture

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

- Interactive diagram: https://gitdiagram.com/diegoagd10/ai-harness
- Repository: https://github.com/diegoagd10/ai-harness

## Overview

ai-harness centralizes version-controlled agent persona, skills, and change-agent configuration, then distributes them to supported coding-agent CLIs. Its user-facing workflow starts at the Typer CLI: users scaffold a repository, install or remove global artifacts, configure model overrides, or run a file-backed change/task workflow; worktree commands isolate sessions. Provider-specific administrators render native artifacts, while the change subsystem manages changes, tasks, and review state. README documents the installer capabilities; source excerpts are limited, so some internal links are omitted where invocation is not evidenced.

Main entry points: [`src/ai_harness/main.py`](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/main.py) (Command CLI), [`src/ai_harness/modules/harness/change.py`](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/change.py) (Change Engine), [`src/ai_harness/modules/wizard/tui.py`](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/wizard/tui.py) (Model Wizard), [`src/ai_harness/modules/harness/operations.py`](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/operations.py) (Artifact Operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and Commands"]
  node_cli["Command CLI<br/>[main.py]"]
  node_init["Repo Scaffolding<br/>[init.py]"]
  node_install_cmd["Install Command<br/>[install.py]"]
  node_uninstall_cmd["Uninstall Command<br/>[uninstall.py]"]
  node_models_cmd["Model Command<br/>[set_models.py]"]
  node_worktree_cmd["Worktree Commands<br/>[worktree.py]"]
  node_change_cmd["Change Commands<br/>[change.py]"]
end

subgraph group_distribution["Artifact Distribution"]
  node_artifacts["Artifact Operations<br/>[operations.py]"]
  node_provider_dispatch["Provider Dispatch<br/>[__init__.py]"]
  node_provider_admin["Provider Renderers<br/>[base.py]"]
  node_agent_configs["Agent Config Homes"]
end

subgraph group_session["Change Sessions"]
  node_worktree["Git Worktree Logic<br/>[worktree.py]"]
  node_change_engine["Change Engine<br/>[change.py]"]
  node_change_flow["Change Flow<br/>[change_flow.py]"]
  node_task_store[("Task Store<br/>[tasks.py]")]
  node_change_config["Change Config<br/>[models.py]"]
end

subgraph group_review["Review Contracts"]
  node_review_contract["Review Contracts"]
  node_review_storage[("Review Persistence")]
  node_checkpoint["Review Checkpoints"]
  node_receipt_store[("Receipts and Evidence<br/>[receipts.py]")]
  node_codec["Shared Review Codec"]
end

subgraph group_configuration["Configuration"]
  node_wizard["Model Wizard<br/>[tui.py]"]
  node_wizard_logic["Wizard Data Logic<br/>[pure.py]"]
  node_overrides[("Model Overrides<br/>[override_store.py]")]
end

node_user(("Engineer"))

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches"| node_init
node_cli -->|"dispatches"| node_install_cmd
node_cli -->|"dispatches"| node_uninstall_cmd
node_cli -->|"dispatches"| node_models_cmd
node_cli -->|"dispatches"| node_worktree_cmd
node_cli -->|"dispatches"| node_change_cmd
node_init -->|"scaffolds"| node_change_config
node_install_cmd -.->|"installs"| node_artifacts
node_uninstall_cmd -.->|"removes artifacts"| node_artifacts
node_artifacts -->|"selects provider"| node_provider_dispatch
node_provider_dispatch -->|"dispatches render"| node_provider_admin
node_artifacts -.->|"writes artifacts"| node_agent_configs
node_models_cmd -->|"starts wizard"| node_wizard
node_wizard -->|"uses data logic"| node_wizard_logic
node_wizard -->|"reads metadata"| node_provider_dispatch
node_wizard -->|"persists choices"| node_overrides
node_worktree_cmd -->|"creates worktrees"| node_worktree
node_change_cmd -->|"invokes change operations"| node_change_engine
node_change_cmd -->|"invokes task operations"| node_task_store
node_change_engine -->|"uses flow"| node_change_flow
node_change_engine -->|"uses task store"| node_task_store
node_change_engine -->|"uses config models"| node_change_config
node_review_storage -->|"encodes records"| node_review_contract
node_review_storage -->|"publishes bundles"| node_receipt_store
node_checkpoint -->|"uses codec"| node_codec
node_checkpoint -->|"uses storage errors"| node_review_storage
node_checkpoint -->|"publishes evidence"| node_receipt_store

click node_cli "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/main.py"
click node_init "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/commands/init.py"
click node_install_cmd "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/commands/install.py"
click node_uninstall_cmd "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/commands/uninstall.py"
click node_models_cmd "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/commands/set_models.py"
click node_worktree_cmd "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/commands/worktree.py"
click node_change_cmd "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/commands/change.py"
click node_artifacts "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/operations.py"
click node_provider_dispatch "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/administrators/__init__.py"
click node_provider_admin "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/administrators/base.py"
click node_wizard "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/wizard/tui.py"
click node_wizard_logic "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/wizard/pure.py"
click node_overrides "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/override_store.py"
click node_worktree "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/worktree.py"
click node_change_engine "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/change.py"
click node_change_flow "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/change_flow.py"
click node_task_store "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/tasks.py"
click node_change_config "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/change_config/models.py"
click node_review_contract "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/review_transactions.py"
click node_review_storage "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/review_transaction_storage.py"
click node_checkpoint "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/review_transaction_checkpoints.py"
click node_receipt_store "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/receipts.py"
click node_codec "https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/_review_contract_codec_shared.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_cli,node_init,node_install_cmd,node_uninstall_cmd,node_models_cmd,node_worktree_cmd,node_change_cmd toneBlue
class node_artifacts,node_provider_dispatch,node_provider_admin,node_agent_configs toneAmber
class node_worktree,node_change_engine,node_change_flow,node_task_store,node_change_config toneMint
class node_review_contract,node_review_storage,node_checkpoint,node_receipt_store,node_codec toneRose
class node_wizard,node_wizard_logic,node_overrides,node_user toneIndigo
```

## Components

### CLI and Commands

- [Command CLI](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/main.py): `src/ai_harness/main.py`
- [Repo Scaffolding](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/commands/init.py): `src/ai_harness/commands/init.py`
- [Install Command](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/commands/install.py): `src/ai_harness/commands/install.py`
- [Uninstall Command](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/commands/uninstall.py): `src/ai_harness/commands/uninstall.py`
- [Model Command](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/commands/set_models.py): `src/ai_harness/commands/set_models.py`
- [Worktree Commands](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/commands/worktree.py): `src/ai_harness/commands/worktree.py`
- [Change Commands](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/commands/change.py): `src/ai_harness/commands/change.py`

### Artifact Distribution

- [Artifact Operations](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/operations.py): `src/ai_harness/modules/harness/operations.py`
- [Provider Dispatch](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/administrators/__init__.py): `src/ai_harness/modules/harness/administrators/__init__.py`
- [Provider Renderers](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/administrators/base.py): `src/ai_harness/modules/harness/administrators/base.py`
- **Agent Config Homes**

### Change Sessions

- [Git Worktree Logic](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/worktree.py): `src/ai_harness/modules/harness/worktree.py`
- [Change Engine](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/change.py): `src/ai_harness/modules/harness/change.py`
- [Change Flow](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/change_flow.py): `src/ai_harness/modules/harness/change_flow.py`
- [Task Store](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/tasks.py): `src/ai_harness/modules/harness/tasks.py`
- [Change Config](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/change_config/models.py): `src/ai_harness/modules/change_config/models.py`

### Review Contracts

- [Review Contracts](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/review_transactions.py): `src/ai_harness/modules/harness/review_transactions.py`
- [Review Persistence](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/review_transaction_storage.py): `src/ai_harness/modules/harness/review_transaction_storage.py`
- [Review Checkpoints](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/review_transaction_checkpoints.py): `src/ai_harness/modules/harness/review_transaction_checkpoints.py`
- [Receipts and Evidence](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/receipts.py): `src/ai_harness/modules/harness/receipts.py`
- [Shared Review Codec](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/_review_contract_codec_shared.py): `src/ai_harness/modules/harness/_review_contract_codec_shared.py`

### Configuration

- [Model Wizard](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/wizard/tui.py): `src/ai_harness/modules/wizard/tui.py`
- [Wizard Data Logic](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/wizard/pure.py): `src/ai_harness/modules/wizard/pure.py`
- [Model Overrides](https://github.com/diegoagd10/ai-harness/blob/main/src/ai_harness/modules/harness/override_store.py): `src/ai_harness/modules/harness/override_store.py`

### Other components

- **Engineer**

## Connections

- Engineer → Command CLI: runs commands (evidence: `README.md`)
- Command CLI → Repo Scaffolding: dispatches (evidence: `src/ai_harness/main.py`)
- Command CLI → Install Command: dispatches (evidence: `src/ai_harness/main.py`)
- Command CLI → Uninstall Command: dispatches (evidence: `src/ai_harness/main.py`)
- Command CLI → Model Command: dispatches (evidence: `src/ai_harness/main.py`)
- Command CLI → Worktree Commands: dispatches (evidence: `src/ai_harness/main.py`)
- Command CLI → Change Commands: dispatches (evidence: `src/ai_harness/main.py`)
- Repo Scaffolding → Change Config: scaffolds (evidence: `src/ai_harness/commands/init.py`)
- Install Command → Artifact Operations: installs
- Uninstall Command → Artifact Operations: removes artifacts
- Artifact Operations → Provider Dispatch: selects provider (evidence: `src/ai_harness/modules/harness/administrators/__init__.py`)
- Provider Dispatch → Provider Renderers: dispatches render (evidence: `src/ai_harness/modules/harness/administrators/__init__.py`)
- Artifact Operations → Agent Config Homes: writes artifacts (evidence: `README.md`)
- Model Command → Model Wizard: starts wizard (evidence: `src/ai_harness/commands/set_models.py`)
- Model Wizard → Wizard Data Logic: uses data logic (evidence: `src/ai_harness/modules/wizard/tui.py`)
- Model Wizard → Provider Dispatch: reads metadata (evidence: `src/ai_harness/modules/wizard/tui.py`)
- Model Wizard → Model Overrides: persists choices (evidence: `src/ai_harness/modules/wizard/tui.py`)
- Worktree Commands → Git Worktree Logic: creates worktrees (evidence: `src/ai_harness/commands/worktree.py`)
- Change Commands → Change Engine: invokes change operations (evidence: `src/ai_harness/commands/change.py`)
- Change Commands → Task Store: invokes task operations (evidence: `src/ai_harness/commands/change.py`)
- Change Engine → Change Flow: uses flow (evidence: `src/ai_harness/modules/harness/change.py`)
- Change Engine → Task Store: uses task store (evidence: `src/ai_harness/modules/harness/change.py`)
- Change Engine → Change Config: uses config models (evidence: `src/ai_harness/modules/harness/change.py`)
- Review Persistence → Review Contracts: encodes records (evidence: `src/ai_harness/modules/harness/review_transaction_storage.py`)
- Review Persistence → Receipts and Evidence: publishes bundles (evidence: `src/ai_harness/modules/harness/review_transaction_storage.py`)
- Review Checkpoints → Shared Review Codec: uses codec (evidence: `src/ai_harness/modules/harness/review_transaction_checkpoints.py`)
- Review Checkpoints → Review Persistence: uses storage errors (evidence: `src/ai_harness/modules/harness/review_transaction_checkpoints.py`)
- Review Checkpoints → Receipts and Evidence: publishes evidence (evidence: `src/ai_harness/modules/harness/review_transaction_checkpoints.py`)
