Agent configuration · Live quotas · Tool telemetry

harnez manage agent harnesses from one config.yaml.

Configure Claude Code, Antigravity, Codex and Prime Agent declaratively. Idempotent configuration, hook interception, live quota and hardware monitoring, and SQLite tool telemetry keep agent workflows observable.

go install ubunatic.com/harnez/cmd/harnez@latest

See the dashboard View source Product home

Project snapshot · measured 2026-10-26

Key facts

Commits 3,850Last commit 2026-10-26 Source receipt ↗ Commits · 7 days 682 Source receipt ↗ Tickets closed 610 / 930 Source receipt ↗ Studies 114 Source receipt ↗

12-week commit activity

2026-10-26

Aug 3

Aug 10

Aug 17

155

Aug 24

368

Aug 31

212

Sep 7

427

Sep 14

749

Sep 21

345

Sep 28

315

Oct 5

141

Oct 12

513

Oct 19

View 12-week data table

Week starting	Commits
2026-08-03	3
2026-08-10	0
2026-08-17	69
2026-08-24	155
2026-08-31	368
2026-09-07	212
2026-09-14	427
2026-09-21	749
2026-09-28	345
2026-10-05	315
2026-10-12	141
2026-10-19	513

Key Features

Idempotent apply of permissions, hooks, commands, skills and AGENTS.md sections from one config.yaml, preserving user-owned keys.
Unified token, session and quota usage table across agents, with live watch and remote hardware streaming.
Server-side monitoring of local and remote hosts with background polling and remote upgrade.

Verified Engineering Milestones

Per-repo .harnez/repo.yaml so init adapts to repos built differently (854)
Server as monitor and background supervision (epic 921, 5b8398ff)
Merged model catalog with policy enforcement and owner tier guidance (941, 956)

Stack

Go 1.26, Cobra, YAML specs, pure-Go SQLite; supporting Bash, Python, TypeScript and HTML

Why harnez

Why harnez?

Configuration Drift & Blind Spots

AI coding agent setups drift across machines and providers. Tool permissions wipe on updates, prompt conventions diverge across repositories, multi-agent skills need disparate target directories, and unexpected rate limits or silent tool failures stall workflows without telemetry.

Declarative Source of Truth & Native Hooks

A single declarative config.yaml idempotently manages global configs, local project scaffolding, and cross-agent skills. Two-stage PreToolUse hooks rewrite commands to proxy stdio unbuffered and capture execution metrics directly into a local SQLite database.

Deterministic, Observable Engineering

Zero drift across all agent harnesses, one-command project onboarding via harnez init, live cross-provider quota tracking with rate-limit protection, and quantitative tool call reliability metrics via harnez stats.

Unified Token, Quota & Hardware Dashboard

harnez usage live terminal dashboard showing All Usage, CPU/RAM/GPU load, Mic level meter, and Remote Load streaming — harnez usage --watch

harnez usage showing All Usage quota bars for five providers, local Load with CPU at 100 percent and RAM at 83 percent, and Remote Load of an ssh node with two GPUs — Quota windows next to local and remote hardware load (CPU, RAM, swap, GPU, VRAM).

harnez usage Remote Load panel for node x600 showing the RTX 3060 at 53 percent and the Phoenix1 GPU at 59 percent while a vision workload runs — A local vision workload on the remote node's RTX 3060 and Phoenix1 iGPU, watched over ssh.

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

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

Tracked tool calls

5,800+ captured non-blocking

Distillation byte savings

54.3%

Average tool score

4.82 / 5

Claude harness failure rate

3.9%

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

Multi-Agent Harness

Centralizes skills, permissions, and conventions across Claude Code (~/.claude), Google Antigravity (~/.gemini), Codex (~/.codex), and Prime Agent (~/.prime).

Non-Destructive Key Merging

Permissions, effort levels, and hooks in settings.json are merged cleanly. User themes, authentication tokens, and manual overrides remain completely intact.

Structured 5-Phase Sprints

Orchestrate structured /sprint workflows: Parallel Advisory Discovery → Sequential TDD → Pre-Commit Review Gate → Process Hygiene → Retrospective.

Live Logarithmic Mic Meter

Equalizer-style smooth decay and speech-activated dynamic refresh rates via PipeWire (pw-record), ALSA, and PulseAudio with logarithmic dBFS scaling.

Repository Discovery & Issues

harnez find and harnez issues offer fast fuzzy search, next-ticket reservation, and automatic README index synchronization.

Copyable Language & Practice Docs

Bundles battle-tested conventions for Go, Bash, Make, Rust, Zig, C++, GTK4, Markdown, Canary-first probes, Spec architectures, and Agentic Loops.

Concise Mode Switching

harnez mode adjusts prompt terseness levels dynamically and syncs AGENTS.local.md overlays across active workspace repos.

One-Command Project Scaffolding

harnez init provisions AGENTS.md, symlinks CLAUDE.md, installs requested language docs, and reconciles Makefile targets.

Release & Forge Automation

