Ubunatic Coding

Declarative developer & agent
harness

One config.yaml drives everything Claude Code and AI agents read — permissions, model effort, hooks, instructions, cross-agent skills, and engineering conventions. Apply is idempotent.

settings.json CLAUDE.md AGENTS.md commands/ skills/ docs/ hooks usage --watch
Quick install
$ git clone https://codeberg.org/ubunatic/harnez
$ cd harnez
$ make install # builds and installs to ~/go/bin

Why harnez?

Problem

Configuration Drift & Fragmented Agents

AI coding agent configurations drift rapidly across machines and tools. Permissions wipe on updates, prompt rules diverge across repositories, slash commands and skills need separate target directories for Claude Code, Gemini, and Codex, while quota limits cause silent failures.

Approach

Single Declarative Source of Truth

A central config.yaml idempotently manages global configs, local project scaffolding, and universal skills. Non-destructive key merging and HTML-comment boundaries preserve user customization, while a unified usage monitor and 5-phase sprint workflow enforce operational discipline.

Result

Deterministic, Zero-Drift Engineering

Zero drift across all agent harnesses, one-command project onboarding via harnez init, live cross-provider quota tracking with rate-limit protection, and structured, zero-zombie agentic sprint execution.

What it manages

Effort & optional model

Set effort centrally; model is unmanaged by default so user and client choices in settings.json are preserved.

Permissions

Allow/deny lists are merged, not replaced — your user-managed keys survive every apply.

Lifecycle hooks

Declare Stop, PreToolUse, and other hooks in YAML; harnez writes the right JSON shape.

CLAUDE.md / AGENTS.md

Managed sections live inside HTML-comment markers. Unmanaged project rules are never overwritten.

Multi-agent skills

Distributes slash commands & Agent Skills across Claude (~/.claude/commands/), Gemini (~/.gemini/skills/), Codex (~/.codex/skills/), and Prime Agent (~/.prime/agent/).

Language & practice docs

Bundles conventions for Go, Bash, Make, Rust, Zig, C++, GTK4, Git, Markdown, Canary-first probes, Spec-driven architecture, and Agentic Loops.

5-phase agentic sprints

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

Token & quota monitor

usage reads tokens, plans, and live quota windows across Claude Code, Antigravity, and Codex — as a report, a one-shot grid, or a live --watch dashboard.

Project setup & upgrade

init sets up AGENTS.md, symlinks CLAUDE.md, copies local docs, notes repo git mode (solo|fork|team), and reconciles Makefile targets.

Quick start

# sync global Claude, Gemini, Codex, and Prime harnesses (idempotent)
$ harnez apply --force-docs

# preview changes without writing (exit code 1 if drift detected)
$ harnez diff --exit-code

# check configuration and installed doc status
$ harnez status

# inspect live cross-agent quota and token velocity
$ harnez usage --watch

# set up or upgrade a project directory with language docs
$ harnez init -d /path/to/project --docs golang,make -y

# upgrade all sibling repositories in workspace
$ make init-siblings

Commands reference

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
init -c -d --docs -m --summary --update --replace -y Set up a project: AGENTS.md, doc copies, repo mode, Makefile targets
diff -c -t -e Preview changes without writing (-e, --exit-code exits with 1 on drift)
clean -c -t Remove managed keys from settings.json; strip MD sections
status -c -t Print config summary and check which items are present on disk
usage -w -s --interval --json --agent --offline Show tokens, plans, and quota windows across agents (aliases: quota, tokens, stats) — see below

All commands accept -c <path> (config file) and -t <dir> (Claude config directory). The binary is self-contained — no flags needed for the common case.

Token & quota monitor

harnez usage (aliases: quota, tokens, stats) pulls token totals, plan tier, active model, and live quota windows from Claude Code, Antigravity (AGY), and OpenAI Codex into one view. Three ways to read it: the full report, a compact one-shot grid, or a live dashboard. 

# full detailed report — every quota window, token breakdown, and data source
$ harnez usage

# compact one-shot grid, printed once and exited — for a quick glance or scripts
$ harnez usage --summary        # -s

# live btop-style dashboard, refreshed in place with a tokens/min sparkline
$ harnez usage --watch          # -w

# machine-readable, or narrowed to one agent, or strictly local (no network)
$ harnez usage --json
$ harnez usage --agent claude   # claude | agy | codex
$ harnez usage --offline
Agentic usage  21:58:34 CEST

┌─ [C] Claude Code ──────────────────────────────┐ ┌─ [G] Antigravity (AGY) ────────────────────────┐
│ alice@example.com · Max                        │ │ alice@example.com · Consumer                   │
│ 5-hour           [████░░░░░░░░] 41.0% · 2h13m  │ │ model: Gemini 3 Pro                            │
│ weekly           [███████░░░░░] 62.0% · 3d04h  │ │ Gemini Models…   [██░░░░░░░░░░] 18.0% · 4h02m  │
│ [T] tok: 8,420,155 total · 1,204/min [▂▃▅▇▆▄▃] │ │ Claude and GPT…  [████████░░░░] 73.0% · 1h47m  │
└────────────────────────────────────────────────┘ └────────────────────────────────────────────────┘
┌─ [O] OpenAI Codex ─────────────────────────────┐
│ alice@example.com · Plus                       │
│ model: gpt-5.6-codex                           │
│ 5-hour           [█░░░░░░░░░░░] 12.0% · 4h31m  │
│ [T] tok: 633,891 total · 0/min [▁▁▂▁▁▁▁]       │
└────────────────────────────────────────────────┘

refresh every 1m0s   [a]ll  [q]uit

Live dashboard

--watch redraws in place and tracks a tokens/min trend. Toggle panels from the keyboard: c Claude, g AGY, o Codex, t tokens, a all, q quit. The refresh cadence is --interval (default 15s, floor 10s).

Failures stay visible

A failed live quota call is reported as quota: unavailable (HTTP 429) instead of silently leaving the window blank — so “fetch failed” never looks like “this plan has no such limit”.

Stale beats blank

On a transient failure --watch keeps the last known-good reading, marked (stale), rather than blanking a panel. A successful refresh always wins.

Shared quota cache

Live quota readings are cached in ~/.claude/harnez-quota-cache.json and coordinated with a file lock, so several concurrent harnez processes share one reading instead of each hammering the API into a rate limit.

Everything is read-only: local agent state under ~/.claude, ~/.gemini, and ~/.codex, plus each vendor's own quota endpoint. --offline skips the network entirely and reports from local caches.

How it works

1

Key merge, not replace

harnez only writes the keys it owns (effortLevel, permissions, hooks, env, spinnerVerbs, mcpServers, and model if explicitly configured). Every other key in settings.json — theme, plugins, auth — is preserved.

2

Managed sections in Markdown

Content in CLAUDE.md / AGENTS.md is wrapped in HTML-comment markers. Sections outside those markers are never modified. Multiple sections coexist independently.

3

Symlink convention

AGENTS.md is the canonical file (readable by any agent); CLAUDE.md is a symlink so Claude Code finds it. Same pattern globally: ~/.claude/CLAUDE.md is real; ~/AGENTS.md links to it.

4

Idempotent by design

Run harnez apply as often as you like. If settings drift, re-running restores the managed keys while leaving everything else alone.

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

# model: sonnet  # optional override; unmanaged by default
effort:  medium

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

hooks:
  - event: Stop
    command: "ffplay -nodisp -autoexit /usr/share/sounds/…"

commands:
  - name: review
    description: "Review current branch against main"
    file: commands/review.md

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