# thruwire/foreman architecture

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

- Interactive diagram: https://gitdiagram.com/thruwire/foreman
- Repository: https://github.com/thruwire/foreman

## Overview

Foreman supervises coding-agent work: a user supplies a software job, a worker performs it, and Foreman repeatedly observes factory evidence, assesses progress, and applies policy to continue, steer, verify, retry, finish, or escalate. The runtime coordinates routing, worker lifecycle, observation, assessment, and interventions. Responsibilities supply pluggable checks and directives; worker backends and attached-worker hooks are additional product capabilities. Connections below follow README descriptions and source-index references; unsampled implementations are represented only where the README documents their role.

Main entry points: [`src/foreman/runtime.py`](https://github.com/thruwire/foreman/blob/main/src/foreman/runtime.py) (Factory runtime), [`src/foreman/workers/base.py`](https://github.com/thruwire/foreman/blob/main/src/foreman/workers/base.py) (Worker protocol), [`src/foreman/observation.py`](https://github.com/thruwire/foreman/blob/main/src/foreman/observation.py) (Observation builder), [`src/foreman/foreman/jev.py`](https://github.com/thruwire/foreman/blob/main/src/foreman/foreman/jev.py) (Jev assessor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Factory orchestration"]
  node_cli["Command interface<br/>[cli.py]"]
  node_runtime["Factory runtime<br/>[runtime.py]"]
  node_steering["Live steering<br/>[steering.py]"]
end

subgraph group_assessment["Assessment and policy"]
  node_routing["Responsibility routing<br/>[routing.py]"]
  node_responsibilities["Responsibilities<br/>[builtin.py]"]
  node_responsibility_config["Check configuration<br/>[configuration.py]"]
  node_jev_assessor["Jev assessor<br/>[jev.py]"]
  node_simulation_assessor["Simulation assessor<br/>[simulation.py]"]
  node_policy["Intervention policy<br/>[policy.py]"]
end

subgraph group_workers["Worker execution"]
  node_worker_protocol["Worker protocol<br/>[base.py]"]
  node_codex_app["Codex App Server"]
  node_codex_exec["Codex exec<br/>[codex.py]"]
  node_opencode["OpenCode worker<br/>[opencode.py]"]
  node_hermes["Hermes worker<br/>[hermes.py]"]
end

subgraph group_evidence["Evidence and state"]
  node_observation["Observation builder<br/>[observation.py]"]
  node_command_evidence["Command evidence<br/>[evidence.py]"]
  node_run_store[("Run persistence<br/>[persistence.py]")]
  node_state_models["Factory state models<br/>[state.py]"]
end

subgraph group_integrations["Extensions and hooks"]
  node_hook_runtime["Attached-worker hooks<br/>[hooks.py]"]
  node_hook_adapters["Hook adapters<br/>[hook_adapters.py]"]
  node_extensions["Extensions<br/>[extensions.py]"]
end

node_user(("Job submitter"))
node_jev_service["Jev service"]
node_agent_process(("Coding-agent process"))

node_user -->|"submits job"| node_cli
node_cli -->|"starts runtime"| node_runtime
node_runtime -->|"routes work"| node_routing
node_runtime -->|"starts workers"| node_worker_protocol
node_runtime -->|"builds observations"| node_observation
node_runtime -->|"assesses state"| node_jev_assessor
node_runtime -->|"chooses interventions"| node_policy
node_runtime -->|"persists state"| node_run_store
node_runtime -->|"steers workers"| node_steering
node_runtime -->|"updates state"| node_state_models
node_routing -->|"selects checks"| node_responsibilities
node_responsibility_config -->|"configures checks"| node_responsibilities
node_jev_assessor -->|"sends assessment"| node_jev_service
node_simulation_assessor -.->|"alternative assessor"| node_runtime
node_observation -->|"reads history"| node_run_store
node_observation -->|"collects commands"| node_command_evidence
node_command_evidence -->|"runs checks"| node_agent_process
node_worker_protocol -->|"implemented by"| node_codex_app
node_worker_protocol -->|"implemented by"| node_codex_exec
node_worker_protocol -->|"implemented by"| node_opencode
node_worker_protocol -->|"implemented by"| node_hermes
node_codex_app -->|"runs agent"| node_agent_process
node_codex_exec -->|"runs agent"| node_agent_process
node_opencode -->|"runs agent"| node_agent_process
node_hermes -->|"runs agent"| node_agent_process
node_hook_adapters -->|"normalizes events"| node_hook_runtime
node_extensions -->|"provides extensions"| node_responsibilities
node_hook_runtime -->|"assesses attached work"| node_jev_assessor

click node_cli "https://github.com/thruwire/foreman/blob/main/src/foreman/cli.py"
click node_runtime "https://github.com/thruwire/foreman/blob/main/src/foreman/runtime.py"
click node_routing "https://github.com/thruwire/foreman/blob/main/src/foreman/routing.py"
click node_responsibilities "https://github.com/thruwire/foreman/blob/main/src/foreman/responsibilities/builtin.py"
click node_responsibility_config "https://github.com/thruwire/foreman/blob/main/src/foreman/responsibilities/configuration.py"
click node_jev_assessor "https://github.com/thruwire/foreman/blob/main/src/foreman/foreman/jev.py"
click node_simulation_assessor "https://github.com/thruwire/foreman/blob/main/src/foreman/foreman/simulation.py"
click node_policy "https://github.com/thruwire/foreman/blob/main/src/foreman/policy.py"
click node_steering "https://github.com/thruwire/foreman/blob/main/src/foreman/steering.py"
click node_worker_protocol "https://github.com/thruwire/foreman/blob/main/src/foreman/workers/base.py"
click node_codex_app "https://github.com/thruwire/foreman/blob/main/src/foreman/workers/codex_app_server.py"
click node_codex_exec "https://github.com/thruwire/foreman/blob/main/src/foreman/workers/codex.py"
click node_opencode "https://github.com/thruwire/foreman/blob/main/src/foreman/workers/opencode.py"
click node_hermes "https://github.com/thruwire/foreman/blob/main/src/foreman/workers/hermes.py"
click node_observation "https://github.com/thruwire/foreman/blob/main/src/foreman/observation.py"
click node_command_evidence "https://github.com/thruwire/foreman/blob/main/src/foreman/evidence.py"
click node_run_store "https://github.com/thruwire/foreman/blob/main/src/foreman/persistence.py"
click node_state_models "https://github.com/thruwire/foreman/blob/main/src/foreman/models/state.py"
click node_hook_runtime "https://github.com/thruwire/foreman/blob/main/src/foreman/hooks.py"
click node_hook_adapters "https://github.com/thruwire/foreman/blob/main/src/foreman/hook_adapters.py"
click node_extensions "https://github.com/thruwire/foreman/blob/main/src/foreman/extensions.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_runtime,node_steering toneBlue
class node_routing,node_responsibilities,node_responsibility_config,node_jev_assessor,node_simulation_assessor,node_policy toneAmber
class node_worker_protocol,node_codex_app,node_codex_exec,node_opencode,node_hermes toneMint
class node_observation,node_command_evidence,node_run_store,node_state_models toneRose
class node_hook_runtime,node_hook_adapters,node_extensions,node_user,node_jev_service,node_agent_process toneIndigo
```

## Components

### Factory orchestration

- [Command interface](https://github.com/thruwire/foreman/blob/main/src/foreman/cli.py): `src/foreman/cli.py`
- [Factory runtime](https://github.com/thruwire/foreman/blob/main/src/foreman/runtime.py): `src/foreman/runtime.py`
- [Live steering](https://github.com/thruwire/foreman/blob/main/src/foreman/steering.py): `src/foreman/steering.py`

### Assessment and policy

- [Responsibility routing](https://github.com/thruwire/foreman/blob/main/src/foreman/routing.py): `src/foreman/routing.py`
- [Responsibilities](https://github.com/thruwire/foreman/blob/main/src/foreman/responsibilities/builtin.py): `src/foreman/responsibilities/builtin.py`
- [Check configuration](https://github.com/thruwire/foreman/blob/main/src/foreman/responsibilities/configuration.py): `src/foreman/responsibilities/configuration.py`
- [Jev assessor](https://github.com/thruwire/foreman/blob/main/src/foreman/foreman/jev.py): `src/foreman/foreman/jev.py`
- [Simulation assessor](https://github.com/thruwire/foreman/blob/main/src/foreman/foreman/simulation.py): `src/foreman/foreman/simulation.py`
- [Intervention policy](https://github.com/thruwire/foreman/blob/main/src/foreman/policy.py): `src/foreman/policy.py`

### Worker execution

- [Worker protocol](https://github.com/thruwire/foreman/blob/main/src/foreman/workers/base.py): `src/foreman/workers/base.py`
- [Codex App Server](https://github.com/thruwire/foreman/blob/main/src/foreman/workers/codex_app_server.py): `src/foreman/workers/codex_app_server.py`
- [Codex exec](https://github.com/thruwire/foreman/blob/main/src/foreman/workers/codex.py): `src/foreman/workers/codex.py`
- [OpenCode worker](https://github.com/thruwire/foreman/blob/main/src/foreman/workers/opencode.py): `src/foreman/workers/opencode.py`
- [Hermes worker](https://github.com/thruwire/foreman/blob/main/src/foreman/workers/hermes.py): `src/foreman/workers/hermes.py`

### Evidence and state

- [Observation builder](https://github.com/thruwire/foreman/blob/main/src/foreman/observation.py): `src/foreman/observation.py`
- [Command evidence](https://github.com/thruwire/foreman/blob/main/src/foreman/evidence.py): `src/foreman/evidence.py`
- [Run persistence](https://github.com/thruwire/foreman/blob/main/src/foreman/persistence.py): `src/foreman/persistence.py`
- [Factory state models](https://github.com/thruwire/foreman/blob/main/src/foreman/models/state.py): `src/foreman/models/state.py`

### Extensions and hooks

- [Attached-worker hooks](https://github.com/thruwire/foreman/blob/main/src/foreman/hooks.py): `src/foreman/hooks.py`
- [Hook adapters](https://github.com/thruwire/foreman/blob/main/src/foreman/hook_adapters.py): `src/foreman/hook_adapters.py`
- [Extensions](https://github.com/thruwire/foreman/blob/main/src/foreman/extensions.py): `src/foreman/extensions.py`

### Other components

- **Job submitter**
- **Jev service**
- **Coding-agent process**

## Connections

- Job submitter → Command interface: submits job (evidence: `README.md`)
- Command interface → Factory runtime: starts runtime (evidence: `src/foreman/cli.py`)
- Factory runtime → Responsibility routing: routes work (evidence: `src/foreman/runtime.py`)
- Factory runtime → Worker protocol: starts workers (evidence: `src/foreman/runtime.py`)
- Factory runtime → Observation builder: builds observations (evidence: `src/foreman/runtime.py`)
- Factory runtime → Jev assessor: assesses state (evidence: `src/foreman/runtime.py`)
- Factory runtime → Intervention policy: chooses interventions (evidence: `src/foreman/runtime.py`)
- Factory runtime → Run persistence: persists state (evidence: `src/foreman/runtime.py`)
- Factory runtime → Live steering: steers workers (evidence: `src/foreman/runtime.py`)
- Factory runtime → Factory state models: updates state (evidence: `src/foreman/runtime.py`)
- Responsibility routing → Responsibilities: selects checks (evidence: `src/foreman/routing.py`)
- Check configuration → Responsibilities: configures checks (evidence: `src/foreman/responsibilities/configuration.py`)
- Jev assessor → Jev service: sends assessment (evidence: `README.md`)
- Simulation assessor → Factory runtime: alternative assessor
- Observation builder → Run persistence: reads history (evidence: `src/foreman/observation.py`)
- Observation builder → Command evidence: collects commands (evidence: `src/foreman/observation.py`)
- Command evidence → Coding-agent process: runs checks (evidence: `src/foreman/evidence.py`)
- Worker protocol → Codex App Server: implemented by (evidence: `src/foreman/workers/__init__.py`)
- Worker protocol → Codex exec: implemented by (evidence: `src/foreman/workers/__init__.py`)
- Worker protocol → OpenCode worker: implemented by (evidence: `src/foreman/workers/__init__.py`)
- Worker protocol → Hermes worker: implemented by (evidence: `src/foreman/workers/__init__.py`)
- Codex App Server → Coding-agent process: runs agent (evidence: `README.md`)
- Codex exec → Coding-agent process: runs agent (evidence: `README.md`)
- OpenCode worker → Coding-agent process: runs agent (evidence: `README.md`)
- Hermes worker → Coding-agent process: runs agent (evidence: `README.md`)
- Hook adapters → Attached-worker hooks: normalizes events (evidence: `src/foreman/hook_adapters.py`)
- Extensions → Responsibilities: provides extensions (evidence: `src/foreman/extensions.py`)
- Attached-worker hooks → Jev assessor: assesses attached work (evidence: `src/foreman/hooks.py`)
