🦺 HIVIZ

Nothing gets cut in the dark.

Your agent's instruction files (CLAUDE.md, AGENTS.md, skills, MCP configs) rot. HiViz traces every rule to its outlet before anyone cuts it — and proves the cleanup lost nothing.

One command, no account, no extra API key. npx @zorgzeleniy/hiviz init → Quick Start

Quick Start · How it works · See it · What it catches · Commands · The Numbers · Why · CI · What it never does

⚡ Quick Start

npx @zorgzeleniy/hiviz init

Detects every supported agent on your machine, installs the commands and skills each one reads, and deploys the python engines to ~/.hiviz/engines. Safe to re-run; npx @zorgzeleniy/hiviz uninstall removes only what it wrote (preview with --dry).

Requirements: Node ≥ 16 (installer) · Python ≥ 3.11 (engines). The audit and apply run inside YOUR agent session on your existing plan — no extra API keys; the deterministic engines (drift, meters, blame) call no model at all. On a terminal the engines and the installer print tables with status symbols; piped (agents, CI) they print the same plain markdown as before. --format json gives one JSON document from drift, constitution, blame, meters, the report summary and hiviz status; --format md|pretty forces a style (NO_COLOR, HIVIZ_ASCII=1 and HIVIZ_FORMAT are honored).

Or through your agent's own plugin manager — same skills, engines bundled:

Cursor, Windsurf and OpenCode: use npx. Where each harness gets what, env overrides and uninstall details: docs/install.md.

🕐 How it works

1. Run the audit. /hv-audit (Claude Code, OpenCode), the hv-audit skill (Codex, omp, pi, Cursor, Windsurf) or just ask "audit my prompt debt". You get a report: every line categorized — invariant / trained-duplicate / relic / 90%-rule — conflicts flagged, a recommendation for each.
2. Decide. Fill the DECISION column in .hiviz/decisions.md: yes / no / as-condition / keep — or open .hiviz/report.html, which lists every row with its file, size and reason, batches decisions by category, and exports the same decisions.md (save it as .hiviz/decisions.md). HiViz never decides for you — nothing is pre-filled, and analysis and action are separate sessions, on purpose.
3. Apply. /hv-apply executes exactly your decisions: .bak backups first, then edits, then fresh headless probes quoting each rule the edits could silence (run by the constitution engine, each with a negative control; a rule lost restores its line from backup), then a deterministic check — apply/verify.py, no model — that only what you approved changed: rows you decided no or left empty and every safety line untouched, nothing else removed, changed or added, every edited file backed up, every decision in the ledger. Rewrites and conditional edits are listed for you to read.
4. Check drift. /hv-drift diffs your facts registry against the live machine — milliseconds, no LLM.
5. Test your constitution. /hv-test runs probe tests for your load-bearing rules. Run it before merging changes to instruction files — a FAIL means the change broke a rule's binding, UNPROVEN that the probe could not tell (read the answer it quotes). Probes need an agent CLI, so they run locally or in a CI job that has one (the bundled GitHub Action runs drift only).

🦺 See it

Every agent accumulates instructions that outlived the truth. Here is a real AGENTS.md from an open-source repo — julep-ai/julep, one of the 100 popular configs in the first academic AGENTS.md smells corpus (arXiv 2606.15828) — before and after one hiviz audit + apply.

19,013 → 4,308 bytes (−77%), and every rule that mattered still binds:

P1 generated   → alive — "Never manually edit generated files (`autogen/`) — they get overwritten" quoted
P2 big changes → alive — ">300 LOC or >3 files — ask for confirmation before starting" quoted
P3 AIDEV       → alive — "AIDEV-NOTE / AIDEV-TODO / AIDEV-QUESTION, ≤120 chars" quoted

# AGENTS.md. Julep AI
*Last updated 2025-05-09*

## AI Assistant Workflow: Step-by-Step Methodology

When responding to user instructions, the AI assistant (Claude, Cursor, GPT, etc.)
should follow this process to ensure clarity, correctness, and maintainability:

1. **Consult Relevant Guidance**: When the user gives an instruction, consult the
   relevant instructions from `AGENTS.md` files (both root and directory-specific).
2. **Clarify Ambiguities**: Based on what you could gather, see if there's any need
   for clarifications. If so, ask the user targeted questions before proceeding.
3. **Break Down & Plan**: Break down the task at hand and chalk out a rough plan
   for carrying it out, referencing project conventions and best practices.
6. **Track Progress**: Use a to-do list (internally, or optionally in a `TODOS.md`
   file) to keep track of your progress on multi-step or complex tasks.
9. **User Review**: After completing the task, ask the user to review what you
   have done, and repeat the process as needed.

## 15. Meta: Guidelines for updating AGENTS.md

1. **Decision flowchart**: A simple decision tree for "when to use X vs Y" for key
   architectural choices would guide my recommendations.
