HarnessME reads the structure and conventions that already exist in a repository, then produces a maintained AGENTS.md, scoped module guides, and agent-specific integrations. It tells agents where to make changes, what must remain true, how to validate their work, and when they must ask a developer before touching a core area.

Why HarnessME?

Generic instructions make an agent guess. HarnessME makes the repository legible: it grounds guidance in real files and validation commands, highlights coupled changes, detects documentation drift, and protects high-impact paths with an explicit human gate. It is a local, scriptable CLI—no hosted service or HarnessME account required.

Quick start

Requires Node.js 26.4 or newer on Windows, macOS, or Linux.

npm install -g harnessme
cd your-repository
harnessme

harnessme opens the interactive dashboard. On a repository without a harness, select Initialize; it guides you through provider, model, thinking level, review depth, and optional project context before it writes anything.

Use

Dashboard — recommended

Run harnessme from a repository root at any time. The dashboard is the default interface and keeps the whole lifecycle in one place:

1. Dashboard — inspect harness health, provider/model settings, safety-gate counts, and every generated harness document. Use [ / ] or Tab to switch the root contract, scoped guides, agent pack, critical policy, and nested module contracts.
2. Guided configuration — choose a provider, model, Codex thinking level, review depth, and optional context without remembering flags.
3. Operation progress — follow analysis, AI review, authored guidance, and integration steps in real time.
4. Quality intelligence, history, and remediation — compare evidence, navigation, operations, documentation, and governance; inspect score trends across initialization, refreshes, and fixes; then select any failed check to see its recoverable points, projected score, recommended workflow, and verified result.
5. Critical Gate Manager — activate, dismiss, remove, or add explicit developer-confirmation gates for sensitive paths. Dismissed proposals stay dismissed after refresh.
6. Knowledge Graph — stay inside the terminal, press G to switch between structured and force-directed views, or press P on two nodes to explain their relationship path.
7. Generation safety — preview generated-document diffs in an isolated workspace and restore one of the latest 20 local snapshots without rolling back source code or maintainer facts.

CLI commands

Use commands when scripting, running CI, or when you already know the operation you need:

harnessme init             # create a harness non-interactively or with prompts
harnessme init --targets codex,pr-agent  # generate selected formats plus PR-Agent's .pr_agent.toml
harnessme refresh          # update it after repository changes
harnessme quality          # report quality dimensions and next best action
harnessme sync --preview   # preview generated-document changes without writing
harnessme generation list  # inspect local generated-document snapshots
harnessme check --ci       # fail CI when repository facts have drifted
harnessme feature list     # inspect semantic features in the committed graph
harnessme context src/api/auth.ts  # assemble bounded pre-edit context for one file
harnessme mcp                      # serve repository context to MCP-capable agents over stdio

The complete command and critical-change workflow reference is available further down this README.

What you get

• A concise root AGENTS.md that keeps maintainer rules and active protected paths visible and loads the canonical agent contract on every task. Agents open only the references relevant to their change, then inspect nearby source and tests.
• A canonical .harnessme/agent-pack/agent.md that routes agents to task-relevant references, names protected boundaries, and surfaces up to five source-grounded invariants. The detailed generated operating contract lives in .harnessme/agent-pack/contract.md; imported maintainer rules stay in the root file.
• Short nested module guides that link scoped references. Agents use harnessme context <path> when local navigation does not establish owners, dependencies, or tests.
• .harnessme/CRITICAL.md, its machine-readable .harnessme/critical.json companion, rollback guidance, and enforceable gates for core, security, persistence, billing, deployment, and public-contract changes.
• A default confirmation rule for foundational entry methods and core infrastructure contracts, including startup, orchestration, model and prompt factories, tool registration, request handling, persisted state, and public event mapping. A newly identified boundary receives an active gate before editing.
• Provider files for Codex, Claude Code, Claude Desktop, Cursor, PR-Agent, and other selected agent formats.
• A critical dashboard and harnessme quality scorecard with five weighted dimensions, evidence breadth, semantic file coverage, context-delivery coverage for leading critical paths, dependency density, test linkage, cited and actionable guide depth, generated-link integrity, assessment confidence, historical trends, ranked findings, and executable remediation plans. Initialization alone cannot earn 100; unresolved critical-path proposals cap the score below "excellent."
• A version-controlled .harnessme/knowledge-graph.json, agent-facing feature map, and terminal explorer with structured and force-directed views.
• Existing configuration, deployment, and documentation paths can ground AI-reviewed feature scopes; only cited and bounded representative paths enter the generated graph.

