Review the files and settings that control an AI coding setup.
See what exists, how the parts connect, what the available evidence supports, and what to change next.

Explore the site → · Product thesis · Architecture · Roadmap

Important

Harness Axis is an executable, read-only alpha. It scans a local target, records what it could inspect, maps static file relationships, calculates a score limited by that evidence, and produces an offline report. It can also write a change plan, but it cannot apply the plan. Static files do not prove that a capability ran successfully.

What problem it solves

An AI coding setup rarely lives in one file. Its behavior may depend on instructions, skills, tools, hooks, permissions, saved memory, generated indexes, and old paths that other files still reference.

A polished folder can still hide:

• competing sources of authority;
• capabilities that are declared but not alive;
• stale paths with active callers;
• generated copies mistaken for canonical truth;
• dependencies that make a “simple cleanup” dangerous;
• confident scores built on incomplete evidence.

A directory listing cannot tell you which file has authority, whether a declared capability is active, or what will break when a path moves.

What Harness Axis produces

The workflow uses three tools, then returns to the first one for verification:

Harness Score → Harness Atlas → Harness Forge
      review          understand       plan
          ▲                                │
          └──────── verify after change ───┘

Three installable Agent Skills provide that workflow:

• harness-score scans a target, records coverage, and calculates the initial score;
• harness-atlas opens or explains the saved report without scanning again;
• harness-forge turns a verified report into a change plan without editing the target.

The skills share one dependency-free Python engine. Internally, the engine loads the scoring rules, records observations and blind spots, and maps static references before calculating a score.

Who it is for

• Maintainers can find conflicting instructions, stale paths, and dependencies before reorganizing a setup.
• Architects can compare the documented design with the files and relationships the scan actually found.
• Reviewers can inspect the scoring rules, coverage, limitations, and source observations behind a result.

Harness Axis is most useful when a setup has grown across several tools or clients and a seemingly small cleanup may have hidden callers.

Rules that constrain a review

1. Score the existing harness first. Freeze scope and establish a baseline before mutation.
2. Show the evidence. Every material claim must resolve to observations and coverage limits.
3. Separate dimensions. Architecture, mechanism, vitality, and evidence strength are not interchangeable.
4. Treat unknown as valid. Missing evidence produces uncertainty—not invented confidence.
5. Map blast radius. Static references do not prove activation, but ignored dependencies still create risk.
6. Keep planning separate from mutation. The alpha can produce a baseline-bound plan; it cannot apply that plan.
7. Rescore the result. Improvement is only claimed when matched evidence supports it.

Quick start

Requirements: Git and Python 3.10+ on macOS or Linux.

git clone https://github.com/youkistudios/harness-axis
cd harness-axis
./install.sh

"$HOME/.local/bin/harness" review fixtures/synthetic-small \
  --output /tmp/harness-axis-run
"$HOME/.local/bin/harness" verify /tmp/harness-axis-run

The default installer writes the CLI to ~/.local/bin/harness and the skills to ~/.claude/skills/ and ~/.agents/skills/. Open /tmp/harness-axis-run/HARNESS-AXIS.html in a browser to inspect the report. Set HARNESS_AXIS_PREFIX or the documented client-root variables before installation to use different destinations.

Forge remains plan-only:

"$HOME/.local/bin/harness" forge-plan /tmp/harness-axis-run \
  --target fixtures/synthetic-small \
  --change fixtures/synthetic-small/change.json \
  --output /tmp/harness-axis-plan

See the committed synthetic run and plan sidecars.

Current status

Area	Status
Three Agent Skills	✅ Implemented
Dependency-free CLI	✅ Implemented
Read-only review and immutable run	✅ Tested
Static Wires and evidence-capped Score	✅ Alpha
Offline Harness Atlas	✅ Alpha
Harness Forge plan-only boundary	✅ Alpha; mutation unavailable
Synthetic end-to-end example	✅ Verified
Claude Code + Codex skill invocations	✅ All three skills invoked against the committed synthetic fixture in both clients
GitHub Actions	✅ Full live-skill suite active
Runtime behavior of scanned third-party capabilities	⏳ Not established by static review
Broad production readiness	⏳ Not claimed

See the live skill implementation plan and roadmap.

Limits

Harness Axis does not claim complete detection, runtime enforcement, safe automatic cleanup, or support for every agent platform. A partial scan can still be useful when the report states what it could and could not inspect.

Read THREAT-MODEL.md, PROVENANCE.md, and SECURITY.md.

Contributing

The most valuable early contributions are adversarial fixtures, detector false-positive reports, schema review, accessibility feedback, and clean-install witnesses. See CONTRIBUTING.md.

License

Newly authored software and documentation in this repository are licensed under Apache License 2.0, unless a file states otherwise. The repository contains no imported scanner code or Git history.