README
¶
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
- Layered configuration (user / project / local)
- Slash command system
Quick Start
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.
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
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.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
agent-harness
command
Package main provides the entry point for agent-harness.
|
Package main provides the entry point for agent-harness. |
|
Package e2e provides behavior-based testing harness for agent repositories
|
Package e2e provides behavior-based testing harness for agent repositories |
|
internal
|
|
|
agent/core
Package agent provides the modular agent architecture.
|
Package agent provides the modular agent architecture. |
|
agent/defaults
Package defaults provides centralized default configurations for agent buckets.
|
Package defaults provides centralized default configurations for agent buckets. |
|
core/audit
Package audit provides append-only logging of tool executions and approvals for security review and accountability.
|
Package audit provides append-only logging of tool executions and approvals for security review and accountability. |
|
core/config
Package config provides the modular configuration architecture.
|
Package config provides the modular configuration architecture. |
|
core/persona
Package persona defines functional personas that adapt agent behavior, system prompts, and security defaults to the user's current role.
|
Package persona defines functional personas that adapt agent behavior, system prompts, and security defaults to the user's current role. |
|
core/state
Package state provides the modular state management architecture.
|
Package state provides the modular state management architecture. |
|
interface/tui
Package tui provides the modular TUI architecture.
|
Package tui provides the modular TUI architecture. |
|
runtime/llm
Package llm provides the modular LLM provider architecture.
|
Package llm provides the modular LLM provider architecture. |
|
runtime/permissions
Package permissions provides the modular permission architecture.
|
Package permissions provides the modular permission architecture. |
|
runtime/permissions/defaults
Package defaults provides centralized default configurations for permission buckets.
|
Package defaults provides centralized default configurations for permission buckets. |
|
runtime/services
Package services provides the modular service architecture.
|
Package services provides the modular service architecture. |
|
runtime/tools
Package tools provides the modular tool architecture.
|
Package tools provides the modular tool architecture. |
|
runtime/tools/buckets
Package buckets provides domain-specific ToolBase implementations.
|
Package buckets provides domain-specific ToolBase implementations. |
|
runtime/tools/defaults
Package defaults provides centralized default configurations for tool buckets.
|
Package defaults provides centralized default configurations for tool buckets. |
|
session/contextmgr
Package contextmgr provides the modular context management architecture.
|
Package contextmgr provides the modular context management architecture. |
|
session/loop
Package loop provides the modular agent loop architecture.
|
Package loop provides the modular agent loop architecture. |
|
session/loop/buckets
Package buckets provides domain-specific LoopBase implementations.
|
Package buckets provides domain-specific LoopBase implementations. |
|
session/loop/buckets/defaults
Package defaults provides hardcoded configuration values for all buckets.
|
Package defaults provides hardcoded configuration values for all buckets. |
|
session/loop/setup
Package setup provides factory functions for creating orchestrators.
|
Package setup provides factory functions for creating orchestrators. |
|
pkg
|
|
Click to show internal directories.
Click to hide internal directories.