Requirements

HarnessME requires Node.js 26.4 or newer on Windows, macOS, or Linux. The dashboard automatically enables Node's experimental FFI flag required by OpenTUI. After installation, run every command directly as harnessme … from the repository you want to analyze.

For model-assisted generation, install and sign in to at least one supported framework CLI: Codex, Claude Code, or Cursor. Use --deterministic when you want a fully local run without model inference.

HarnessME verifies the selected CLI's login status before inference. Run harnessme providers doctor --provider cursor to check installation, login, and model discovery; add --probe to make one live structured-output call and measure its response time. The probe can use a model override with --model. The cursor-agent command is supported, as is Cursor's agent command; a different program named agent is ignored. Cursor may return an error inside an otherwise successful JSON process result; HarnessME reports that error directly. Initialization and refresh now report each model stage, completion time, and a still-running signal every 30 seconds without printing prompts or responses. Cursor-assisted initialization makes several model calls and can take minutes per phase. For slow or model-specific behavior, pass an available model ID with --model; --council-size 1 reduces the number of review calls.

How the harness is created

When harnessme init runs, it:

1. Scans supported source files with bundled syntax-tree grammars and reads repository configuration and documentation, including nested maintainer guides under .agents/.
2. Reads package metadata, formatter and linter settings, type configuration, contribution documentation, and Git history.
3. Detects the project purpose, repository structure, coding conventions, domain invariants, module ownership, validation commands, import hubs, frequently changed files, and documentation references that no longer match the implementation.
4. Stores those findings in .harnessme/facts/. Every inferred convention includes a repository-relative file and line citation; local imports retain their source lines for graph evidence. Source and discovered-document hashes let harnessme check detect content changes even when the file list stays the same.
5. Builds a deterministic AGENTS.md baseline and a bounded list of possible critical files and modules. Deterministic citations identify source to inspect; they are not presented as verified behavioral invariants.
6. Uses a four-stage model pipeline when AI is enabled: evidence extraction, independent claim verification, harness/reference authorship, and final baseline comparison. The author and reviewers receive the same bounded, redacted repository context; it is never stored. The review council validates every candidate and selects the strongest valid result based on concrete paths, symbols, citations, workflows, and scoped coverage. A focused repair pass runs only when local validation rejects every candidate.
7. Authors a concise repository-specific root AGENTS.md, reviewed semantic feature definitions, a dedicated agent pack with architecture routing and a critical-change audit standard, and concern-focused executable change manuals. Each scoped guide identifies responsibilities, supported extension seams, invariants, coupled change impact, anti-patterns, workflows, validation, and maintenance triggers. HarnessME then places detailed nested AGENTS.md operating contracts in the applicable module directories. Cross-cutting guides can cover multiple concrete scopes. Obsolete managed module guides are removed on refresh.
8. Builds .harnessme/knowledge-graph.json, .harnessme/FEATURES.md, and focused feature guides. Deterministic runs map modules, files, tests, imports, documentation, and critical paths, including links from maintainer guides to the exact source files they cite. harnessme context uses those links to surface relevant guides for a changed file. Reviewed AI runs add evidence-backed feature meaning. Maintainer overrides always win. Refresh retains reviewed active gates. If a model draft omits a feature, refresh retains its existing guide while the source files in its scope and its cited evidence remain unchanged.
9. Classifies proposed gates as security, persistence, public-contract, billing, deployment, shared-core, or other. Test files are excluded from automatic gate nominations. An imported maintainer rule that explicitly protects a named Python method becomes an active file gate only when its definition resolves to one source file; ambiguous names remain in the preserved directive. Other candidates stay proposed until reviewed.
10. Scores the resulting harness for purpose, documentation, validation, evidence, operating rules, core boundaries, workflows, feature navigation, scoped references, and documentation consistency.
11. Enforces safety language and managed placeholders locally, distributes the result to every selected framework, and generates .harnessme/CRITICAL.md, .harnessme/critical.json, CODEOWNERS, a Claude Code hook when selected, Lefthook configuration, and a GitHub Actions workflow.