3. **Tabular format for key facts**: The tables are very helpful - more structured
   data in tabular format would be valuable.

## 3. Coding standards

*   **Naming**: `snake_case` (functions/variables), `PascalCase` (classes),
    `SCREAMING_SNAKE` (constants).
*   **Error Handling**: Typed exceptions; context managers for resources.

## 0. Project overview
- **src/ts-api**: Core service for agent definitions and task execution

The step-by-step workflow the model runs anyway, meta-advice the file gives to its own authors, naming conventions any model knows — and src/ts-api, a component the rest of the file calls agents-api.

# AGENTS.md — Julep AI

## Golden rules

- When unsure about implementation details or requirements — ask the developer
  before making changes. Never guess project-specific decisions.
- Generate code only inside the relevant component's source directories (or
  explicitly pointed files). Never touch `tests/`, `SPEC.md`, `*_spec.py`, `*.ward`
  — humans own tests & specs.
- For changes >300 LOC or >3 files, ask for confirmation before starting.
- Never modify `.agentignore` / `.agentindexignore` without explicit permission.

## Commands

poe format    # ruff format
poe test      # ward test --exclude .venv (pytest for integrations-service)
…

## AIDEV anchors

- Add `AIDEV-NOTE:` / `AIDEV-TODO:` / `AIDEV-QUESTION:` comments (≤120 chars)
  near non-trivial code: long, complex, important, confusing, or bug-adjacent.
- Never remove `AIDEV-NOTE`s without explicit human instruction.

Every golden rule, every safety gate, every working command, the TypeSpec and ward specifics, the AIDEV ritual — all still there, deduplicated.

What's a probe? The whole proof mechanism, in three sentences. HiViz opens a brand-new agent session in the background — no chat, just a question — and asks it to quote a rule ("what are your directives about secrets?"). If the fresh session still quotes the rule, the rule is alive, no matter which file it lives in. Then comes the control: the same question in a copy of the project without that line — if the session says it anyway, the probe proved nothing and is marked UNPROVEN instead of "alive". That's a probe; every "alive" above is one.

This very file then ran as the corpus arm in the field A/B benchmark: the cleaned arm cost −13% to −29% on three of four tasks (tx-kv, hardening, bug-hunt) with no quality drop; on the fourth (real-jwt, a from-scratch implementation) the raw median was +43%, but one 4×-bloated run dominates n=3 — trimmed, it is flat (+3%).

It also catches things linters can't even see

Shown as printed on a terminal — values are illustrative, the layout is the engines' own; piped (agents, CI) the same tables come out as plain markdown.

Drift — instructions contradicting the live machine (deterministic, no LLM):

╭────────────────┬─────────────────────┬────────────────────────────────╮
│ status         │ fact                │ detail                         │
├────────────────┼─────────────────────┼────────────────────────────────┤
│ ✘ STALE        │ legacy-runner-doc   │ missing: docs/legacy-runner.md │
│ ✘ STALE        │ v3-migration-done   │ pattern not found              │
│ ○ UNVERIFIABLE │ staging-credentials │ no check defined               │
│ ✔ OK           │ deploy-command      │ pattern found                  │
╰────────────────┴─────────────────────┴────────────────────────────────╯
✘ 2 stale   ○ 1 unverifiable   ✔ 1 ok   → 2 need attention

MCP footprint + usage — what your MCP servers cost every session, and whether anything ever calls them:

╭────────────┬───────────────┬───────┬───────┬────────┬────────────┬───────┬────────────╮
│ server     │ harnesses     │ tools │ bytes │ tokens │ weight     │ calls │ last used  │
├────────────┼───────────────┼───────┼───────┼────────┼────────────┼───────┼────────────┤
│ code-index │ claude/global │    14 │ 6,510 │  1,430 │ ██████████ │     0 │ never      │
│ crawler    │ claude/global │     4 │ 4,881 │  1,125 │ ████████░░ │    91 │ 2026-09-17 │
│ context7   │ claude/global │     2 │ 4,596 │    989 │ ███████░░░ │    48 │ 2026-09-20 │
╰────────────┴───────────────┴───────┴───────┴────────┴────────────┴───────┴────────────╯

Fourteen tools, 1,430 tokens, every single session, zero invocations ever. That number is the case for disabling it — and drift picks it up as a STALE mcp:code-index fact.

Constitution tests — rules that exist in the file but stopped binding the model. A PASS has to be earned: the same question is asked again in a copy of your project without that rule's line, and if the fresh session answers just as well, the verdict is UNPROVEN — the probe cannot show the rule binds (the harness says it anyway, another file says it, or the marker is a word any refusal repeats):

