russell@sidonsoft:~$ _

HexClamp

_ inspectable autonomous agent loop scaffold

Observe → Condense → Plan → Execute → Verify → Persist. File-backed state, metrics dashboard, Telegram integration, and circuit breakers built in.

GitHub Docs ← Home
// overview

What is HexClamp?

HexClamp is an inspectable autonomous agent loop scaffold designed for transparency and reliability. Unlike black-box agents that hide their reasoning, HexClamp exposes every step of the agent loop — so you can understand, debug, and recover from failures.

The loop follows a six-phase cycle: Observe → Condense → Plan → Execute → Verify → Persist. Each phase writes state to disk, making every decision auditable and every failure recoverable.

// features

Features

File-Backed State

Every loop phase persists to disk. Agent context, decisions, and results are stored as plain JSON — inspectable, recoverable, and portable across sessions.

Metrics Dashboard

Built-in metrics for cycle count, latency, success rate, and verification results. Track agent performance over time without external observability tools.

Telegram Integration

Get notified on agent events — task completion, verification failures, or circuit breaker triggers. Stay informed without polling logs.

Verifier Learning

Adaptive verification that learns from past results. Improve quality gates over time based on actual outcomes and manual corrections.

Circuit Breakers

Automatic halts on repeated failures or quality threshold breaches. Prevent runaway agent loops and ensure human-in-the-loop oversight.

Quality Gates

Configurable checkpoints between phases. Define pass/fail criteria that must be met before the agent proceeds to the next phase.

58+ Tests High Coverage TypeScript Python Adapter
// installation

Installation

bash 
pip install hexclamp

Or for development:

bash 
git clone https://github.com/sidonsoft/HexClamp
cd HexClamp
pip install -e ".[dev]"
// examples

Quick Start

python 
from hexclamp.loop import HexClampLoop
from hexclamp.agent import CLIAgent
from pathlib import Path

# Create agent and loop
agent = CLIAgent(workspace="/path/to/workspace")
loop = HexClampLoop(Path("/path/to/workspace"), agent)

# Enqueue a task
loop.enqueue("Read the README file")

# Run cycle
loop.run_cycle()

CLI Usage

bash 
# Initialize workspace
hexclamp init

# Enqueue a task
hexclamp enqueue "Fix the login bug"

# Run cycle
hexclamp run

# Check status
hexclamp status