Existing unmanaged AGENTS.md instructions are preserved as project directives instead of being discarded. An imported root contract is archived at .harnessme/imported-AGENTS.md, and unmanaged nested contracts remain in place. Application source files are analyzed but not rewritten.

Framework model inference and fallback

Model-assisted generation reuses the authentication from Codex, Claude Code, or Cursor. Choose the runtime with --provider; auto resolves the first installed supported CLI:

harnessme init --provider auto

When run in a terminal without --model, HarnessME asks you to select a model after resolving the provider. Codex and Cursor expose their available model catalogs; providers that cannot enumerate models offer their configured default or a manually entered model ID. Codex also offers Fast, Balanced, and Deep thinking levels, which map to its native reasoning-effort setting. For scripts and CI, set that choice explicitly with --thinking-level low|medium|high (Codex only):

harnessme init --provider codex --model your-model --thinking-level high

Supported inference runtimes are codex, claude-code, and cursor. HarnessME runs them non-interactively in an isolated temporary directory containing only bounded, redacted analysis input—not the repository itself. Input selection prioritizes the root README, architecture/policy documents, manifests, and a balanced sample of core source from each module. The model first enriches deterministic findings with structured, evidence-cited facts. It then authors the full AGENTS.md and scoped change manuals from verified facts, the deterministic baseline, and that same audited context. Existing repository documentation is used through progressive disclosure: the root contract routes agents to task-relevant documents and states when those documents must change with the code instead of duplicating them. Independent review candidates compare and edit the harness before HarnessME selects the deepest valid candidate and validates pre-edit guidance, actionable operating rules and workflows, concrete core boundaries, extension seams, coupled changes, anti-patterns, documentation routing, exact validation commands, safety language, managed placeholders, and chosen gate paths. Inventory-style output such as language percentages is rejected. AI mode never substitutes a deterministic document: it retries validation repairs up to three times and then fails clearly, leaving no newly rendered fallback harness. Use --deterministic only when local-only generation is explicitly intended.

For a second opinion, assign a separate reviewer with --review-provider. The reviewer verifies proposed facts before storage, then receives the redacted validated evidence bundle, deterministic baseline, and draft for the final comparison. A different provider is recommended when available:

harnessme init --provider codex --review-provider claude-code

Without --review-provider, the selected runtime performs a separate review call. With it, both fact verification and final-document comparison use the independent reviewer. AI may activate a critical gate only for a concrete file or module discovered by deterministic analysis; the local Git-content approval mechanism remains deterministic and still requires an authorized human reviewer.

An OpenAI-compatible endpoint, including a local Ollama server, remains available when no framework CLI is suitable:

harnessme init --provider http --ai-endpoint http://localhost:11434/v1/chat/completions --model qwen2.5-coder:7b

For an authenticated endpoint, add --ai-api-key-env AI_API_KEY. The reviewer endpoint equivalents are --review-ai-endpoint, --review-model, and --review-ai-api-key-env. Model inference examines text-like source files within configured size limits. Git-ignored files, common credential paths, .harnessmeignore entries, secret-like lines, and prompt-injection-like lines are excluded or redacted before inference. Proposed facts must pass schema validation, local file-and-line citation checks, and model verification before entering the facts store. The audit at .harnessme/facts/ai-inputs.json records paths, byte counts, and redaction counts—never file contents.