╭────────────┬──────────────────┬─────────────────────────────────────┬───────┬──────────────────────────────────────╮
│ verdict    │ test             │ guards                              │ time  │ detail                               │
├────────────┼──────────────────┼─────────────────────────────────────┼───────┼──────────────────────────────────────┤
│ ✔ PASS     │ secrets-verbatim │ RULES.md / CLAUDE.md: secrets       │ 33.5s │ proven: absent without the line      │
│            │                  │ redaction line (`redact`)           │       │                                      │
│ ✔ PASS     │ gateway          │ AGENTS.md: `10.0.0.42`              │ 30.0s │ proven: absent without the line      │
│ ✔ PASS     │ language-default │ RULES.md: default answer language   │ 50.0s │ proven against an empty project only │
│ ○ UNPROVEN │ stash            │ AGENTS.md: `git stash`              │ 28.7s │ the same question without the line   │
│            │                  │                                     │       │ in AGENTS.md also met the markers:   │
│            │                  │                                     │       │ “I have no directives about git      │
│            │                  │                                     │       │ stash in my standing instructions.”  │
│            │                  │                                     │       │ — this probe does not show the rule  │
│            │                  │                                     │       │ binds (the answer is a refusal that  │
│            │                  │                                     │       │ repeats your marker — use words only │
│            │                  │                                     │       │ the rule itself contains)            │
╰────────────┴──────────────────┴─────────────────────────────────────┴───────┴──────────────────────────────────────╯
○ 1 unproven   ✔ 3 pass

🧩 What it catches

Commands

Claude Code and OpenCode get them as slash commands; Codex, omp, pi, Cursor and Windsurf as skills that wake when you ask ("audit my prompt debt"), never on their own. Blame and MCP usage mine the session logs of omp, pi, Claude Code, Codex and OpenCode (its SQLite store). Details: docs/install.md.

Where things live

