harness

harness is a Go library for driving AI coding CLIs in headless mode. It
supports Claude Code, Codex, GitHub Copilot CLI, and OpenCode through one
interface while leaving process placement to the caller. A command can run on
the host, inside a container, or through a remote runner with the same arguments
and event parser.

Supported backends

The Copilot adapter targets CLI 1.0.80 and remains compatible with the
prompt-mode JSONL stream introduced in 1.0.75.

For Copilot BYOK runs, Job.BaseURL sets COPILOT_PROVIDER_BASE_URL and
Harness.Env passes through the configured COPILOT_MODEL and
COPILOT_PROVIDER_* credentials and wire settings as bare keys, so container
and remote runners can inject their values without placing secrets in argv.

The library owns the details that differ between CLIs: binary names, arguments,
credential and state environment variables, project instruction files, skill
directories, model API hosts, JSONL parsing, account-limit errors, default
models, and token prices.

Install

go get github.com/alpha-omega-security/harness

Go 1.26 or later is required.

Core API

A Job contains resolved values for one invocation. Callers apply their own
configuration defaults before constructing it.

type Job struct {
    Workspace string
    SrcDir    string
    SkillName string

    Prompt       string
    SystemPrompt string

    Model    string
    Effort   string
    MaxTurns int

    OutputFile  string
    AllowedTools string
    BaseURL      string

    ResumeSessionID string
    ResumePrompt    string
}

Workspace is the command's working directory. SrcDir is the repository
directory relative to it and defaults to src; set it to . when Workspace
is already the repository root. SkillName selects a staged SKILL.md; when
Prompt is empty, the backend builds a short activation prompt. SystemPrompt
uses --system-prompt with Claude and the backend's project instruction file
for the other CLIs.

MaxTurns uses the backend default when set to zero; Copilot maps it to maximum
autopilot continuations. Effort applies to Claude and Copilot. AllowedTools
applies only to Claude. ResumeSessionID and ResumePrompt continue an
existing conversation.

The Harness interface exposes the parts needed by local, container, and remote
runners:

type Harness interface {
    Binary() string
    Args(Job) []string
    Prompt(Job) string
    ParseStream(io.Reader, func(Event))
    SkillDir(workspace, name string) string
    GuideFilename() string
    SystemPromptViaArgs() bool
    EgressHosts() []string
    Env(baseURL string) []string
    StateEnv(dir string) []string
    AccountErrorText(string) string
    DefaultModels() []ModelDefault
}

Use ByName to select a backend. An empty name selects Claude.

h, err := harness.ByName("codex")
name := harness.Name(h)
available := harness.Names() // "claude, codex, copilot, opencode"

Each parser produces the same event type:

type Event struct {
    Kind      string
    Tool      string
    Text      string
    CostUSD        float64
    SessionCostUSD float64
    Turns          int
    Usage          Usage
    Model          string
    SessionID      string
    RateLimit      *RateLimitInfo
}

Kinds are thinking, text, tool, result, usage, error, session,
rate_limit and egress. FormatEvent renders an event for a plain-text log.
CostFromUsage calculates a list-price estimate when the CLI reports tokens
without a dollar amount. Copilot's CostUSD uses the latest cumulative
session.usage_checkpoint when one is present, so on a resumed Copilot session
the reported cost is session-cumulative rather than per-invocation.

Claude's total_cost_usd is cumulative too, both across the several results
one invocation can print and across --resume. Each Claude result's CostUSD
is therefore what that result added within the invocation. The raw total is
kept on SessionCostUSD. Copilot sets SessionCostUSD from its checkpoint.
When resuming a session, subtract the SessionCostUSD recorded for the earlier
invocation from the first result's CostUSD only if that result also sets
SessionCostUSD, since its cost then still includes the earlier invocation. A
resumed Copilot result with no checkpoint has SessionCostUSD 0 and a
per-invocation CostUSD, so use it unchanged.

A usage event reports the tokens one model call added, with its Model and a
list-price CostUSD estimate (zero for an unknown model). Summing them gives a
running estimate while a run is in progress, but the result event stays the
authoritative total, so do not add usage events to it. Claude needs no caller
change because Args adds --include-partial-messages. Subagent output tokens
are a lower bound until the result arrives. Codex reports usage only in its
result and emits no usage events.

Run a local subprocess

Run starts the selected binary in the workspace, applies its environment,
writes a project instruction file when needed, and parses combined output as it
arrives.

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/alpha-omega-security/harness"
    "github.com/alpha-omega-security/harness/egress"
    "github.com/alpha-omega-security/harness/skills"
)

func main() {
    ctx := context.Background()
    workspace := "/work/project"

    h, err := harness.ByName("claude")
    if err != nil {
        log.Fatal(err)
    }
    instructions, err := skills.Parse("/work/instructions/review.md")
    if err != nil {
        log.Fatal(err)
    }

    job := harness.Job{
        Workspace:    workspace,
        SrcDir:       ".",
        Prompt:       "Review this project for security defects.",
        SystemPrompt: skills.Concat(instructions),
        Model:        "claude-sonnet-4-6",
        MaxTurns:     20,
    }

    if err := egress.WriteSandboxSettings(workspace, h.EgressHosts()); err != nil {
        log.Fatal(err)
    }
    err = harness.Run(ctx, h, job, func(event harness.Event) {
        fmt.Println(harness.FormatEvent(event))
    })
    if err != nil {
        log.Fatal(err)
    }
}