The reviewed AI template is stored at .harnessme/facts/AGENTS.authored.md; scoped documents are stored in .harnessme/facts/references.json and rendered under .harnessme/references/. The generated .harnessme/agent-pack/architecture.md routes agents to the smallest applicable guide, while critical-change-audit.md defines the required audit record for confirmed protected edits. .harnessme/facts/harness-generation.json records the author/reviewer runtimes, models, comparison summary, activated gates, and per-call inference durations. It records no prompts or responses. .harnessme/facts/conflicts.json reports documentation paths that disagree with the repository, .harnessme/facts/quality.json records the current scored checks, and .harnessme/facts/quality-history.json retains the latest 100 initialization, refresh, and remediation snapshots. HarnessME owns the critical-path, directives, verified-changes, and pending-note placeholders so later governance commands can update them without discarding maintainer content.

Preview exactly which files would be included without contacting a model or writing the harness:

harnessme init --ai-preview

Use --ai-include "src/**", --ai-exclude "src/generated/**", or add patterns to .harnessmeignore for finer control. Use --deterministic to disable model inference for offline or privacy-sensitive runs.

After the repository changes, run harnessme refresh. It reuses the provider, model, privacy filters, and reviewer stored during initialization, preserves maintainer directives, approved critical records, verified changes, and pending notes, and rewrites only HarnessME-managed guidance. Pass --deterministic for an offline refresh.

Command reference

Commands that operate on a repository accept --root <path> to operate on another repository root. Use harnessme --help for built-in help and harnessme --version to print the installed version.

| Command | Purpose | Options | | --- | --- | --- | | harnessme init | Analyze a repository and stage the complete harness before applying it. | --provider auto|codex|claude-code|cursor|http, --review-provider …, --targets <comma-list>, --model <name>, --thinking-level low|medium|high (Codex), --review-model <name>, --ai-endpoint <url>, --review-ai-endpoint <url>, --ai-api-key-env <env>, --review-ai-api-key-env <env>, --ai-include <comma-list>, --ai-exclude <comma-list>, --ai-preview, --deterministic, --critical-approvers <comma-list>, --details <text> | | harnessme scan | Report source and documentation drift without writing. | No command-specific options. | | harnessme refresh | Stage updated facts and guidance together while preserving directives, approvals, verified changes, and pending notes. | --deterministic, --details <text> | | harnessme sync | Stage and validate generated files, then apply them with rollback if the update fails. | --targets <comma-list>, --preview | | harnessme generation list | List the latest local generated-document snapshots. | — | | harnessme generation preview | Render in an isolated temporary workspace and show the pending file-level diff. | --targets <comma-list> | | harnessme generation rollback [id] | Stage a generated-document snapshot and its history update before restoring them, defaulting to the previous generation. | --preview shows the rollback diff without writing. | | harnessme quality | Score five quality dimensions, print coverage/depth metrics, and rank corrective actions. | No command-specific options. | | harnessme validate | Verify pending notes and stage the fact and generated-file refresh before applying it. | --max-retries <non-negative integer>, --ci | | harnessme check | Fail when stored facts, analyzed source or document contents, or generated guidance have drifted. | --ci | | harnessme directive add <text> | Add a maintainer-authored instruction. | — | | harnessme directive list | Print maintained directives. | — | | harnessme critical add <glob> | Register a risk-classified critical path. | --reason <text> and --approvers <comma-list> are required; --risk security|persistence|public-contract|billing|deployment|shared-core|other overrides automatic classification. | | harnessme critical list | List critical-path rules. | — | | harnessme critical activate <glob> | Activate a proposed critical path and record the review decision. | --reason <text> is required. | | harnessme critical remove <glob> | Remove an active or proposed critical-path rule, record why, remember the dismissal across refreshes, and regenerate governance files. Imported maintainer directives protect their entry-method gates from removal. | --reason <text> is required. | | harnessme critical review --file <plan.yaml> | Validate and apply several proposed-gate decisions with one sync and quality snapshot. | Use --dry-run to preview; every decision needs a reason. | | harnessme critical draft <path> | Start a review record before changing a critical file. | --summary <text> is required. | | harnessme critical approve <record.md> | Bind an approved record to staged content. | --approver <handle> is required. | | harnessme critical-gate | Run the critical-path gate (normally invoked by hooks/CI). | --path <file> for edit checks, --base <git-revision> for CI, or --hook for Claude Code hook input. | | harnessme hooks install | Install the generated cross-platform Git pre-commit gate. | — | | harnessme hooks status | Report whether the local gate is installed. | — | | harnessme providers list | List selectable inference providers. | — | | harnessme providers doctor | Check CLI installation, login, and model discovery; optionally make a timed structured-output probe. | --provider all\|codex\|claude-code\|cursor\|http, --probe, --model, --endpoint, --api-key-env | | harnessme targets list | List generated integration targets. | — | | harnessme feature list | List features and concerns in the knowledge graph. | — | | harnessme feature path <from> <to> | Explain the shortest relationship path between node IDs, repository paths, or unique labels. | — | | harnessme context <path> | Combine the path's owning features, directly citing maintainer guides, dependencies, consumers, tests, gates, and validation. | --changed resolves all current Git changes; --json emits structured output. | | harnessme feature add <slug> | Add a maintainer-owned feature definition. | --title, --summary, and comma-separated --scopes are required; --kind feature\|concern is optional. | | harnessme feature edit <slug> | Override generated feature metadata. | Optional --title, --summary, and --scopes. | | harnessme feature remove <slug> | Remove a manual feature or exclude a generated feature. | — | | harnessme feature link <from> <to> | Add a feature relationship. | --kind depends-on\|related-to. | | harnessme feature unlink <from> <to> | Remove or exclude a feature relationship. | --kind depends-on\|related-to. |

