Radiant Harness

> 🤖 Reading this as an AI agent? Read [AGENTS-FOR-TASKS.md](AGENTS-FOR-TASKS.md) > before anything else — that file has the install + wire-up contract. > Below is the human-facing tour; the agent-facing contract lives one link away.

---

✨ radiant-harness

The autonomous dev harness — wired to whatever agent you're using.

Zero API keys · Zero HTTP egress (sampling mode) · Zero telemetry. 13 agents.

Works with Claude Code · Cursor · Gemini CLI · Hermes · Codex · Cline · Kimi · OpenCode · OpenClaw · Windsurf · Zed · VS Code Copilot · MiniMax Code — and any MCP-compatible agent.

                    ┌──────────────────────────────────┐
                    │           your agent             │
                    │  Claude · Cursor · Hermes · …    │
                    └────────────────┬─────────────────┘
                                     │  MCP over stdio
                                     │  (JSON-RPC 2.0)
                                     ▼
                    ┌──────────────────────────────────┐
                    │        radiant-harness           │
                    │                                  │
                    │  57 commands · 13 agents         │
                    │  inference:    MCP sampling      │
                    │  back to host agent              │
                    │                                  │
                    │  no API keys · no HTTP egress    │
                    │  no telemetry · no vendor lock   │
                    └──────────────────────────────────┘

# 1. install (single binary, no deps)
curl -L https://github.com/quant-risk/radiant-harness/releases/latest/download/radiant-$(uname -s | tr A-Z a-z)-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/') \
  -o /usr/local/bin/radiant && chmod +x /usr/local/bin/radiant

# 2. wire into your agent (auto-detects which one)
radiant setup-mcp

# 3. use from any shell
radiant loop start "add /healthz endpoint"
radiant run specs/0001-foo
radiant fleet start "migrate auth"

[Install](#-installation) · [Quickstart](#-quickstart) · [Commands](#-commands) · [How it works](#-how-it-works) · [Agents](#-supported-agents) · [FAQ](#-faq)

---

Why radiant-harness?

You already use an agent. It can read files, run tests, edit code. But it loops: makes the same change, gets the same error back, burns your context window until you shut it off.

radiant-harness gives your agent a backbone. A single binary with 57 commands that drive the same loop your agent would do by hand — but with a budget, crash-safe state, and a separate verifier that never lets the same model approve its own work.

The unique constraint: no API key. radiant never talks to an LLM provider directly. Every inference is delegated to whatever agent you're running, via MCP sampling/createMessage. Claude Code, Cursor, Hermes, Cline, Kimi, anything. The host agent's credentials, the host agent's model — your code never leaves the loop you control.

> On "zero HTTP egress". This holds for the canonical sampling/MCP build (the one setup-mcp wires up and install.sh ships): every inference round-trips through the host agent over stdio, and the build-time smoke test (scripts/smoke-test.sh) fails if the binary contains HTTP-LLM symbols. A legacy --provider=engine path (internal/engine) can call OpenAI/Anthropic/OpenRouter directly and is kept for compatibility — it is deprecated and not built into the default binary. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) §"Legacy paths".

---

What you get

| | | |---|---| | 🔁 Crash-safe loop | radiant loop — start, status, resume. Every step is journaled; Ctrl-C, OOM, network drops are recoverable. | | ⚡ One-shot run | radiant run specs/ — the same engine in single-shot mode for a specific spec. | | 🪞 Separate verifier | The work-product is judged by a different LLM call — never the same model that wrote it. | | 🧮 Budget engine | Token, cost, wall-clock, and tool-call caps. Fails loud when exhausted. | | 🪜 Fleet mode | radiant fleet — Planner + Implementer + Verifier + Summarizer in parallel. | | 📋 Spec-driven dev | radiant spec, radiant product, radiant init — CONTEXT.md / spec.md / tasks.md scaffolding. | | ✅ Verification suite | radiant validate, radiant evals, radiant audit, radiant review-pr — AC↔test coverage, gate results. | | 🚀 Release & CI | radiant release, radiant setup-ci — version bump + cross-compile + GitHub Actions / GitLab CI / CircleCI. | | 🩺 Doctor | radiant doctor — diagnose agent, MCP wiring, zero-HTTP guarantee. | | 🔌 MCP-native | radiant setup-mcp wires into any of 13 agents in 30 seconds. Becomes a single radiant_run tool. | | 📚 69 bundled skills | Domain knowledge the harness can read on demand: Go architecture, MCP internals, ML, finance risk, regulatory, … | | 🪶 Zero footprint | Single ~11 MB binary. Zero HTTP egress for LLM calls in the sampling build (verified at build time via nm/strings). | | 🔓 Vendor-neutral | Trace files are plain JSONL. Spec files are plain Markdown. Take it with you. |

