Skip to main content

The go-code Command

go-code is the single terminal entry point for the entire go-code runtime. It is a shell wrapper (scripts/go-code.sh) that sits in front of harnessd (the daemon) and harnesscli (the CLI client). You never have to start the daemon manually — go-code detects whether a server is already running, boots one if needed, and shuts it down again when you are done.

What you get from this one command:

  • An interactive, full-screen TUI for multi-turn agent conversations
  • A single-shot streaming mode for scripted or piped use
  • A daemon-only mode for long-lived background servers
  • All run-management operations (list, inspect, cancel, continue, replay, search, improve)

What the wrapper does​

When you invoke go-code, the wrapper:

  1. Checks whether harnessd is healthy at the configured port by hitting GET /healthz.
  2. If no healthy server is found, starts harnessd in the background and waits up to 10 seconds for it to become ready.
  3. Resolves your project root by walking up from the current directory.
  4. Delegates to harnesscli (for TUI and prompt modes) or passes the subcommand straight through (for run-management operations).
  5. On exit, stops the server only if the wrapper started it. A server you started independently is always left running.

The auto-start/auto-stop contract is intentional. Running go-code in two terminals at the same time is safe: the second invocation detects the already-running server and reuses it without touching its lifecycle.

Invocation modes​

Headless scripting and exit codes​

The wrapper propagates the harnesscli exit code unchanged, so shell scripts and CI can branch on $? exactly as they would when calling harnesscli directly — including when the wrapper started the server itself (the auto-stop EXIT trap does not override the exit status):

go-code "summarize the diff"
case $? in
  0) echo "run completed" ;;
  2) echo "run failed" ;;
  3) echo "run blocked on input — resume interactively" ;;
  6) echo "run cancelled — resumable via go-code continue <run-id> ..." ;;
esac

The full code table (0 completed, 1 client error, 2 failed, 3 blocked, 6 cancelled, 130 interrupted) and its per-command coverage are documented in Exit Codes.

Subcommand reference​

go-code runs and go-code list are both aliases — they both map to harnesscli list. Similarly, go-code show and go-code status both map to harnesscli status.

InvocationMaps to harnesscli subcommandWhat it does
go-code--tuiLaunches the interactive BubbleTea TUI
go-code "prompt"-prompt "..."Runs a single prompt, streams events, exits
go-code --server(server lifecycle only)Starts harnessd in background and exits
go-code runslistLists known runs
go-code listlistAlias for runs
go-code show <id>statusShows one run
go-code status <id>statusAlias for show
go-code cancel <id>cancelCancels one run
go-code continue <id> "prompt"continueContinues a completed run and streams events
go-code replay <id-or-path>replayReplays a recorded run
go-code search <query>searchSearches run metadata (client-side substring match)
go-code improve [flags]improveRuns or plans the self-improvement test loop

Address and project root​

Server address: HARNESS_ADDR​

The HARNESS_ADDR environment variable controls the listen address. The default is :8080. The wrapper extracts the port from this value and constructs the base URL as http://127.0.0.1:<port>.

# Run on a different port
HARNESS_ADDR=:9090 go-code "List the Go source files"

The address can also be set in your project or user config file (~/.harness/config.toml or .harness/config.toml). HARNESS_ADDR takes precedence over the TOML layers.

Project root detection​

go-code automatically resolves the workspace root before launching TUI or prompt mode. It walks parent directories from $PWD, looking for:

  1. A .git/ directory
  2. A .harness/config.toml file

The first directory that contains either marker is used as the workspace root. If neither is found at any level, $PWD is used as the fallback.

The resolved path is passed to harnesscli as -workspace <root>, so the agent always operates relative to your project root — not the directory you happened to be in when you ran the command.

~/projects/
  myapp/          ← .git/ lives here → workspace root
    src/
      api/        ← you run "go-code" here

In the example above, running go-code from src/api/ resolves the workspace root as ~/projects/myapp/.

Key-free smoke testing​

You can run go-code without any provider API key by setting HARNESS_PROVIDER=fake. The fake provider returns deterministic responses and is the right choice for CI smoke tests and local integration checks.

# Start the server with the fake provider
HARNESS_PROVIDER=fake go-code --server

# In another terminal, run a prompt against it
go-code "hello"

Or in a single invocation:

HARNESS_PROVIDER=fake go-code "Does this pipeline work?"

The --server flag removes the auto-stop trap. After using go-code --server, stop the daemon manually with pkill harnessd. If you need to use the PID file directly, note that it is written to ${TMPDIR:-/tmp}/harnessd.<wrapper-pid>.pid — on macOS $TMPDIR is a per-user temp directory (e.g. /var/folders/.../T/), not /tmp. The filename uses the launching wrapper's PID; the file's contents are harnessd's PID.

Prerequisites​

go-code requires three commands on your PATH: harnessd, harnesscli, and curl. If any of these are missing it exits with an error. The recommended install (brew install --HEAD dennisonbertram/go-code/go-code or ./scripts/install.sh --add-to-path) places all three in the correct location automatically.

Next steps​

  • Configure the server — set default model, cost limits, and provider keys: see the Configuration reference.
  • Understand run events — learn what run.completed, run.failed, and the rest of the SSE event stream mean: see Events.
  • Use harnesscli directly — for flag-level control over individual subcommands without the wrapper: see the harnesscli reference.