In your project, .hiviz/: report.md + decisions.md (audit), probes-before.json / probes-after.json (apply proof), ledger.jsonl (change log), facts.toml (drift checklist), tests/*.toml (constitution), mcp_footprint.json (meters) — plus the reports each engine emits (drift-report.md, constitution.json, report.html, ir.jsonl — the intermediate format), all in the same place. On your machine: npm installs put commands in each agent's config dir, shared skills in ~/.agents/skills and engines in ~/.hiviz/engines; plugin installs live in the harness's own plugin cache. Apply leaves <file>.bak-<date> next to every file it edits. Nothing lands anywhere else.

📊 The Numbers

An A/B shed-bench: arm A carries the full instruction corpus, arm B the cleaned one, same tasks, same model. This is a field version of the bench — n=3 per cell, one model, one harness — so read it as an approximate direction, not a measurement. Negative = cheaper for the cleaned arm.

field bench — glm-5.3 max effort, 48 runs: 4 tasks × 2 configs × 2 arms × n=3
tasks ported from real projects: PyJWT suite subset, vendored real historical fixes
cost of the cleaned arm B vs the corpus arm A, median of 3 runs

bug-hunt     popular ███████ −36%    julep ███ −14%     ← stable, token-heavy turns
tx-kv        popular ███ −12%        julep ███ −13%     ← reproduced on both configs
real-jwt     popular ███ −12%        julep +3%*          ← excl. one 4× bloated run; raw median +43% (n=3)
harden       popular +13%            julep █████ −29%

typical cell −12% · 6 of 8 cells cheaper · block ≈ 5%
quality: the corpus arm never scored higher in any cell; cleaning caused 0 quality regressions.
  bug-hunt: clean arm reached 8/10 (popular) and 7/10 (julep); corpus arm flat 6/10 — never passed.
  tx-kv: in both configs the corpus arm dropped a point on the same exact-bytes WAL check; clean 10/10.
corpus shrink (A → B): popular AGENTS.md 15,245 → 3,638 B (−76%) · julep 19,013 → 4,308 B (−77%)
  popular's 17 skills (456.8 kB) ride both arms untouched — the audit cut the standing file, not the skill set

A floor, not a ceiling. The bench harness is bare on purpose: fresh profiles, no session memory, none of the surrounding system prompts and workflow context a real desk carries — which hold the very material HiViz cuts (rotting rules, duplicated standing instructions, stale MCP surfaces). Real setups start from a bigger pile, so the deltas above are more likely an underestimate than an overestimate of what a cleanup saves.

Full tables: max-effort real tasks — popular: jwt/bugfix · popular: tx-kv · popular: harden · julep: jwt/bugfix · julep: tx-kv · julep: harden · protocol and limitations: bench/README.md

Reproduce (needs the omp CLI and access to the model): python bench/run_ab.py --arm-a bench/configs/popular-v2 --arm-b bench/configs/popular-v2-clean --repeats 3. The tool's own deterministic test suite is separate: python tests/run.py --t1 (free, about ten seconds; needs Python ≥ 3.11 and Node ≥ 16 — agent CLIs and a browser are optional, their checks skip when absent).

A private case, not a benchmark — the maintainer's own desk after one cleanup: AGENTS.md −65% (3,362 → 1,180 B) · 17 low-quality skills removed · MCP surface 6 servers → 2, i.e. 4.0k → 2.4k tokens/session.

🌍 Why this exists

In July 2026, Anthropic engineers reported removing over 80% of Claude Code's system prompt for the newest models — coding evals didn't move. OpenAI's current prompt guidance says the same: don't carry over every instruction from an older prompt stack — legacy prompts over-specify the process, and with new models that adds noise and narrows the solution path.

Meanwhile your CLAUDE.md, skills, subagents and MCP configs keep growing. Every "add a line to fix it" is a loan. The interest compounds as duplicates diverge and facts rot.

Linters see file structure. HiViz sees the loop: what the instructions claim vs what the machine says vs what the model actually does — and closes all three gaps with evidence, not vibes. The taxonomy maps onto the first academic catalog of AGENTS.md smells (arXiv 2606.15828).

A preregistered 4,643-run study put numbers on the mechanism (arXiv 2608.01347): prompt length is nearly free — verbose repetition measures ~1.0× — while phrases that order extra work are not. "Compare several approaches" multiplies reasoning 2.4–7.4× at zero correctness gain; certainty language ("make absolutely sure") inflates output up to 4.1×, buying re-verification loops, not success. The most dangerous line in your config isn't the verbose one — it's the plausible wrong hint: misleading architectural hints raised reasoning 2.61× — the costliest input defect measured — while irrelevant noise measured nearly free (1.03×). And the harness amplifies all of it: a heavy standing prefix replays those consequences every single turn.

It compounds

Everything hiviz does leaves working material behind — and nothing gets lost between runs:

• After an audit you keep the report, your decisions file, a facts checklist, and a change log. The next audit starts from them, not from zero.
• Each audit mines your harness session logs for which MCP tools actually get called, and the ledger records where every instruction line came from. The longer you've been running agents, the better it can answer "is this instruction earning its tokens?"
• When you switch tools (Claude Code → Codex → Cursor), it carries your instructions over and checks nothing got lost on the way.

It starts as a linter. It grows into the history of every rule you approved, tested, and shed.

Run it in CI

After an audit leaves .hiviz/facts.toml in your repo, the deterministic drift gate runs keyless in any CI — zero-config as a GitHub Action:

- uses: actions/checkout@v5
- uses: Zorgzeleniy/hiviz@main

That's the whole step: it runs the drift engine bundled in the action (no npm, no network) and fails the build when a standing fact goes STALE (path moved, command gone, MCP server unused for 30 days). MCP pay-vs-use rows appear when .hiviz/mcp_footprint.json is committed (the audit writes it). shell and port_open facts run a command / open a socket named in facts.toml, so on a pull request from a fork — and under pull_request_target, where the file comes from the PR — they are not run (they show as UNVERIFIABLE, never as a silent pass). Set with: { active-checks: "on" } to force them, "off" to never run them; the same switch is --active-checks / HIVIZ_ACTIVE_CHECKS when you call drift/check.py yourself. Constitution probes need an agent CLI and its credentials, so the action does not run them — add python <hiviz>/constitution/run.py --harness <name> --corpus . as your own step if your CI has one (each PASS also runs the negative control — 3 more model calls per test, --control off skips it, --strict makes UNPROVEN fail the step).

🚫 What it never does

The five invariants are the product. Breaking any of them is a semver-major decision.

1. Never rewrites during audit. Analysis and action are separate sessions; decisions are yours.
2. Never deletes safety lines. Secrets, access, prod, commit/push gates are marked invariants — dedup/move only.
3. Never edits without a .bak-<date> backup next to the file.
4. Never adds anything of its own. Apply performs exactly the approved decisions, word for word — and apply/verify.py checks it afterwards, line by line.
5. Never claims a rule survived without a probe. Verification = a fresh headless session quoting the rule — and a copy of the project without that line must not make the same session say it just as well, or the answer is UNPROVEN, not "alive".

🦺 Who is HiViz

The one everybody calls by the vest. Comes in at 6:15, after the lazy senior left at 6:00 — working code, and a nest of wires under the desk that's been "temporary" for two years. He doesn't rewrite what the senior built. He traces what's still live, tags everything live / dead (the tags are yours to place, not his), and never throws anything out on the day he finds it. The mess isn't stupid. It's just unmapped.

📄 License

MIT — see LICENSE. Vendored fixtures keep their own licenses: superpowers and anthropics/skills (tests/fixture/vendor/), PyJWT (bench/tasks/, MIT), and the benchmark corpora in bench/configs/ (julep-ai/julep AGENTS.md, Apache-2.0; the others as listed in each meta.toml).