harnez manage agent harnesses from one config.yaml.

Why harnez

Why harnez?

Unified Token, Quota & Hardware Dashboard

Unified Token, Quota & Hardware Dashboard

harnez usage (aliases: quota, tokens) unifies live rate-limit quota windows, token velocity sparklines, host hardware load, remote SSH nodes, and microphone speech meters into one interactive btop-style dashboard.

Instant Splash Status: Red/green brand glyphs (● codex, ✱ claude, Λ agy, ● mic) provide sub-second verification of provider connectivity and recording state on startup.

Multi-Provider Quotas

Live 5-hour and weekly rate limits for Claude Code, Gemini/Antigravity, and OpenAI Codex with reset countdowns and shared file-locked disk caching.

Hardware & Remote Streaming

Local CPU, RAM, and GPU/VRAM telemetry (AMD Cezanne/Phoenix, NVIDIA) alongside remote node metrics streamed over SSH (--host @x600).

Live Speech & Mic Ballistics

PipeWire (pw-record), ALSA (arecord), and PulseAudio live input capture with logarithmic dBFS scaling and equalizer-style visual decay.

# live btop-style dashboard with tokens/min sparkline and hardware load
$ harnez usage --watch          # -w

# compact one-shot summary for status bars and quick CLI glances
$ harnez usage --summary        # -s

# stream live telemetry from a remote compute node over SSH
$ harnez usage --watch --host user@x600

# inspect JSON output for custom statuslines or automation
$ harnez usage --json

Tool Telemetry & Analytical Reporting

Tool Telemetry & Analytical Reporting

harnez stats queries the local SQLite telemetry database populated by harnez exec and harnez rate. It breaks down call frequency, quality scores, failure rates, and distillation byte savings across tools, agents, and repositories.

# render the full analytical report with tool, agent, and project breakdowns
$ harnez stats

# filter report to the current session (resolved from environment)
$ harnez stats --auto

# inspect feedback token overhead and distillation ratios
$ harnez stats --overhead --project harnez

distillation byte savings: 54.33% (27,957 -> 12,769 bytes)
heartbeat (harnez rate --ok): 37 recorded, last at 2026-09-07T07:19:55Z
feedback overhead: 28.1 avg bytes/call, ~943 one-time instruction tokens

Two-Stage Hook Interception

PreToolUse hooks rewrite commands into harnez exec -- <cmd>. The hook process exits immediately; the wrapper proxies unbuffered stdio, captures timing and exit codes, and writes SQLite telemetry in a bounded goroutine without blocking the agent.

Noise Distillation Engine

harnez distill automatically strips passing test noise, repetitive logs, and ANSI escape codes before output enters the agent's context window, saving over 50% in context tokens and bandwidth.

Native Multi-Agent Hooks & Shims

Includes dedicated adapters: quiet guarded bash PATH shim for Google Antigravity, Claude Code settings.json hooks, and Codex shell wrappers.

Core Engine Features

Core Engine Features

Commands Reference

Commands Reference

Self-contained, fast Go binary with no external dependencies required for daily workflows.

Architecture

How it works

1. Two-Stage Hook Interception

PreToolUse lifecycle hooks rewrite tool invocations (such as Bash or run_command) into harnez exec wrappers. The hook returns instantaneously, letting harnez exec supervise execution, proxy unbuffered stdio, and write telemetry asynchronously to SQLite.

2. Key Merge, Not Replace

harnez only mutates keys it explicitly manages (effortLevel, permissions, hooks, env, spinnerVerbs). User preferences, dark themes, and auth tokens in settings.json and hooks.json are strictly preserved.

3. Managed Markdown Boundaries

Content in AGENTS.md and CLAUDE.md is bounded by HTML comments (<!-- harnez:begin ... -->). Custom rules, project architectures, and unmanaged sections outside those comments are never overwritten.

4. Shared Caching & Lock Coordination

Live quota queries and hardware metrics are cached on disk with file locks (~/.claude/harnez-quota-cache.json). Multiple running terminals and agent subprocesses share cached readings without hitting upstream API rate limits.

Configuration

config.yaml at a glance

target_dir: ~/.claude
skills_target: ~/.gemini/skills
codex_skills_target: ~/.codex/skills
prime_agent_target: ~/.prime/agent

docs:
  - golang
  - bash
  - make
  - agentic-loop
  - canary
  - spec

effort: medium

permissions:
  allow:
    - "Bash(git *)"
    - "Bash(make *)"
    - "Read(~/projects/**)"

hooks:
  - event: PreToolUse
    matcher: Bash
    command: "harnez exec hook"
  - event: Stop
    command: "ffplay -nodisp -autoexit /usr/share/sounds/..."

skills:
  - name: sprint
    description: "Orchestrate 5-phase agentic sprint loop"
    file: commands/sprint.md

Recent engineering

Recent engineering

Recent milestones include repeat-safe agent deletion and missing-session recovery (issue 688), spec-driven usage view modes (678), role inference and fuzzy session resume (686, 692, 695), and an Antigravity tool rejection hook (694). The agent harness story connects these changes to the repository’s recorded workflow.

Getting started

Build and install from source

git clone https://codeberg.org/ubunatic/harnez
cd harnez
make install