# tigerless-labs/autoharness architecture

> Architecture diagram of the GitHub repository tigerless-labs/autoharness, 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/tigerless-labs/autoharness
- Repository: https://github.com/tigerless-labs/autoharness

## Overview

AutoHarness is a Claude Code skill layer that learns from sessions and maintains its own skill library. Its main flow captures and redacts session activity, launches a reflector to propose changes, queues those proposals, and uses a deterministic promoter to validate and land them. Session-start recall and lifecycle review, curator consolidation, and usage evidence support the ongoing library. Several connections are documented or indicated by the SOURCE INDEX; unsampled implementations are represented at their existing source paths, and uncertain links are omitted.

Main entry points: [`src/autoharness/hook/promoter.py`](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/hook/promoter.py) (Deterministic promoter), [`src/autoharness/hook/on_session_start.py`](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/hook/on_session_start.py) (Session start), [`src/autoharness/hook/dispatch.py`](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/hook/dispatch.py) (Hook dispatch), [`src/autoharness/hook/spawn.py`](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/hook/spawn.py) (Reflector and curator launch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_session["Session hooks"]
  node_dispatch["Hook dispatch<br/>[dispatch.py]"]
  node_capture["Session capture<br/>[capture.py]"]
  node_session_start["Session start"]
  node_skill_call["Skill-use tracking<br/>[on_skill_call.py]"]
  node_stop_end["Stop and session end<br/>[on_stop.py]"]
end

subgraph group_learning["Learning and review"]
  node_spawn["Reflector and curator launch<br/>[spawn.py]"]
  node_reflector["Reflector agent<br/>[reflector.md]"]
  node_curator["Curator agent<br/>[curator.md]"]
end

subgraph group_admission["Proposal admission"]
  node_stage["Stage-skill MCP tool<br/>[server.py]"]
  node_queue["Intent queue<br/>[intent_queue.py]"]
  node_promoter["Deterministic promoter<br/>[promoter.py]"]
  node_validate["Skill validation<br/>[validate.py]"]
end

subgraph group_library["Skill library"]
  node_skills[("Skill files and archives<br/>[skill_store.py]")]
  node_sidecar[("Skill metadata<br/>[sidecar.py]")]
  node_ledger[("Decision ledger<br/>[ledger.py]")]
  node_lifecycle["Lifecycle review<br/>[lifecycle.py]"]
  node_metrics["Usage metrics<br/>[metrics.py]"]
end

subgraph group_support["Shared runtime"]
  node_layer["Layer paths<br/>[layer.py]"]
  node_counters[("Session counters<br/>[counters.py]")]
  node_redact["Redaction<br/>[redact.py]"]
  node_atomic["Atomic writes<br/>[atomic.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_notify["Run notifications<br/>[notify.py]"]
end

node_user(("Claude Code user"))
node_claude(("Claude Code"))

node_user -->|"works in"| node_claude
node_claude -.->|"fires hooks"| node_dispatch
node_dispatch -->|"dispatches"| node_session_start
node_dispatch -->|"dispatches"| node_skill_call
node_dispatch -->|"dispatches"| node_stop_end
node_dispatch -->|"dispatches"| node_promoter
node_claude -.->|"provides session activity"| node_capture
node_capture -->|"redacts activity"| node_redact
node_session_start -->|"reviews skills"| node_lifecycle
node_session_start -->|"reads and archives"| node_skills
node_session_start -->|"reads ownership and counters"| node_sidecar
node_session_start -->|"reads request counts"| node_counters
node_skill_call -->|"records use"| node_sidecar
node_stop_end -->|"updates cadence"| node_counters
node_stop_end -.->|"triggers learning"| node_spawn
node_capture -->|"supplies episode"| node_spawn
node_spawn -->|"launches"| node_reflector
node_spawn -->|"launches periodic pass"| node_curator
node_reflector -->|"proposes skill changes"| node_stage
node_user -->|"requests /learn"| node_stage
node_stage -->|"front-checks proposals"| node_validate
node_stage -.->|"appends intents"| node_queue
node_spawn -.->|"drains run intents"| node_queue
node_promoter -.->|"reads intents"| node_queue
node_promoter -->|"validates shaped changes"| node_validate
node_promoter -->|"lands or archives"| node_skills
node_promoter -->|"updates metadata"| node_sidecar
node_promoter -->|"records decisions"| node_ledger
node_promoter -->|"reads request count"| node_counters
node_promoter -->|"redacts evidence"| node_redact
node_curator -.->|"consolidates library"| node_skills
node_metrics -->|"reads usage data"| node_sidecar
node_metrics -->|"reads decisions"| node_ledger
node_session_start -.->|"provides lifecycle inputs"| node_metrics
node_config -->|"uses layer definitions"| node_layer
node_skills -->|"writes atomically"| node_atomic
node_sidecar -->|"writes atomically"| node_atomic
node_counters -->|"writes atomically"| node_atomic
node_promoter -.->|"reports run outcome"| node_notify

click node_dispatch "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/hook/dispatch.py"
click node_capture "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/hook/capture.py"
click node_session_start "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/hook/on_session_start.py"
click node_skill_call "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/hook/on_skill_call.py"
click node_stop_end "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/hook/on_stop.py"
click node_spawn "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/hook/spawn.py"
click node_reflector "https://github.com/tigerless-labs/autoharness/blob/main/agents/reflector.md"
click node_curator "https://github.com/tigerless-labs/autoharness/blob/main/agents/curator.md"
click node_stage "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/stage_skill/server.py"
click node_queue "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/intent_queue.py"
click node_promoter "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/hook/promoter.py"
click node_validate "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/validate.py"
click node_skills "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/skill_store.py"
click node_sidecar "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/sidecar.py"
click node_ledger "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/ledger.py"
click node_lifecycle "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/lifecycle.py"
click node_metrics "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/metrics.py"
click node_layer "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/layer.py"
click node_counters "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/counters.py"
click node_redact "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/redact.py"
click node_atomic "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/atomic.py"
click node_config "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/config.py"
click node_notify "https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/notify.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_dispatch,node_capture,node_session_start,node_skill_call,node_stop_end,node_user toneBlue
class node_spawn,node_reflector,node_curator toneAmber
class node_stage,node_queue,node_promoter,node_validate toneMint
class node_skills,node_sidecar,node_ledger,node_lifecycle,node_metrics toneRose
class node_layer,node_counters,node_redact,node_atomic,node_config,node_notify,node_claude toneIndigo
```

## Components

### Session hooks

- [Hook dispatch](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/hook/dispatch.py): `src/autoharness/hook/dispatch.py`
- [Session capture](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/hook/capture.py): `src/autoharness/hook/capture.py`
- [Session start](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/hook/on_session_start.py): `src/autoharness/hook/on_session_start.py`
- [Skill-use tracking](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/hook/on_skill_call.py): `src/autoharness/hook/on_skill_call.py`
- [Stop and session end](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/hook/on_stop.py): `src/autoharness/hook/on_stop.py`

### Learning and review

- [Reflector and curator launch](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/hook/spawn.py): `src/autoharness/hook/spawn.py`
- [Reflector agent](https://github.com/tigerless-labs/autoharness/blob/main/agents/reflector.md): `agents/reflector.md`
- [Curator agent](https://github.com/tigerless-labs/autoharness/blob/main/agents/curator.md): `agents/curator.md`

### Proposal admission

- [Stage-skill MCP tool](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/stage_skill/server.py): `src/autoharness/stage_skill/server.py`
- [Intent queue](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/intent_queue.py): `src/autoharness/lib/intent_queue.py`
- [Deterministic promoter](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/hook/promoter.py): `src/autoharness/hook/promoter.py`
- [Skill validation](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/validate.py): `src/autoharness/lib/validate.py`

### Skill library

- [Skill files and archives](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/skill_store.py): `src/autoharness/lib/skill_store.py`
- [Skill metadata](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/sidecar.py): `src/autoharness/lib/sidecar.py`
- [Decision ledger](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/ledger.py): `src/autoharness/lib/ledger.py`
- [Lifecycle review](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/lifecycle.py): `src/autoharness/lib/lifecycle.py`
- [Usage metrics](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/metrics.py): `src/autoharness/lib/metrics.py`

### Shared runtime

- [Layer paths](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/layer.py): `src/autoharness/lib/layer.py`
- [Session counters](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/counters.py): `src/autoharness/lib/counters.py`
- [Redaction](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/redact.py): `src/autoharness/lib/redact.py`
- [Atomic writes](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/atomic.py): `src/autoharness/lib/atomic.py`
- [Runtime configuration](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/config.py): `src/autoharness/config.py`
- [Run notifications](https://github.com/tigerless-labs/autoharness/blob/main/src/autoharness/lib/notify.py): `src/autoharness/lib/notify.py`

### Other components

- **Claude Code user**
- **Claude Code**

## Connections

- Claude Code user → Claude Code: works in (evidence: `README.md`)
- Claude Code → Hook dispatch: fires hooks
- Hook dispatch → Session start: dispatches (evidence: `src/autoharness/hook/dispatch.py`)
- Hook dispatch → Skill-use tracking: dispatches (evidence: `src/autoharness/hook/dispatch.py`)
- Hook dispatch → Stop and session end: dispatches (evidence: `src/autoharness/hook/dispatch.py`)
- Hook dispatch → Deterministic promoter: dispatches (evidence: `src/autoharness/hook/dispatch.py`)
- Claude Code → Session capture: provides session activity
- Session capture → Redaction: redacts activity (evidence: `src/autoharness/hook/capture.py`)
- Session start → Lifecycle review: reviews skills (evidence: `src/autoharness/hook/on_session_start.py`)
- Session start → Skill files and archives: reads and archives (evidence: `src/autoharness/hook/on_session_start.py`)
- Session start → Skill metadata: reads ownership and counters (evidence: `src/autoharness/hook/on_session_start.py`)
- Session start → Session counters: reads request counts (evidence: `src/autoharness/hook/on_session_start.py`)
- Skill-use tracking → Skill metadata: records use (evidence: `src/autoharness/hook/on_skill_call.py`)
- Stop and session end → Session counters: updates cadence (evidence: `src/autoharness/hook/on_stop.py`)
- Stop and session end → Reflector and curator launch: triggers learning
- Session capture → Reflector and curator launch: supplies episode (evidence: `src/autoharness/hook/spawn.py`)
- Reflector and curator launch → Reflector agent: launches (evidence: `src/autoharness/hook/spawn.py`)
- Reflector and curator launch → Curator agent: launches periodic pass (evidence: `src/autoharness/hook/spawn.py`)
- Reflector agent → Stage-skill MCP tool: proposes skill changes (evidence: `README.md`)
- Claude Code user → Stage-skill MCP tool: requests /learn (evidence: `README.md`)
- Stage-skill MCP tool → Skill validation: front-checks proposals (evidence: `src/autoharness/stage_skill/server.py`)
- Stage-skill MCP tool → Intent queue: appends intents (evidence: `src/autoharness/stage_skill/server.py`)
- Reflector and curator launch → Intent queue: drains run intents
- Deterministic promoter → Intent queue: reads intents (evidence: `src/autoharness/hook/promoter.py`)
- Deterministic promoter → Skill validation: validates shaped changes (evidence: `src/autoharness/hook/promoter.py`)
- Deterministic promoter → Skill files and archives: lands or archives (evidence: `src/autoharness/hook/promoter.py`)
- Deterministic promoter → Skill metadata: updates metadata (evidence: `src/autoharness/hook/promoter.py`)
- Deterministic promoter → Decision ledger: records decisions (evidence: `src/autoharness/hook/promoter.py`)
- Deterministic promoter → Session counters: reads request count (evidence: `src/autoharness/hook/promoter.py`)
- Deterministic promoter → Redaction: redacts evidence (evidence: `src/autoharness/hook/promoter.py`)
- Curator agent → Skill files and archives: consolidates library
- Usage metrics → Skill metadata: reads usage data (evidence: `src/autoharness/lib/metrics.py`)
- Usage metrics → Decision ledger: reads decisions (evidence: `src/autoharness/lib/metrics.py`)
- Session start → Usage metrics: provides lifecycle inputs
- Runtime configuration → Layer paths: uses layer definitions (evidence: `src/autoharness/config.py`)
- Skill files and archives → Atomic writes: writes atomically (evidence: `src/autoharness/lib/skill_store.py`)
- Skill metadata → Atomic writes: writes atomically (evidence: `src/autoharness/lib/sidecar.py`)
- Session counters → Atomic writes: writes atomically (evidence: `src/autoharness/lib/counters.py`)
- Deterministic promoter → Run notifications: reports run outcome (evidence: `src/autoharness/hook/promoter.py`)