Directive, critical-path, and feature changes stage their stored settings, generated integrations, and history together. Critical approval stages its record, index, and manifest together. Dashboard provider changes and multi-step quality or gate workflows use the same commit boundary. A failed update leaves the existing repository files unchanged.

--provider and --review-provider select inference runtimes. --targets selects generated instruction formats; the two settings are intentionally independent. The HTTP provider requires --ai-endpoint and --model; HTTP review requires --review-ai-endpoint and --review-model.

MCP server

Run harnessme mcp --root <repository> to expose the initialized repository through the local stdio Model Context Protocol. Configure an MCP-capable client with harnessme as the command and mcp --root <repository> as its arguments.

The server tells non-coding clients to call the read-only harnessme_preflight tool before edits and Git/PR actions. That tool returns the root and canonical agent contract, nearest scoped instructions, critical-path approval decision, graph context, and validation plan for the supplied paths. The server also provides harnessme_quality, harnessme_change_context, harnessme_critical_paths, harnessme_feature_graph, and harnessme_validation_plan. harnessme_draft_critical_record, harnessme_add_directive, and harnessme_refresh write managed artifacts only when their explicit confirmation parameter is true; drafting never approves a critical change.

For Claude Desktop, select the claude-desktop target and follow the generated .harnessme/integrations/claude-desktop.md. It contains an MCP configuration template and copy-ready Project custom instructions. MCP instructions are advisory when a separate filesystem/git server owns writes; the generated Git hook and CI workflow remain the hard enforcement layer.

Generation snapshots are local, Git-ignored, capped at 20, and contain only wholly generated documents. Rollback preserves the current pending-update section and never replaces merged maintainer configuration such as CODEOWNERS, Lefthook, or provider settings.

Keep the harness current:

harnessme scan                 # report differences without writing
harnessme refresh              # reanalyze and update the operating contract and scoped references
harnessme quality              # show the harness quality score and missing guidance
harnessme validate             # verify pending notes from AGENTS.md
harnessme sync                 # regenerate provider files
harnessme check --ci           # fail when facts have drifted
harnessme feature add authentication --title "Authentication" --summary "Request identity and session enforcement" --scopes "src/auth/**,tests/auth/**"
harnessme feature path src/auth.ts sessions
harnessme context src/auth.ts

