foreignloops

foreignloops

github.com/looprig/foreignloops runs external coding agents (Claude Code, Codex, or any agent speaking the Agent Client Protocol) as Harness foreign loops. It provides the concrete backend behind Harness's pkg/foreign builder contracts, a provider-neutral driver contract, and three drivers.

A product composition root builds a driver, wraps it in a backend configuration, and installs the resulting builders in a Harness rig with rig.WithForeignBuilders(builder, restored). Harness itself carries only the contracts; it never imports this module.

Status

Released. Carbon uses the ACP driver in production (driver/acp.BuildWithServices).

Known limits:

• Process supervision requires process-group handling that is implemented for Linux (non-Android) and macOS only. On other platforms the Claude and Codex drivers return PlatformError, and the ACP driver cannot spawn its child (see acp/transport/stdio).
• The Codex CLI driver (driver/codex) exposes normalized live events but reports its authoritative history as unavailable (driver.History{Available: false}).
• Steering (injecting input into a running turn) through the ACP driver is only enabled for adapter versions verified to honour it; see the version floors in driver/acp/steering.go.

Install

go get github.com/looprig/foreignloops@latest

Packages

Usage

The runnable, offline examples live under examples/:

• examples/scripted-driver runs the Codex driver in front of a deterministic scripted executable.
• examples/backend-lifecycle builds a live backend.Loop, runs a turn, snapshots it, and restores it with backend.BuildRestoredWith.
• examples/acp-backend drives a scripted ACP child through driver/acp (Linux/macOS).

The shape of a composition:

agent, err := claude.NewAgent(os.Environ(), claude.Config{ /* provider settings */ })
if err != nil {
	return err
}
cfg := backend.Config{Agent: agent, Cwd: workspace, Posture: driver.PostureDefault, SIDMode: backend.SIDPrebound}
opt := rig.WithForeignBuilders(backend.BuildWith(cfg), backend.BuildRestoredWith(cfg))

Where it sits

Tier 5 in the Looprig graph. Direct Looprig dependencies: acp, core, harness, and inference (test-only: backend parity tests and provider fakes). Consumed by carbon.

Development

Go 1.26.9 baseline.

GOWORK=off go test ./...
make test      # layering boundary check + go test -race ./...
make build     # boundary check + CGO_ENABLED=0 go build -trimpath ./...
make check     # fmt-check, vet, staticcheck, gosec, govulncheck, test, build

The Claude and Codex driver integration tests (-tags integration) need the real CLIs on PATH; the Claude test also needs ANTHROPIC_API_KEY, and the Codex tests need LOOPRIG_CODEX_INTEGRATION=1. See CONTRIBUTING.md for contribution rules.

License

Apache License 2.0. See LICENSE.