harnez release coordinates semantic version bumps, builds, minisign signatures, and Codeberg release forge uploads.

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 (). 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 milestones include server-side monitoring of local and remote hosts (epic 921, in progress: server status --json, remote upgrade on start, remote load polling), a per-repo .harnez/repo.yaml so init adapts to repos built differently (854), a merged model catalog with policy enforcement (941, under epic 942) and developer tier defaults from owner feedback (956). The four days of epics story records the work ticket by ticket.

Getting started

Build and install from source

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

Project details

Stack

Go 1.26, Cobra, YAML specs, pure-Go SQLite; supporting Bash, Python, TypeScript and HTML

Milestones

Per-repo .harnez/repo.yaml so init adapts to repos built differently (854) · Server as monitor and background supervision (epic 921, 5b8398ff) · Merged model catalog with policy enforcement and owner tier guidance (941, 956)

Source

https://codeberg.org/ubunatic/harnez ↗

Architecture

Layer composition

Terminal: CLI, shell hooks, usage table
Desktop: Linux
Inference / AI: Claude Code, Antigravity, Codex, Prime Agent
Containers / VM: —
Web: —

Engineering story

harnez: the story behind the project

Period: 2026-10-22 13:37 (commit 25ef1e46) to 2026-10-25 ~15:00. Measurement cutoff: f2b51d71 (the story commit itself and later doc commits are excluded). - Previous story: 2026-10-22-generic-init-repo-yaml-story.md (per-repo .harnez/repo.…

Read the engineering story

Measurement source · 2026-10-26

Verification receipts

Commits: 3,850 · Last commit 2026-10-26
git -C <repo> rev-list --count HEAD; git -C <repo> rev-list --count --since=<ISO-week-Monday> --until=<ISO-week-Sunday> HEAD; git -C <repo> rev-list --count --since=<measured-date-6-days>T00:00:00 --until=<measured-date>T23:59:59 HEAD; git -C <repo> log -1 --format=%cs HEAD; ls <repo>/issues | grep '^[0-9].*\.md$'; grep -l -E '^\*\*Status\*\*: *(Closed|Done|Resolved|Fixed|Complete)' <repo>/issues/*.md | wc -l; ls <repo>/docs/studies/*.md
repositories behind spec project ids in ~/projects; private-repo filter is a safety net and matches no spec project today; missing repos reported separately; seven calendar days ending on measured date in the measuring host's local timezone; commit counts include all authors and merge commits reachable from HEAD · measured 2026-10-26
Commits · 7 days: 682
git -C <repo> rev-list --count HEAD; git -C <repo> rev-list --count --since=<ISO-week-Monday> --until=<ISO-week-Sunday> HEAD; git -C <repo> rev-list --count --since=<measured-date-6-days>T00:00:00 --until=<measured-date>T23:59:59 HEAD; git -C <repo> log -1 --format=%cs HEAD; ls <repo>/issues | grep '^[0-9].*\.md$'; grep -l -E '^\*\*Status\*\*: *(Closed|Done|Resolved|Fixed|Complete)' <repo>/issues/*.md | wc -l; ls <repo>/docs/studies/*.md
repositories behind spec project ids in ~/projects; private-repo filter is a safety net and matches no spec project today; missing repos reported separately; seven calendar days ending on measured date in the measuring host's local timezone; commit counts include all authors and merge commits reachable from HEAD · measured 2026-10-26
Tickets closed: 610 / 930
git -C <repo> rev-list --count HEAD; git -C <repo> rev-list --count --since=<ISO-week-Monday> --until=<ISO-week-Sunday> HEAD; git -C <repo> rev-list --count --since=<measured-date-6-days>T00:00:00 --until=<measured-date>T23:59:59 HEAD; git -C <repo> log -1 --format=%cs HEAD; ls <repo>/issues | grep '^[0-9].*\.md$'; grep -l -E '^\*\*Status\*\*: *(Closed|Done|Resolved|Fixed|Complete)' <repo>/issues/*.md | wc -l; ls <repo>/docs/studies/*.md
repositories behind spec project ids in ~/projects; private-repo filter is a safety net and matches no spec project today; missing repos reported separately; seven calendar days ending on measured date in the measuring host's local timezone; commit counts include all authors and merge commits reachable from HEAD · measured 2026-10-26
Studies: 114
git -C <repo> rev-list --count HEAD; git -C <repo> rev-list --count --since=<ISO-week-Monday> --until=<ISO-week-Sunday> HEAD; git -C <repo> rev-list --count --since=<measured-date-6-days>T00:00:00 --until=<measured-date>T23:59:59 HEAD; git -C <repo> log -1 --format=%cs HEAD; ls <repo>/issues | grep '^[0-9].*\.md$'; grep -l -E '^\*\*Status\*\*: *(Closed|Done|Resolved|Fixed|Complete)' <repo>/issues/*.md | wc -l; ls <repo>/docs/studies/*.md
repositories behind spec project ids in ~/projects; private-repo filter is a safety net and matches no spec project today; missing repos reported separately; seven calendar days ending on measured date in the measuring host's local timezone; commit counts include all authors and merge commits reachable from HEAD · measured 2026-10-26
12-week commit activity
git rev-list --count --since=<Monday> --until=<Sunday> HEAD
12 latest complete ISO weeks; weekly values are from spec/metrics.yaml.