Swarmforge

Swarmforge is a builder-focused environment for designing, refining, and reusing processes and the tools they produce. It emphasizes robustness, constraint-driven design, and interoperability over ad-hoc interaction or one-off execution.

Installation

Check the prerequisites first. On Windows, set up WSL and run everything below inside it.

1. Add the shell helper alias and link the swarmforge command:

bash ./install.sh

This appends an oc alias to your shell rc file that runs make run_opencode PROJECT_DIR=$(pwd) against the repo's Makefile. It also links bin/swarmforge into ~/.local/bin so you can run swarmforge by name, replacing a symlink already there but never a regular file.

2. Build the container images you want:

make build_opencode
make build_claude
make build_grok
make build_codex

Or build them all at once with make build_harnesses. The images share every stage below the harness install, so make -j -O build_harnesses is worth it once one build has populated that cache (-O keeps the parallel logs apart).

3. Run from your project directory:

• OpenCode: oc
• Claude Code: make run_claude PROJECT_DIR=$(pwd)
• Grok Build: make run_grok PROJECT_DIR=$(pwd)
• Codex CLI: make run_codex PROJECT_DIR=$(pwd)
• Pass OpenCode overrides as arguments (oc PROFILE=work DATA_DIR=...) or env vars (PROFILE=work oc).
• Override the container timezone per run (affects git commit timestamps): oc TIMEZONE=America/New_York.

Installation carries the rest: which rc file install.sh writes, pinning OpenCode to a release, and pointing several aliases at one checkout.

Documentation

docs/ is the index. The pages behind it:

• Installation, Windows (WSL), swarmforge CLI, and Git repos and worktrees — getting a session running, and what the read-only git mounts change about it.
• OpenCode, Claude Code, Grok Build CLI, Codex CLI — one page per harness.
• Configuration and assets, Agents, Skills, Commands — what every harness picks up, and how to write it once.
• Tongs — sidecar containers that hold what the agent must not, such as credentials.
• Harness lifecycle and Testing — working on Swarmforge itself.
• Environment variables and Make targets — every knob and every target, for looking one up.