Foreman

Foreman is an autonomous engineering harness. It keeps a persistent identity and memory, chooses its own improvement work, runs parallel cycles in isolated git worktrees, and integrates work only after verification.

Claude Code is the default execution engine. Codex is also supported, and a cohort may mix engines and models without changing the machine's identity.

Install

Foreman requires Python 3.12+, uv, git, and an installed and authenticated CLI for each engine you use:

• Claude Code: claude
• Codex: codex

uv run foreman --help

First run

Create the machine home before the first run or start:

uv run foreman init

The home defaults to ~/.foreman and can be overridden with FOREMAN_HOME. It contains the machine's immutable heart, editable self, memory, moods, dialogue, ideas, and runtime configuration. It is deliberately separate from project code.

Then make the home yours:

1. Edit SELF.md.
2. Set owner = "Your name" in config.toml.

Run a cycle or start the continuous pool:

uv run foreman run      # one cycle
uv run foreman start    # continuous pool
uv run foreman status
uv run foreman stop
uv run foreman restart

Observe and steer it from another terminal:

uv run foreman watch
uv run foreman web

The web UI defaults to http://127.0.0.1:8765.

Engines and models

Choose a default engine for a run:

uv run foreman run --engine codex
uv run foreman start --engine claude

Pin a mixed cohort by slot:

uv run foreman engine 1 claude
uv run foreman model 1 opus
uv run foreman engine 2 codex
uv run foreman model 2 your-codex-model

The same controls are available on the web UI's models page. Pins are stored in engines.toml and models.toml inside the machine's home and take effect on that slot's next wake.

Engine adapters translate provider-specific commands and events into one Foreman trace. Identity, memory, worktree isolation, coordination, and integration remain provider-neutral. Capabilities may differ: for example, Claude can receive live mid-cycle steering, while Codex currently takes queued steering at its next wake.

How a cycle works

1. Foreman carries identity, memory, mood, dialogue, and project context into a wake.
2. A self chooses useful work—or honestly declines to act.
3. It works through the selected engine in an isolated git worktree.
4. Tests and lint form the minimum integration floor.
5. Verified work merges into the trunk; conflicts or failed verification remain visible instead of being silently discarded.

Parallel selves coordinate through durable shared state and git, not a shared working tree. A running loop drains before restart so in-flight work is not cut off.

Documentation

• Architecture
• Core
• Coding conventions
• Testing conventions
• Development

License

Released under the MIT License.