# alexeyv/chainsaw architecture

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

- Interactive diagram: https://gitdiagram.com/alexeyv/chainsaw
- Repository: https://github.com/alexeyv/chainsaw

## Overview

Chainsaw is a Rust supervisor for continuously coordinating spec-driven coding runs across LLM sessions. A human starts and steers a run; the lead creates and dispatches tasks, implementers produce commits, and the commentator reports observations or findings for the lead to address. The supervisor tracks sessions, prompts, task state, and review data in SQLite while using a terminal runtime and agent-specific transcripts. The README documents the overall roles and loop; sampled source confirms task/review persistence and session abstractions, but not every coordinator dispatch or integration call.

Main entry points: [`skills/chainsaw/coordinator/src/coordinator/sessions.rs`](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/coordinator/sessions.rs) (Session coordination), [`skills/chainsaw/coordinator/src/coordinator/review.rs`](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/coordinator/review.rs) (Review exchange), [`skills/chainsaw/coordinator/src/coordinator.rs`](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/coordinator.rs) (Lead coordination), [`skills/chainsaw/coordinator/src/coordinator/tasks.rs`](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/coordinator/tasks.rs) (Task lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_coord["Run coordination"]
  node_cli["Supervisor CLI<br/>[cli.rs]"]
  node_daemon["Run daemon<br/>[daemon.rs]"]
  node_lead["Lead coordination<br/>[coordinator.rs]"]
end

subgraph group_work["Task and review"]
  node_taskflow["Task lifecycle<br/>[tasks.rs]"]
  node_review["Review exchange<br/>[review.rs]"]
  node_git["Git operations<br/>[git.rs]"]
  node_calibration["Task calibration<br/>[calibrate.rs]"]
end

subgraph group_sessions["Agent sessions"]
  node_sessioncoord["Session coordination<br/>[sessions.rs]"]
  node_promptcoord["Prompt handling<br/>[prompt.rs]"]
  node_agent["Agent adapters<br/>[agent.rs]"]
  node_runtime["Terminal runtime<br/>[session_runtime.rs]"]
  node_transcript["Transcript monitor"]
  node_sessiondomain["Session model<br/>[session.rs]"]
end

subgraph group_state["Run state"]
  node_domain["Run/task models<br/>[task.rs]"]
  node_store[("SQLite store<br/>[store.rs]")]
  node_taskdb["Task records<br/>[task.rs]"]
  node_sessiondb["Session records<br/>[session.rs]"]
  node_reviewdb["Review records<br/>[finding.rs]"]
  node_observationdb["Observations<br/>[observation.rs]"]
  node_promptdb["Prompt records<br/>[prompt.rs]"]
end

node_human(("Human"))

node_human -->|"starts and steers"| node_cli
node_cli -.->|"runs"| node_daemon
node_daemon -.->|"coordinates run"| node_lead
node_lead -->|"creates and dispatches"| node_taskflow
node_taskflow -->|"reads and writes"| node_taskdb
node_taskflow -.->|"checks repository"| node_git
node_lead -->|"hands out work"| node_sessioncoord
node_sessioncoord -->|"reads and writes"| node_sessiondb
node_sessioncoord -.->|"controls sessions"| node_runtime
node_sessioncoord -->|"monitors transcripts"| node_transcript
node_sessioncoord -.->|"uses agent adapters"| node_agent
node_agent -->|"starts sessions"| node_runtime
node_agent -->|"reads transcripts"| node_transcript
node_sessiondb -->|"materializes"| node_sessiondomain
node_promptcoord -->|"tracks prompts"| node_promptdb
node_lead -->|"receives findings"| node_review
node_review -->|"reads and writes"| node_reviewdb
node_review -->|"reads and writes"| node_observationdb
node_review -->|"validates task"| node_taskdb
node_store -->|"hosts records"| node_taskdb
node_store -->|"hosts records"| node_sessiondb
node_git -.->|"supports commit checks"| node_taskflow
node_calibration -.->|"records estimates"| node_store
node_human -->|"observes and steers"| node_review

click node_cli "https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/cli.rs"
click node_daemon "https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/coordinator/daemon.rs"
click node_lead "https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/coordinator.rs"
click node_taskflow "https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/coordinator/tasks.rs"
click node_review "https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/coordinator/review.rs"
click node_git "https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/infra/git.rs"
click node_calibration "https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/coordinator/calibrate.rs"
click node_sessioncoord "https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/coordinator/sessions.rs"
click node_promptcoord "https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/coordinator/prompt.rs"
click node_agent "https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/infra/agent.rs"
click node_runtime "https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/infra/session_runtime.rs"
click node_transcript "https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/infra/transcript_monitor.rs"
click node_sessiondomain "https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/domain/session.rs"
click node_domain "https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/domain/task.rs"
click node_store "https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/persistence/store.rs"
click node_taskdb "https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/persistence/task.rs"
click node_sessiondb "https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/persistence/session.rs"
click node_reviewdb "https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/persistence/finding.rs"
click node_observationdb "https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/persistence/observation.rs"
click node_promptdb "https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/persistence/prompt.rs"

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_daemon,node_lead toneBlue
class node_taskflow,node_review,node_git,node_calibration toneAmber
class node_sessioncoord,node_promptcoord,node_agent,node_runtime,node_transcript,node_sessiondomain toneMint
class node_domain,node_store,node_taskdb,node_sessiondb,node_reviewdb,node_observationdb,node_promptdb toneRose
class node_human toneIndigo
```

## Components

### Run coordination

- [Supervisor CLI](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/cli.rs): `skills/chainsaw/coordinator/src/cli.rs`
- [Run daemon](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/coordinator/daemon.rs): `skills/chainsaw/coordinator/src/coordinator/daemon.rs`
- [Lead coordination](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/coordinator.rs): `skills/chainsaw/coordinator/src/coordinator.rs`

### Task and review

- [Task lifecycle](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/coordinator/tasks.rs): `skills/chainsaw/coordinator/src/coordinator/tasks.rs`
- [Review exchange](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/coordinator/review.rs): `skills/chainsaw/coordinator/src/coordinator/review.rs`
- [Git operations](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/infra/git.rs): `skills/chainsaw/coordinator/src/infra/git.rs`
- [Task calibration](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/coordinator/calibrate.rs): `skills/chainsaw/coordinator/src/coordinator/calibrate.rs`

### Agent sessions

- [Session coordination](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/coordinator/sessions.rs): `skills/chainsaw/coordinator/src/coordinator/sessions.rs`
- [Prompt handling](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/coordinator/prompt.rs): `skills/chainsaw/coordinator/src/coordinator/prompt.rs`
- [Agent adapters](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/infra/agent.rs): `skills/chainsaw/coordinator/src/infra/agent.rs`
- [Terminal runtime](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/infra/session_runtime.rs): `skills/chainsaw/coordinator/src/infra/session_runtime.rs`
- [Transcript monitor](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/infra/transcript_monitor.rs): `skills/chainsaw/coordinator/src/infra/transcript_monitor.rs`
- [Session model](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/domain/session.rs): `skills/chainsaw/coordinator/src/domain/session.rs`

### Run state

- [Run/task models](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/domain/task.rs): `skills/chainsaw/coordinator/src/domain/task.rs`
- [SQLite store](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/persistence/store.rs): `skills/chainsaw/coordinator/src/persistence/store.rs`
- [Task records](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/persistence/task.rs): `skills/chainsaw/coordinator/src/persistence/task.rs`
- [Session records](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/persistence/session.rs): `skills/chainsaw/coordinator/src/persistence/session.rs`
- [Review records](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/persistence/finding.rs): `skills/chainsaw/coordinator/src/persistence/finding.rs`
- [Observations](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/persistence/observation.rs): `skills/chainsaw/coordinator/src/persistence/observation.rs`
- [Prompt records](https://github.com/alexeyv/chainsaw/blob/main/skills/chainsaw/coordinator/src/persistence/prompt.rs): `skills/chainsaw/coordinator/src/persistence/prompt.rs`

### Other components

- **Human**

## Connections

- Human → Supervisor CLI: starts and steers
- Supervisor CLI → Run daemon: runs
- Run daemon → Lead coordination: coordinates run
- Lead coordination → Task lifecycle: creates and dispatches
- Task lifecycle → Task records: reads and writes (evidence: `skills/chainsaw/coordinator/src/coordinator/tasks.rs`)
- Task lifecycle → Git operations: checks repository
- Lead coordination → Session coordination: hands out work
- Session coordination → Session records: reads and writes (evidence: `skills/chainsaw/coordinator/src/coordinator/sessions.rs`)
- Session coordination → Terminal runtime: controls sessions
- Session coordination → Transcript monitor: monitors transcripts (evidence: `skills/chainsaw/coordinator/src/coordinator/sessions.rs`)
- Session coordination → Agent adapters: uses agent adapters
- Agent adapters → Terminal runtime: starts sessions (evidence: `skills/chainsaw/coordinator/src/infra/agent.rs`)
- Agent adapters → Transcript monitor: reads transcripts (evidence: `skills/chainsaw/coordinator/src/infra/agent.rs`)
- Session records → Session model: materializes (evidence: `skills/chainsaw/coordinator/src/persistence/session.rs`)
- Prompt handling → Prompt records: tracks prompts
- Lead coordination → Review exchange: receives findings
- Review exchange → Review records: reads and writes (evidence: `skills/chainsaw/coordinator/src/coordinator/review.rs`)
- Review exchange → Observations: reads and writes (evidence: `skills/chainsaw/coordinator/src/coordinator/review.rs`)
- Review exchange → Task records: validates task (evidence: `skills/chainsaw/coordinator/src/coordinator/review.rs`)
- SQLite store → Task records: hosts records (evidence: `skills/chainsaw/coordinator/src/persistence/store.rs`)
- SQLite store → Session records: hosts records (evidence: `skills/chainsaw/coordinator/src/persistence/store.rs`)
- Git operations → Task lifecycle: supports commit checks
- Task calibration → SQLite store: records estimates
- Human → Review exchange: observes and steers