When a non-zero exit contains a provider account-limit message, Run returns
an *harness.AccountError. Its optional reset time can be used to schedule a
later retry.

Use another process runner

Callers that own process creation can use the same API without Run. This is
useful for containers, job queues, and remote execution.

h, err := harness.ByName("codex")
if err != nil {
    return err
}
skill, err := skills.Parse("/skills/security-review/SKILL.md")
if err != nil {
    return err
}
job := harness.Job{
    Workspace:  "/work",
    SrcDir:     ".",
    SkillName:  skill.Name,
    Model:      "gpt-5.3-codex",
    OutputFile: "report.json",
}
if err := skills.Stage(h, job, skill); err != nil {
    return err
}
if err := harness.WriteSystemPrompt(h, job); err != nil {
    return err
}
argv := append([]string{h.Binary()}, h.Args(job)...)
env := append(h.Env(job.BaseURL), h.StateEnv("/state")...)

// Pass argv and env to the process runner. Entries such as "CODEX_API_KEY"
// use the `docker run -e KEY` passthrough form.
stdout, err := startContainer(ctx, argv, env)
if err != nil {
    return err
}
h.ParseStream(stdout, func(event harness.Event) {
    fmt.Println(harness.FormatEvent(event))
})

WriteSystemPrompt is needed only when SystemPrompt is non-empty. Backends
whose SystemPromptViaArgs method returns true receive that value in their
arguments, so the helper does not write a guide file.

Process isolation

The generated arguments allow unattended tool use. Claude uses
bypassPermissions unless AllowedTools is set. Codex uses
danger-full-access, OpenCode uses --auto, and Copilot uses --allow-all.
Run these commands only in a workspace and execution environment where those
permissions are acceptable. Container and remote callers should apply their
own filesystem, process, secret, and network limits.

The egress package can restrict outbound HTTP and HTTPS by hostname. Its proxy
checks the resolved destination immediately before connecting and rejects
loopback, private, link-local, carrier-grade NAT, unspecified, and multicast
addresses. This closes the usual DNS rebinding path after a hostname has passed
the allowlist.

Packages

skills parses SKILL.md files following the Agent Skills specification. YAML frontmatter is optional, so plain markdown instruction files parse too. Parse returns a Skill with the spec fields (name, description, license, compatibility, allowed-tools, metadata), the body, a sibling schema.json when present, and a content hash covering both. Walk finds skills under a directory; Stage writes one into the selected backend's discovery directory; Concat joins bodies for a system prompt; Render produces SKILL.md bytes from a Skill built in memory. ValidateNamespace and the Match/PathIncluded glob helpers support callers that add their own metadata keys and path filters.

container runs a backend inside an ephemeral OCI container. Runner.Run
mirrors harness.Run's signature; the workspace is bind-mounted at /work
and an optional state directory at /harness-state so a later run can resume
the session. DetectRuntime resolves docker, podman (rootful or rootless), or
Apple's container CLI and applies each engine's flag differences
(--userns=keep-id, --progress none, missing --security-opt). SELinux
:z bind-mount relabeling is handled via ResolveSELinuxRelabel, and
VerifyKeepID / VerifySELinuxMount report host misconfiguration once during
startup. Runner.Hardened
creates an internal network. Runner.Run owns that network for one backend
invocation. Call Runner.Open when readiness checks or retries must share it;
the returned Scope runs backends with Run, auxiliary commands with
RunCommand, and removes its resources with Close. Runner.ProcessEnv
supplies scoped values for bare Runner.Env keys without exposing them in the
container-runtime argv, while Runner.OmitEnv removes inherited backend
credentials that a caller replaces. Rootless podman gets a harness-proxy
sidecar on that network, restricted to Harness.EgressHosts() and any extra
hosts in Runner.Sidecar; Docker Desktop uses the same sidecar because an
internal network cannot reach its host proxy. Other runtimes use
Runner.ProxyURL through the network gateway. Runner images used for this
path need curl and the cmd/harness-proxy binary. Call SweepHardened during
startup to remove networks and sidecars left by an interrupted process.
Sidecar images must be rebuilt when Harness changes its proxy policy; stale
images fail closed.

egress contains the authenticated allowlist proxy and
WriteSandboxSettings, which writes Claude's .claude/settings.json domain
allowlist.
APIPort permits inspected HTTP only. CONNECT to it is refused even when the
port is also listed in HostPorts; use HostPorts for separate TLS or raw
TCP services.

llm sends a single schema-constrained request to the Anthropic Messages API.
It accepts a caller-owned HTTP client and permits plain HTTP only for local
development endpoints.

License

MIT