harnez — declarative developer and agent harness

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

The figures below are a historical sample from the original page, including a September 2026 heartbeat. They are not live counters.

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.

| Tool / Dimension | Sample Calls | Avg Score (1–5) | Failure Rate | Operational Role | | --- | --- | --- | --- | --- | | Bash (via harnez exec) | 5,594 | 4.82 | 4.1% | Proxied shell execution with automatic exit scoring | | Edit / apply_patch | 144 | 4.48 | 11.1% | Structured codebase modification & diff application | | Read / Write / Grep | 59 | 4.92 | 0.0% | High-reliability read-only and code-writing operations | | heartbeat (rate --ok) | 37 | n/a | 0.0% | Lean liveness assertions (issue 179) | | Agent: Claude Code | 5,337 | 4.85 | 3.9% | Primary agent session attribution via session ID | | Agent: OpenAI Codex | 553 | 4.42 | 9.4% | Codex exec interception & telemetry tracking | | Agent: Antigravity (AGY) | 21 | 5.00 | 0.0% | Native hooks.json PreToolUse interception |

# 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.

| Command | Key flags | What it does | | --- | --- | --- | | apply | -c -t -d --force-docs | Sync global Claude, Gemini, Codex, and Prime Agent rules, prompts, skills, and docs idempotently | | usage | -w -s --host --mic --json --offline | Live dashboard & sparkline monitor for token quotas, CPU/RAM/GPU load, and mic speech ballistics | | stats | --auto --overhead --project --tool --json | Analytical report over tool call frequency, average quality score, failure rate, and byte savings | | exec | --tool --expect-failure --distill | Proxy stdio unbuffered, execute commands, and record non-blocking telemetry rows to SQLite | | distill | -- hook | Strip low-signal test suite noise, ANSI escapes, and redundant output to conserve context tokens | | init | -c -d --docs -m -y --update | Set up a project directory: AGENTS.md, doc copies, git mode, and Makefile targets | | diff | -c -t -e | Preview pending changes without writing (-e, --exit-code returns 1 on drift) | | find | -d issues docs --json | Fuzzy search across tickets, documentation entities, and compute next issue numbers | | issues | new start close -d | Change ticket status, resync issues/README.md, and commit in one atomic step | | mode | concise verbose normal | Switch concise mode terseness level and update AGENTS.local.md overlays | | rate | 1-5 --ok --note | Record tool quality feedback score or a lean heartbeat into telemetry SQLite database | | release | patch minor major | Run version bump, test suite, binary build, minisign signing, and forge release publication | | revert --managed | -c -t --managed | Remove managed keys from settings.json and strip managed Markdown blocks | | status | -c -t | Print configuration summary and verify applied file integrity on disk |

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