agent-harness

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

Note: This project is in early development. We are iterating fast. Best used in Coder, DevPod, or GitHub Codespaces for a consistent environment.

Purpose

agent-harness captures architectural patterns from production agentic coding tools:

Core agent loop with streaming responses
Tool dispatch with permission controls
Two execution modes: interactive (prompt for each command) and yolo (auto-approve with visibility)
Secure credential storage with AES-256-GCM encryption
Session management with auto-save
Root YAML plus layered configuration (user / project / local)
Slash command system

Quick Start

Local Model First

The repository includes agent-harness.yml, a local-first runtime config for an OpenAI-compatible llama.cpp server. The intended default model is DeepReinforce Ornith-1.0 GGUF, using a practical Q4_K_M quantization.

git clone https://github.com/BA-CalderonMorales/agent-harness.git
cd agent-harness
mkdir -p models

# Place an Ornith-1.0 Q4_K_M GGUF at:
# ./models/ornith-1.0-9b-Q4_K_M.gguf

llama-server -m ./models/ornith-1.0-9b-Q4_K_M.gguf -c 8192 --host 127.0.0.1 --port 8080

In another terminal:

make build
./build/agent-harness

Run ./build/agent-harness --diagnose to inspect resolved config, model file presence, and local endpoint reachability. See Local Model Setup for download and override details.

Installation

Linux/macOS:

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

Manual:

go install github.com/BA-CalderonMorales/agent-harness/cmd/agent-harness@latest

Usage

# Start the TUI
agent-harness

# Or use the short alias (after setup)
ah

Key Controls:

Tab / Shift+Tab - Switch views (Chat, Sessions, Settings)
ESC - Cancel current agent execution or exit mode
? - Show help (in normal mode)
/ - Open command palette (when input is empty)
Ctrl+C - Quit

Execution Modes:

Interactive (default) - Prompts you before executing shell/write/edit commands
Yolo - Auto-approves commands but shows what is happening in the UI

Switch modes in Settings or with /mode commands.

Configuration

agent-harness.yml is the obvious project setup file. Environment variables override YAML values when needed:

AH_PROVIDER, AH_RUNTIME, AH_MODEL, AH_MODEL_PATH
AH_ENDPOINT_URL, AH_CONTEXT_LENGTH, AH_TEMPERATURE, AH_MAX_TOKENS
AH_WORKSPACE_PATH, AH_LOCAL_SERVER_COMMAND
AH_PERMISSION_MODE, AH_PERM_READ, AH_PERM_WRITE, AH_PERM_DELETE, AH_PERM_EXECUTE

Remote providers are still supported through OpenRouter, OpenAI, and Anthropic. Set AH_PROVIDER, AH_MODEL, and AH_API_KEY or use the /login flow.

Architecture

cmd/agent-harness/          # CLI entrypoint
internal/
  agent/                    # Core loop + streaming executor
  approval/                 # Command approval system
  commands/                 # Slash command registry
  config/                   # Layered config + secure storage
  llm/                      # LLM client abstraction
  permissions/              # Permission stack
  state/                    # Session management
  tools/                    # Tool descriptor + registry
  tui/                      # Terminal UI (Bubble Tea)
pkg/
  bash/                     # Shell execution
  git/                      # Git operations

Documentation

Architecture - Pattern implementations
Command Approval - How the approval system works
Edge Cases - Non-obvious behaviors
Local Model Setup - Ornith-1.0 GGUF and local runtime setup

Building from Source

go build -o agent-harness ./cmd/agent-harness

License

MIT

Acknowledgments

This project is inspired by the architectural patterns found in terminal-jarvis.

The TUI design patterns are inspired by golazo by Juan Manuel.

Additional TUI inspiration from the awesome-tuis collection.

Agent Harness

README