How thruwire/foreman works
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: runtime.py Factory runtime · base.py Worker protocol · observation.py Observation builder · jev.py Jev assessor
Components 24
Factory orchestration
- Command interface
src/foreman/cli.py - Factory runtime
src/foreman/runtime.py - Live steering
src/foreman/steering.py
Assessment and policy
- Responsibility routing
src/foreman/routing.py - Responsibilities
src/foreman/responsibilities/builtin.py - Check configuration
src/foreman/responsibilities/configuration.py - Jev assessor
src/foreman/foreman/jev.py - Simulation assessor
src/foreman/foreman/simulation.py - Intervention policy
src/foreman/policy.py
Worker execution
- Worker protocol
src/foreman/workers/base.py - Codex App Server
src/foreman/workers/codex_app_server.py - Codex exec
src/foreman/workers/codex.py - OpenCode worker
src/foreman/workers/opencode.py - Hermes worker
src/foreman/workers/hermes.py
Evidence and state
- Observation builder
src/foreman/observation.py - Command evidence
src/foreman/evidence.py - Run persistence
src/foreman/persistence.py - Factory state models
src/foreman/models/state.py
Extensions and hooks
- Attached-worker hooks
src/foreman/hooks.py - Hook adapters
src/foreman/hook_adapters.py - Extensions
src/foreman/extensions.py
Other components
- Job submitter
- Jev service
- Coding-agent process
Connections 28
- Job submitter → Command interface: submits job
README.md - Command interface → Factory runtime: starts runtime
src/foreman/cli.py - Factory runtime → Responsibility routing: routes work
src/foreman/runtime.py - Factory runtime → Worker protocol: starts workers
src/foreman/runtime.py - Factory runtime → Observation builder: builds observations
src/foreman/runtime.py - Factory runtime → Jev assessor: assesses state
src/foreman/runtime.py - Factory runtime → Intervention policy: chooses interventions
src/foreman/runtime.py - Factory runtime → Run persistence: persists state
src/foreman/runtime.py - Factory runtime → Live steering: steers workers
src/foreman/runtime.py - Factory runtime → Factory state models: updates state
src/foreman/runtime.py - Responsibility routing → Responsibilities: selects checks
src/foreman/routing.py - Check configuration → Responsibilities: configures checks
src/foreman/responsibilities/configuration.py - Jev assessor → Jev service: sends assessment
README.md - Simulation assessor → Factory runtime: alternative assessor
- Observation builder → Run persistence: reads history
src/foreman/observation.py - Observation builder → Command evidence: collects commands
src/foreman/observation.py - Command evidence → Coding-agent process: runs checks
src/foreman/evidence.py - Worker protocol → Codex App Server: implemented by
src/foreman/workers/__init__.py - Worker protocol → Codex exec: implemented by
src/foreman/workers/__init__.py - Worker protocol → OpenCode worker: implemented by
src/foreman/workers/__init__.py - Worker protocol → Hermes worker: implemented by
src/foreman/workers/__init__.py - Codex App Server → Coding-agent process: runs agent
README.md - Codex exec → Coding-agent process: runs agent
README.md - OpenCode worker → Coding-agent process: runs agent
README.md - Hermes worker → Coding-agent process: runs agent
README.md - Hook adapters → Attached-worker hooks: normalizes events
src/foreman/hook_adapters.py - Extensions → Responsibilities: provides extensions
src/foreman/extensions.py - Attached-worker hooks → Jev assessor: assesses attached work
src/foreman/hooks.py