Agent Harness

A clean-room, pattern-derived agent harness for building coding agents

Safe Testing Recommended: Agent Harness is a harness for AI coding tools that can modify files and execute commands. For the safest experience, test in a remote development environment such as GitHub Codespaces, Coder, or DevPod.

Install

The one-liner installs the binary and the runtime convenience scripts into ~/.local/bin. Platforms, prerequisites, and manual paths: Installation.

# Any Linux or macOS shell
curl -fsSL https://raw.githubusercontent.com/BA-CalderonMorales/agent-harness/main/scripts/install.sh | bash

# Termux (Android)
curl -fsSL https://raw.githubusercontent.com/BA-CalderonMorales/agent-harness/main/scripts/install-termux.sh | bash

# Or build from source (this repository)
go build -o build/agent-harness ./cmd/agent-harness

Quick Start

Boot the terminal UI, walk the tabs, and talk to a model. The startup wizard handles credentials once; the modes, settings, and the full command surface: Usage.

# From this repository
make build
./build/agent-harness

# local-first: the repository defaults to a llama.cpp server and a local GGUF:
#   ./scripts/ah-local.sh            # local server + TUI
#   ./build/agent-harness --diagnose # resolve config, check the endpoint

Remote providers work the same way — switch provider and model in the Settings tab or with env vars, then /login when a key is needed:

AH_PROVIDER=openrouter \
AH_MODEL=nvidia/nemotron-3-super-120b-a12b:free \
./build/agent-harness

Commands

Everything happens inside the TUI: four tabs (Home, Chat, Sessions, Settings) with vim-style navigation and a slash-command system for operations. /help lists every command in place; Ctrl+P opens the command palette.

Key controls

Slash commands

Headless flags

agent-harness --diagnose   # resolve config, check model file + endpoint
agent-harness --version

Layout

The repository is a few small planes, and every Go domain is bucketed the same way — once you can read one, you can read them all.

cmd/agent-harness/           # the app: boot, command wiring, TUI delegates
internal/
├── agent/                   # the live agent loop (streaming executor)
├── core/                    # cross-cutting state
│   ├── audit/               # tool-activity ledger
│   ├── config/              # layered YAML + env + user settings
│   ├── persona/             # behavior modes
│   ├── planning/            # task planning
│   └── state/               # session model and persistence
├── interface/               # the public surfaces
│   ├── approval/            # command approval system
│   ├── commands/            # slash command registry
│   └── tui/                 # the terminal UI (Bubble Tea)
├── runtime/
│   ├── llm/                 # OpenAI-compatible client, SSE, probing
│   ├── permissions/         # permission stacking
│   ├── services/            # provider services
│   └── tools/               # tool registry and buckets
├── session/                 # session ledger + the modular loop buckets
└── ui/                      # line editor, stream rendering, screens
pkg/                         # shared types, messages, git, bash, sandbox

Each domain keeps one concept per file with a facade for its public surface, and tests mirror the sources beside them. Files target 400 lines or fewer and make verify measures that shape so it stays observable. Developers: Development docs.

Docs

Browse the whole folder from the docs index. What this is for, and how the loop moves a turn: Architecture.

License

MIT