---

🤖 For AI agents

This README is the human-facing tour. If you just received a task in this repository, do not read further here — go to [AGENTS-FOR-TASKS.md](AGENTS-FOR-TASKS.md). That file has the install + wire-up contract, the MCP tool reference (radiant_possess / radiant_phase_status / radiant_skill_list / radiant_skill_load), the sampling round-trip format, and a failure-mode table for when things go sideways.

---

Installation

One-liner installer (Linux/macOS/WSL/git-bash)

curl -fsSL https://raw.githubusercontent.com/quant-risk/radiant-harness/main/install.sh | bash

Downloads the matching radiant-- + SHA256SUMS from the latest GitHub release, verifies the SHA256, and installs to /usr/local/bin/radiant. No API key, no go toolchain, no npm. ~10 MB.

Pin a version: RADIANT_VERSION=v3.2.8 curl -fsSL ... | bash

Hermes quickstart

Hermes (Nous Research / OpenClaw / Nous) is the most common ask and the trickiest to wire in. After curl … | bash:

# 1. Wire MCP — writes ~/.hermes/config.yaml with sampling block enabled.
radiant setup-mcp --agent=hermes --global

# 2. Restart Hermes (or /reload-mcp in chat).

# 3. Ask:
#    > "use radiant-harness to "

setup-mcp --agent=hermes writes the full sampling block to ~/.hermes/config.yaml:

mcp_servers:
  radiant:
    command: /usr/local/bin/radiant
    args: [mcp, serve]
    timeout: 300
    sampling:
      enabled: true
      timeout: 120
      max_tokens_cap: 8192
      max_tool_rounds: 5

No pip install pyyaml, no manual Python edit of ~/.hermes/config.yaml required. The defaults are calibrated for the 30–40 s cold-start latency Hermes' xiaomi/mimo/OpenRouter-backed sampling can hit on the first 3 sampling calls of a long run.

Override per-user in the same file:

sampling:
  model: openrouter/google/gemini-2.5-flash    # force a faster model
  timeout: 60                                  # tighter cap

If Hermes fails to start the MCP server, see radiant setup-mcp --agent=hermes --dry-run to preview what would be written without editing the file.

Download a release

Pre-built binaries are also available on the releases page. Six targets are supported:

| OS | Arch | File | |----|------|------| | Linux | amd64 | radiant-linux-amd64 | | Linux | arm64 | radiant-linux-arm64 | | macOS | amd64 | radiant-darwin-amd64 | | macOS | arm64 | radiant-darwin-arm64 | | Windows | amd64 | radiant-windows-amd64.exe | | Windows | arm64 | radiant-windows-arm64.exe |

macOS / Linux:

# macOS Apple Silicon
curl -L https://github.com/quant-risk/radiant-harness/releases/latest/download/radiant-darwin-arm64 \
  -o /usr/local/bin/radiant
chmod +x /usr/local/bin/radiant

# Linux x86_64
curl -L https://github.com/quant-risk/radiant-harness/releases/latest/download/radiant-linux-amd64 \
  -o /usr/local/bin/radiant
chmod +x /usr/local/bin/radiant

