# evolutionairy-ai/mindlas architecture

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

- Interactive diagram: https://gitdiagram.com/evolutionairy-ai/mindlas
- Repository: https://github.com/evolutionairy-ai/mindlas

## Overview

Mindlas is a local, deterministic reliability instrument for long-running Claude Code sessions. Hooks capture session activity into an event ledger; four independent gauges measure deterioration and surface paired corrections. The CLI runs those corrections and exposes status and reports, while the status line presents live readings. README capabilities fill in the hook, status-line, and gauge branches where source excerpts were not sampled; their exact wiring is therefore shown only where documented.

Main entry points: [`src/mindlas/cli.py`](https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/cli.py) (Mindlas CLI), [`src/mindlas/runtime`](https://github.com/evolutionairy-ai/mindlas/tree/main/src/mindlas/runtime) (Signal builders), [`src/mindlas/vitals/hooks.py`](https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/vitals/hooks.py) (Hook dispatch), [`src/mindlas/vitals/ledger.py`](https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/vitals/ledger.py) (Event ledger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Session capture"]
  node_hooks["Hook dispatch<br/>[hooks.py]"]
  node_capture_events["Event capture<br/>[capture.py]"]
  node_ledger[("Event ledger<br/>[ledger.py]")]
end

subgraph group_gauges["Risk gauges"]
  node_rot["Context Rot<br/>[context_rot.py]"]
  node_verify["Verification Debt"]
  node_blast["Blast Radius<br/>[blast_radius.py]"]
  node_loop["Tool Failure Loop"]
  node_runtime_state["Signal builders"]
end

subgraph group_corrections["Corrections"]
  node_repair["Context Repair<br/>[context_repair.py]"]
  node_verify_gate["Verify Gate<br/>[verify_gate.py]"]
  node_splitter["Patch Splitter<br/>[patch_splitter.py]"]
  node_loop_stop["Loop Stop<br/>[loop_stop.py]"]
end

subgraph group_reporting["CLI and reporting"]
  node_cli["Mindlas CLI<br/>[cli.py]"]
  node_statusline["Status line<br/>[statusline.py]"]
  node_scorecard["Scorecard export<br/>[scorecard.py]"]
end

node_claude(("Claude Code"))

node_claude -->|"sends events"| node_hooks
node_hooks -->|"captures activity"| node_capture_events
node_hooks -->|"records events"| node_ledger
node_ledger -->|"provides events"| node_runtime_state
node_runtime_state -->|"builds signals"| node_rot
node_runtime_state -->|"builds signals"| node_verify
node_runtime_state -->|"builds signals"| node_blast
node_runtime_state -->|"builds signals"| node_loop
node_rot -->|"pairs correction"| node_repair
node_verify -->|"pairs correction"| node_verify_gate
node_blast -->|"pairs correction"| node_splitter
node_loop -->|"pairs correction"| node_loop_stop
node_claude -->|"invokes commands"| node_cli
node_cli -->|"runs correction"| node_repair
node_cli -->|"runs correction"| node_verify_gate
node_cli -->|"runs correction"| node_splitter
node_cli -->|"runs correction"| node_loop_stop
node_statusline -->|"reads events"| node_ledger
node_statusline -->|"builds readings"| node_runtime_state
node_repair -->|"writes report"| node_scorecard
node_verify_gate -->|"writes report"| node_scorecard
node_cli -->|"shows report"| node_scorecard

click node_hooks "https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/vitals/hooks.py"
click node_capture_events "https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/vitals/capture.py"
click node_ledger "https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/vitals/ledger.py"
click node_rot "https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/features/context_rot.py"
click node_verify "https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/features/verification_debt.py"
click node_blast "https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/features/blast_radius.py"
click node_loop "https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/features/tool_failure_loop.py"
click node_repair "https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/actions/context_repair.py"
click node_verify_gate "https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/actions/verify_gate.py"
click node_splitter "https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/actions/patch_splitter.py"
click node_loop_stop "https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/actions/loop_stop.py"
click node_runtime_state "https://github.com/evolutionairy-ai/mindlas/tree/main/src/mindlas/runtime"
click node_cli "https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/cli.py"
click node_statusline "https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/vitals/statusline.py"
click node_scorecard "https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/runtime/scorecard.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_hooks,node_capture_events,node_ledger toneBlue
class node_rot,node_verify,node_blast,node_loop,node_runtime_state toneAmber
class node_repair,node_verify_gate,node_splitter,node_loop_stop toneMint
class node_cli,node_statusline,node_scorecard toneRose
class node_claude toneIndigo
```

## Components

### Session capture

- [Hook dispatch](https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/vitals/hooks.py): `src/mindlas/vitals/hooks.py`
- [Event capture](https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/vitals/capture.py): `src/mindlas/vitals/capture.py`
- [Event ledger](https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/vitals/ledger.py): `src/mindlas/vitals/ledger.py`

### Risk gauges

- [Context Rot](https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/features/context_rot.py): `src/mindlas/features/context_rot.py`
- [Verification Debt](https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/features/verification_debt.py): `src/mindlas/features/verification_debt.py`
- [Blast Radius](https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/features/blast_radius.py): `src/mindlas/features/blast_radius.py`
- [Tool Failure Loop](https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/features/tool_failure_loop.py): `src/mindlas/features/tool_failure_loop.py`
- [Signal builders](https://github.com/evolutionairy-ai/mindlas/tree/main/src/mindlas/runtime): `src/mindlas/runtime`

### Corrections

- [Context Repair](https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/actions/context_repair.py): `src/mindlas/actions/context_repair.py`
- [Verify Gate](https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/actions/verify_gate.py): `src/mindlas/actions/verify_gate.py`
- [Patch Splitter](https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/actions/patch_splitter.py): `src/mindlas/actions/patch_splitter.py`
- [Loop Stop](https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/actions/loop_stop.py): `src/mindlas/actions/loop_stop.py`

### CLI and reporting

- [Mindlas CLI](https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/cli.py): `src/mindlas/cli.py`
- [Status line](https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/vitals/statusline.py): `src/mindlas/vitals/statusline.py`
- [Scorecard export](https://github.com/evolutionairy-ai/mindlas/blob/main/src/mindlas/runtime/scorecard.py): `src/mindlas/runtime/scorecard.py`

### Other components

- **Claude Code**

## Connections

- Claude Code → Hook dispatch: sends events
- Hook dispatch → Event capture: captures activity
- Hook dispatch → Event ledger: records events
- Event ledger → Signal builders: provides events
- Signal builders → Context Rot: builds signals
- Signal builders → Verification Debt: builds signals
- Signal builders → Blast Radius: builds signals
- Signal builders → Tool Failure Loop: builds signals
- Context Rot → Context Repair: pairs correction
- Verification Debt → Verify Gate: pairs correction
- Blast Radius → Patch Splitter: pairs correction
- Tool Failure Loop → Loop Stop: pairs correction
- Claude Code → Mindlas CLI: invokes commands
- Mindlas CLI → Context Repair: runs correction
- Mindlas CLI → Verify Gate: runs correction
- Mindlas CLI → Patch Splitter: runs correction
- Mindlas CLI → Loop Stop: runs correction
- Status line → Event ledger: reads events
- Status line → Signal builders: builds readings
- Context Repair → Scorecard export: writes report
- Verify Gate → Scorecard export: writes report
- Mindlas CLI → Scorecard export: shows report