Add a project policy that cannot be inferred from source code:

harnessme directive add "Use OAuth2 for authentication"

Protect a critical area:

harnessme critical add "src/payments/**" --reason "money movement" --approvers "alice,bob"
harnessme critical draft "src/payments/refund.ts" --summary "support partial refunds"
# A listed human reviewer reviews the record and staged code, then:
harnessme critical approve <record.md> --approver alice
git add .harnessme/critical-log/<record.md> .harnessme/CRITICAL.md .harnessme/critical.json

In deterministic-only mode, heuristic paths begin as proposed. Review them first, then activate an accepted rule. In AI mode, the final comparison may activate evidence-backed core paths automatically and records them with source ai-reviewed:

harnessme critical list
harnessme critical activate "src/core.ts" --reason "Shared contract used by multiple consumers"
harnessme critical remove "src/core.ts" --reason "Reviewed path is not a protected contract"

For a larger queue, write a review plan and validate it before applying:

schemaVersion: 1
decisions:
  - glob: src/core.ts
    decision: activate
    reason: Shared contract used by several consumers
  - glob: src/fixture.ts
    decision: dismiss
    reason: Fixture constant has no protected behavior

harnessme critical review --file gate-review.yaml --dry-run
harnessme critical review --file gate-review.yaml

The batch command rejects duplicate, unknown, already active, or directive-protected dismissal entries before writing any decision.

For registered paths, generated agent instructions require explicit developer confirmation before editing. Claude Code receives a native permission prompt; the Git hook and CI read the staged or committed record, index, manifest, and gate registry from the same Git snapshot. They reject changes unless an allowed approver's record matches the exact changed content and ships with the updated governance artifacts. The --approver flag records a claimed handle; it does not authenticate identity. Require code owner review in GitHub branch rules for human approval before merge. The generated CI gate runs for pull requests and direct pushes to main after the branch has a prior revision. Gates active in the baseline revision still govern code changed in the same commit that removes or weakens them. harnessme check verifies the generated CI gate; when .github/workflows/harnessme.yml is user-owned, HarnessME creates .github/workflows/harnessme-generated.yml beside it.

Activation and dismissal decisions are recorded with a reason and timestamp in .harnessme/critical-paths.yaml; refresh preserves that review history. Gate changes also add a quality-history snapshot so score trends include reviewed governance changes.

Gates derived from imported AGENTS.md entry-method restrictions remain active while those directives apply. critical remove rejects their removal, check reports a missing gate, and refresh restores one even if the registry was manually edited. Edit and commit gates also consult the stored directives, so a registry edit alone cannot permit a protected source change.

Behind the scenes

• web-tree-sitter and VS Code WASM grammars for deterministic multi-language analysis
• OpenTUI for the cross-platform full-screen terminal dashboard
• zod for validating the version-controlled facts store
• Ruler for distributing instructions to agent-specific formats
• js-yaml, TOML, and frontmatter parsing for project configuration and critical-change records
• Git history for hotspot detection and git-native critical-path checks
• Import-graph fan-in and AST patterns for core-module and architecture detection
• Authenticated Codex, Claude Code, or Cursor CLI sessions for optional model-assisted harness inference
• Full AI authorship plus a separate baseline-comparison and correction pass for AGENTS.md
• Claude Code hooks, Lefthook, GitHub Actions, and CODEOWNERS for governance backstops
• Explicit labels distinguishing observed, AI-assisted, maintainer-authored, proposed, and active guidance

Development

npm install
npm run lint
npm test
npm run test:package

To compare coding-agent task outcomes, use python3 scripts/benchmark_agents.py --manifest /private/manifest.json --output /private/results. The opt-in manifest names local repositories, historical base and fix commits, task prompts, hidden gold test files, verifier commands, and baseline/candidate setup commands. Keep manifests and results outside this public repository. The runner checks out only each task's base commit, runs Codex before restoring gold tests, and writes JSONL events, verifier logs, token counts, and a result table to the private output directory. Review pass/fail and protected edits before making a release decision.

License

MIT