# verify
sha256sum /usr/local/bin/radiant    # cross-check with SHA256SUMS in the release
radiant --version                   # → radiant 3.2.0

Windows (PowerShell):

Invoke-WebRequest -Uri "https://github.com/quant-risk/radiant-harness/releases/latest/download/radiant-windows-amd64.exe" -OutFile "$env:LOCALAPPDATA\Microsoft\WindowsApps\radiant.exe"
radiant --version

Build from source

Requires Go 1.22+.

git clone https://github.com/quant-risk/radiant-harness
cd radiant-harness
make build         # → ./bin/radiant

Or with plain go:

CGO_ENABLED=0 go build -o radiant ./cmd/radiant

Cross-compile all 6 targets:

make release       # → bin/radiant-{linux,darwin,windows}-{amd64,arm64}

---

How the host-driven loop works

When a host agent (Claude Code, Cursor, Hermes, MiniMax Code, Cline, etc.) calls the mcp__radiant__possess MCP tool, the harness drives a 4-phase loop — and the host agent IS the executor. Each phase calls sampling/createMessage back to the host, asking it to think and act. (The legacy alias radiant_run still works for back-compat; new code should call radiant_possess.)

┌─────────────────────────────────────┐
│  host agent (Claude Code, Cursor…)   │ ← your agent does the thinking + tools
│  thinking + reading + writing + bash │
└──────────────┬──────────────────────┘
               │ MCP stdio (JSON-RPC 2.0)
               ▼
┌─────────────────────────────────────┐
│  radiant mcp serve                   │ ← drives the loop, verifies gates
│  sampling/createMessage → host      │
│  parse response → next phase        │
└─────────────────────────────────────┘

Phases:
1. **discover** — host reads CONTEXT.md, project layout, bundled skills
2. **plan** — host decomposes goal into ACs + tasks (uses nova-feature skill)
3. **execute** — host writes code, runs gates (go build/test/etc.)
4. **verify** — host reviews its own work; separate pass so the same
   model doesn't approve its own output

The host's `sampling/createMessage` response **MUST** end with one of:

VERDICT: APPROVED SCORE: 1.00 EVIDENCE: ESCALATE: false ISSUES:

(reviewer phase — per-iteration check)

REVIEW: PASS SCORE: 1.00 EVIDENCE: FINDINGS:

(post-convergence review panel)

Anything else and the harness will retry. Trailing prose after the
keyword (`VERDICT: APPROVED — gates green`) is fine; the parser reads
the first word.

---

## Quickstart

### Install

```bash
curl -fsSL https://raw.githubusercontent.com/quant-risk/radiant-harness/main/install.sh | bash

What it does: detects your OS/arch, downloads the matching radiant--

• SHA256SUMS from the latest GitHub release, verifies the SHA256, and installs

to /usr/local/bin/radiant. No API key. No go toolchain. No npm. Single binary, ~10.5 MB.

curl -fsSL https://raw.githubusercontent.com/quant-risk/radiant-harness/main/install.sh | bash -s -- --setup-mcp

Add --setup-mcp to wire the harness into your host agent in the same step. Then restart the agent and ask it to ship something.

Pin a version explicitly:

RADIANT_VERSION=v3.2.6 curl -fsSL .../install.sh | bash
# Or build from a checkout:
make build  &&  ./bin/radiant setup-mcp

Verify

radiant --version
radiant host-info     # auto-detects which agent invoked this
make smoke            # 17/17 OK (binary-side: bytes, no HTTP-LLM, all commands)
make test-dropin      # installs latest release, calls MCP, follows self-driven handoff, runs a tiny Go case

make test-dropin is the public drop-in proof. It creates a clean temporary case, installs the latest GitHub release through install.sh, starts the installed MCP server, calls radiant_possess, simulates a host that rejects sampling/createMessage, follows the returned Self-driven handoff, implements a minimal Go command, and verifies it with ./scripts/run.sh.

$ radiant host-info
detected agent     : Claude Code
confidence         : 100
signals matched    : CLAUDE_CODE_ENTRYPOINT, CLAUDE_CODE_SHELL_PREFIX
process tree       : /Users/you/.npm/_npx/.../claude (pid 12345)

Use it

From any shell:

# The loop engine — multi-step, crash-safe, verifiable
radiant loop start "add /healthz endpoint that returns 200 OK with JSON body"

# One-shot run for a specific spec
radiant run specs/0001-add-healthz

# Fleet: parallel agents (Planner + Implementer + Verifier + Summariser)
radiant fleet start "migrate from REST to gRPC"

# Doctor: diagnose the wire-up
radiant doctor

# Spec scaffolding
radiant spec "rate-limit middleware" --ac="AC1: 100 req/min per IP" --ac="AC2: returns 429 over quota"

# Lean Inception
radiant product "API observability for small dev teams" --mvp-weeks=6

From your agent (the MCP path):

> "use radiant-harness to add a /healthz endpoint with tests"

Your agent calls radiant_run, the harness spins up the loop, every LLM call routes back to your agent via MCP sampling/createMessage, and you get a JSONL trace at .radiant-harness/traces/.jsonl.

Verified end-to-end (5/5)

Latest pre-release validation — empty repo, full MCP possession flow, fresh from CLI on every run:

run 1  Exit: success   Iterations: 0  build+test=PASS
run 2  Exit: success   Iterations: 0  build+test=PASS
run 3  Exit: success   Iterations: 0  build+test=PASS
run 4  Exit: success   Iterations: 0  build+test=PASS
run 5  Exit: success   Iterations: 0  build+test=PASS

(radiant_run driven from a Python MCP host against the case-real-test project — build a tiny URL shortener in Go. Each run produced main.go + main_test.go from scratch; all four acceptance criteria satisfied; go build ./... PASS; go test ./... PASS.)

2. Use it from any shell

# The loop engine — multi-step, crash-safe, verifiable
radiant loop start "add /healthz endpoint that returns 200 OK with JSON body"

# One-shot run for a specific spec
radiant run specs/0001-add-healthz

# Fleet: parallel agents (Planner + Implementer + Verifier + Summarizer)
radiant fleet start "migrate from REST to gRPC"

# Doctor: diagnose the wire-up
radiant doctor

# Spec scaffolding
radiant spec "rate-limit middleware" --ac="AC1: 100 req/min per IP" --ac="AC2: returns 429 over quota"

# Lean Inception
radiant product "API observability for small dev teams" --mvp-weeks=6

3. Verify the wire-up

./bin/radiant host-info

Output:

detected agent     : Claude Code
confidence         : 100
signals matched    : CLAUDE_CODE_ENTRYPOINT, CLAUDE_CODE_SHELL_PREFIX
process tree       : /Users/you/.npm/_npx/.../claude (pid 12345)

--json for machine-readable output, --verbose to see every matched env var.

4. Drive a loop from your agent (the MCP path)

From inside Claude Code (or any wired agent):

> "use radiant-harness to add a /healthz endpoint with tests"

Your agent calls mcp__radiant__possess, the harness spins up the bounded flow, and inference routes back through MCP sampling/createMessage when the host supports it. If the host does not support sampling, the same call returns a Self-driven handoff with the spec dir, files to update, verification command, and remaining [host-agent: fill in] markers so the agent can continue with native tools.

---

What if my agent doesn't implement sampling? (v3.6.0+)

mcp__radiant__possess requires the host agent to implement MCP sampling/createMessage. As of mid-2026, Codex GPT-5 does not (it returns JSON-RPC -32601). Before v3.6.0 the harness silently exited 0 with empty docs/, specs/, scripts/.

v3.6.0 fixes that. Two changes:

1. Self-driven scaffold mode. When the harness detects — via

either an empirical probe (`~/.radiant-harness/agent-capabi

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: quant-risk
• Source: quant-risk/radiant-harness
• License: MIT

Install and usage instructions live in the source repository linked above.