vigiles

vigiles

Lint & test the harness your AI agent runs on.

Your CLAUDE.md, hooks, and skills steer the agent — but nothing checks they're true, and nothing tests they work. vigiles does both.

---

Agent = Model + Harness. You'd never ship an app without a linter and a test suite — yet the harness steering your agent runs on vibes. vigiles[^name] is the deterministic layer for it, and does two independent things — adopt either, or both:

🔎 Lint	Every file path, script, code symbol, and linter rule your CLAUDE.md cites is checked against reality — so a renamed file or a disabled rule can't silently mislead the agent. →
🧪 Test	Hooks, skills, and subagents are code. vigiles tests they do their job — and almost all of it is deterministic, no API key; the real-model evals run on your Claude subscription, not metered tokens. →

Pick the one that hurts today. Works with Claude Code and Codex (vigiles/codex), and you can teach it your own harness.

Quick start

Paste into Claude Code or Codex:

Set up vigiles in this repo with good defaults (lint + test, non-interactive).
Verify my CLAUDE.md / AGENTS.md references and show me what's stale, then write
and run a harness test for one of my hooks or skills. Ask me first before gating
it in CI, adding a real-model eval, or enforcing strictly (--strict).

Or do it yourself:

npx vigiles init   # sets up lint + test: spec + harness test + CI + plugin

It's interactive in a terminal and non-interactive for agents/CI (or with --yes), so "set up vigiles" from a Claude Code / Codex prompt Just Works — and it installs a model-invocable test-harness skill, so afterward you can just tell your agent "test my skills" and it picks the tier and writes the test.

What init sets up

• Both lint and test by default; scope with --lint / --test (one or both).

• Adds vigiles to your devDependencies.

• Installs the Claude Code plugin (skills + hooks) via the marketplace — globally, never vendored into your repo.

• Wires CI as a zernie/vigiles@v1 workflow (a composite over the same CLI):

  - uses: actions/checkout@v4
  - uses: zernie/vigiles@v1 # lints by default; posts a sticky PR comment + a `valid` output
  

Prefer to write tests yourself? They can be JS or TS (*.harness.{mjs,ts}) — run them with npx vigiles test.

① Lint — your CLAUDE.md lies to your agent

Your CLAUDE.md points the agent at src/auth/login.ts and tells it to run npm run check. But the file moved to src/auth/session.ts six commits ago, and the script was renamed. The agent trusts the stale claim and acts on fiction.

npx vigiles lint resolves every reference against reality:

CLAUDE.md:
  ✗ src/auth/login.ts — no such file (renamed or moved?)
  ✗ npm run check — not in package.json. Did you mean: "check:types"?
  ✓ @typescript-eslint/no-floating-promises — exists and enabled in eslint config

File paths, scripts, and code symbols — plus linter rules across 7 catalogs (the rule exists and is enabled). Start with one inline comment, no new files; step up to a typed .spec.ts (compiled to CLAUDE.md, compiler-grade) when you want it. Full guide →

② Test — does your harness do its job?

A hook can be wired wrong. A skill's description can fail to trigger — or hijack unrelated prompts. Injected context can never reach the model. All of it passes a naive "did it run?" check. vigiles tests the assembled harness for real: