go-harness

Deterministic, local-first autonomous software engineering runtime.

Vision

go-harness combines deterministic orchestration with LLM reasoning. Rather than a single autonomous agent, it executes a staged pipeline backed by a shared workspace index.

Architecture

                           User
                             │
                             ▼
                      Coordinator
                             │
         ┌───────────────────┼───────────────────┐
         ▼                   ▼                   ▼
     Planner          Context Builder      Validator
         │                   │                   ▲
         └───────────┬───────┴───────────┐       │
                     ▼                   │       │
                  Editor                 │       │
                     │                   │       │
        filesystem / git / shell tools  │       │
                     ▼                   │       │
                 Repairer ───────────────┘───────┘

                    Workspace Index
     ┌──────────────────────────────────────────┐
     │ Packages │ Files │ Symbols │ Graph │ AST │
     └──────────────────────────────────────────┘

Pipeline

1. Planner creates a task graph.
2. Retriever queries the workspace index.
3. Context Builder assembles minimal grounded context.
4. Editor performs symbol-aware edits.
5. Validator runs formatting and tests.
6. Repairer fixes diagnostics until validation succeeds or retries are exhausted.

Features

• AST-based workspace index
• Stale-safe persistent workspace index builds
• Symbol-aware editing
• Approval-gated tool execution
• Queue-driven /think workflow
• Swarm workers
• Git worktrees
• Workspace diff previews
• Fast parallel validation
• Bounded dynamic workflows with live re-planning (-ultra)
• Deterministic retrieval
• Self-healing validation loop

Usage

When installed, the go-harness binary stays under 10 MB instead of carrying the full runtime directly. It delegates to the larger go-harness-agent runtime binary. If go-harness-agent is available on PATH, run:

GO_HARNESS_AGENT_BIN=go-harness-agent go-harness

Binary Size

go-harness uses a small launcher binary plus a larger agent runtime binary. Release builds are size-optimized with:

go build -trimpath -ldflags "-s -w"

Current macOS install size:

Binary	Size
go-harness	1.8 MB
go-harness-agent	38 MB
go-harness-filesystem	2.4 MB
go-harness-git	2.2 MB
go-harness-shell	2.2 MB

The launcher stays very small because it delegates to go-harness-agent. The agent contains the main autonomous coding runtime, including orchestration, queueing, workspace handling, tool execution, and validation support.

Dynamic workflows

Ultra mode is an opt-in workflow controller for tasks whose next step depends on the current workspace. It plans a dependency-aware graph, executes one ready node, re-plans against the live workspace, and repeats until the task is complete or the configured step limit is reached.

go-harness tui -ultra -ultra-steps 24
go-harness run -ultra "fix the failing tests"

Inside the TUI, /ultra enables the mode, /ultra <instruction> runs one dynamic workflow immediately, and /noultra disables it. The default remains the existing static workflow.

License

See LICENSE.