Coding Harness

By LatentDream

Harness

Harness is a small, modular coding-agent runtime for working with LLMs inside a developer environment.

Harness is a work in progress. See todo.md for the roadmap.

Features

• Support multiple LLM providers, including Codex, OpenAI-compatible APIs, Anthropic, and LiteLLM;
• Interactive terminal UI when running in a TTY.
• Line-oriented mode for redirected input/output.
• Build, Plan, and Chat modes.
• Tool calling support for reading, writing, searching, globbing, and shell commands.
• Provider/model switching with :model or /model.
• New session support with :new or /new.
• Resume the active session for the current folder with --continue or -c.
• Switch between sessions from the current folder with :switch or /switch.
• Copy latest assistant response with :copy or /copy.
• Structured tracing and session logging.

Requirements

• fzf
• rg
• fd

Quick Start

Using just:

just build
just run
just test

Harness starts a new persistent session by default. To resume the active session created from the same canonical folder path:

harness --continue
# or
harness -c

Sessions are scoped to their working directory. A session ID from another folder is never considered for continuation or switching. After the first successful turn, Harness uses a small tool-free model request to create a concise session title from the initial prompt. If that request fails, it derives a deterministic title from the prompt instead. Multiple sessions per folder are retained. List them through the TUI's fuzzy session picker, or switch by exact title, full ID, or a unique ID prefix. Empty sessions are omitted from session selection:

/switch
/switch 91dc7f4a
/switch implement authentication

Configuration

Harness loads configuration from the default user config path:

~/.harness.json

You can override the config path with:

HARNESS_CONFIG_PATH=/path/to/config.json

If no user config file exists, Harness uses its embedded defaults. The config file is JSON and may contain any fields from the default config; values you provide override the defaults.

Example config

Warning

Auth and multi-provider setup are still works in progress. Codex is the guaranteed working provider for now, but you must run the OpenCode auth flow first to generate the auth file that Harness reads. Built-in auth and provider setup helpers are coming soon.

{
  "providers": [
    {
      "name": "codex",
      "type": "codex",
      "auth_file": "~/.local/share/opencode/auth.json",
      "auth_provider": "openai",
      "models": [
        { "name": "gpt-5.5" },
        { "name": "gpt-5.6-sol" },
        { "name": "gpt-5.6-luna" }
      ],
      "enabled": true
    },
    {
      "name": "openai",
      "type": "openai",
      "auth_token_env_var": "OPENAI_API_KEY",
      "models": [
        { "name": "gpt-4.1" },
        { "name": "gpt-4.1-mini" }
      ],
      "enabled": true
    },
    {
      "name": "anthropic",
      "type": "anthropic",
      "auth_token_env_var": "ANTHROPIC_API_KEY",
      "models": [
        { "name": "claude-sonnet-4-5" }
      ],
      "enabled": true
    },
    {
      "name": "litellm",
      "type": "litellm",
      "base_url": "http://localhost:4000/v1",
      "auth_token_env_var": "LITELLM_API_KEY",
      "models": [
        { "name": "gpt-4.1" }
      ],
      "enabled": false
    }
  ]
}

Provider setup and authentication

Harness supports these provider types:

Type	Description	Auth
codex	ChatGPT/Codex backend provider	OAuth auth file or token env var
openai / openai-compatible	OpenAI Chat Completions-compatible APIs	API key env var
anthropic / claude	Anthropic Messages API	API key env var
litellm / custom-litellm	LiteLLM or custom OpenAI-compatible endpoint	API key env var plus base_url

For API-key based providers, set auth_token_env_var in the config and export the matching environment variable:

export OPENAI_API_KEY="your-openai-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"
export LITELLM_API_KEY="your-litellm-api-key"

OpenAI-compatible providers send the token as a bearer token. Anthropic providers send the token as x-api-key.

For Codex, Harness currently defaults to using the OpenCode auth file:

{
  "name": "codex",
  "type": "codex",
  "auth_file": "~/.local/share/opencode/auth.json",
  "auth_provider": "openai",
  "enabled": true
}

The Codex auth file is expected to contain an OAuth record keyed by auth_provider. Harness can refresh expired Codex OAuth tokens when a refresh token is present.

You can also configure Codex with a token environment variable instead:

{
  "name": "codex",
  "type": "codex",
  "auth_token_env_var": "CODEX_ACCESS_TOKEN",
  "models": [{ "name": "gpt-5.3-codex" }],
  "enabled": true
}

export CODEX_ACCESS_TOKEN="your-token"

First-run config generation and built-in auth setup are still works in progress. See todo.md for the roadmap.

Terminal UI

When stdin and stdout are interactive TTYs, Harness starts a full-screen terminal interface.

Useful keys:

Key	Action
Enter	Submit prompt
Shift+Enter	Insert newline
Tab	Cycle Build/Plan/Chat mode
@	Pick a repository file
/ or :	Open command picker
!	Run a local shell command and insert truncated output into the next prompt
Ctrl+C	Cancel and exit

Build mode allows the full configured tool set. Plan mode exposes only read-only tools. Chat mode is conversational and attaches no coding tools by default; runtime integrations may allow only webfetch.