# gnomon > gnomon is a terminal coding agent whose behaviour is fixed by a content-hashed `.gnomon/` directory in the repository, not by the machine. Roles are separated by the tools they are offered, every change is gated behind an approval diff by default, every step lands in one of three outcome buckets (result, refusal, apparatus_failure), and a hash-chained audit trail records what happened. It runs local models (Ollama, llama.cpp, any OpenAI-compatible server) and cloud models, per role, and `gnomon check` applies the same rules to work done by other harnesses such as Claude Code and opencode. Node 22+; MIT; pre-1.0. Current release: v0.5.0 (2026-11-12), the latest GitHub release and what the installer gives you; published to npm as `gnomon-harness`. 0.4.4 and 0.4.5 were never published, so 0.5.0 carries their changes. 3,466 tests, green on Linux, macOS and Windows; surface-hash fidelity 14/14, degradations 17/17. From 0.4.x: Node 22+ is required; re-run `gnomon guard install --write` for a Claude Code or opencode guard hook (until then it shows as `outdated`); requests to Claude targets now carry prompt-cache markers (`prompt_cache = false` keeps the 0.4.x request bodies); reasoning replay for hosted endpoints is now on by default (`replay_reasoning = false` restores the old behaviour); from 0.3.x run `gnomon migrate` in each project, then re-trust it. New in 0.5.0: no API key reaches a host the trust step would not allow (readiness, doctor, endpoint list/test, setup, fallback and escalate); prompt-cache markers on by default for Claude targets; opt-in local-first cloud rescue ([roles..escalate]) and checkpoint-then-grind; guard liveness, `gnomon check --scorecard` and `gnomon guard install --local`; Node 22 floor; reasoning replay on by default for hosted endpoints (H3: +16 points of hidden tests passed [+4, +29]); `gnomon task --deadline`; governance levels observe/advise/prevent/enforce per rule family, protected secret and CI paths, writes outside the project root refused; guard hardening (host hook files protected, Claude Code bypass mode turns ask into deny, opencode session base, grep/glob governed); the `exec = "docker"` fix against a hostile model; opt-in finish gate v2, deliverable-first notes, soft-timeout shell, first-token watchdog and container sandbox profile, none shown to improve outcomes. Recommendations (gnomon's own v0.5.0 release runs): prompt caching on Claude is on by default — about 93% of input read from cache, $0.029 instead of $0.084 per long benchmark task, no measurable change in hidden tests passed. Start from the defaults — on Claude Haiku they did at least as well as a tuned long-task recipe at about half the cost. A done check before the final answer is opt-in: it makes the final answer more honest, not the outcome better. Hybrid local-first with cloud rescue (a cloud model takes over a stuck local turn; opt-in, [roles..escalate]) is an opt-in cost mode, not a default: about 23% of cloud-only's cloud cost, -0.07 hidden-test share vs cloud-only, +0.25 vs local-only. Those figures are not for the plan-in-the-cloud hybrid that gnomon setup offers as an opt-in mode (it never suggests hybrid), which showed no advantage over cloud-only (R3R, R4H). Shared governance: one committed `.gnomon/` policy is enforced inside Claude Code and opencode (Cursor: shell and reads) by `gnomon guard` in their pre-tool hooks, and checked for any harness at merge time by `gnomon check`; decisions land in a hash-chained trail. In a $0 pilot (scripted model) both hosts made identical decisions on 137/137 forced calls, no denied call ran, and 800/800 records named agent, harness and session; the detachment holes it found are fixed in 0.5.0. Measured (pre-registered, gnomon's own results; peer figures are cited only from before November 2026): on 34 paired short Terminal-Bench tasks against opencode (2026-09-02, v0.2 line) 50.0% vs 47.1%, p = 1.0 — no difference. In November 2026, pooled over three pre-registered studies on long Terminal-Bench tasks against opencode and mini-swe-agent, no difference was shown in either direction; in the latest single study opencode turned more tasks into full solves, while gnomon cost less per task and used fewer tool calls and tokens on the same model (figures unpublished until the benchmark repository is). On 29 long Terminal-Bench 4.0 tasks (gnomon 0.4.1) a tuned hosted recipe raised the hidden-test share from 0.31 to 0.58; reasoning replay alone added 16 points (H3) and is now a default. Of 167 valid hosted long-task runs, 48% hit the 30-minute cap and 68% of those never wrote the required output; ~84% of capped time is model calls, ~1% everything else including gnomon. Did not work: switching the idle nudge off locally (LG1: no gain, 1.43x tokens), the completion gate on a local model (G1-gate: no difference shown) and with a reviewer on hosted 30-minute runs (H4-lite: -10 points), and the RTX 5090 hybrid result (87% vs 84% cloud-only), which did not reproduce and is retracted. gnomon Bench Standards (draft; OVERHEAD, CHAOS, GOVERNANCE, AUDIT, HYBRID, REPORTING, LAYER) gnomon-only figures: +169 ms CPU per run over a null harness, 0.2 ms per policy decision; 17/20 faults announced; 245/280 attacks blocked with the opt-in kernel sandbox (PR #156, unreleased; 170/280 without); self-governance 27/27; audit with a git anchor 7/7, 3/3, 5/5, 0 false alarms in 48. Install: `curl -fsSL https://raw.githubusercontent.com/eljaplacido/gnomonharness/master/scripts/install.sh | sh` (Linux/macOS) or `irm https://raw.githubusercontent.com/eljaplacido/gnomonharness/master/scripts/install.ps1 | iex` (Windows). This installs v0.5.0 with its native binaries. Then, in the project: `gnomon setup`, optionally `gnomon dashboard`, then `gnomon launch`. Or `npm i -g gnomon-harness` (from 0.5.0; no native binaries); the command is `gnomon`. Agents configuring gnomon for a user: follow section 11 of the guide. Never put API keys in `.gnomon/` (use `gnomon key set `), never guess a model id (use `gnomon endpoint list`), and verify with `echo /quit | gnomon prompt`, which makes no model call. ## Docs - [The gnomon guide](https://raw.githubusercontent.com/eljaplacido/gnomonharness/master/docs/GUIDE.md): what it is, architecture, install, quick start, model recipes, commands, use cases, troubleshooting, FAQ, and a step-by-step procedure for agents - [README](https://raw.githubusercontent.com/eljaplacido/gnomonharness/master/README.md): the full reference, including The Six Rules and Known Limits - [Getting started](https://raw.githubusercontent.com/eljaplacido/gnomonharness/master/GETTING_STARTED.md): per-platform install steps, including Windows and from source - [Contracts](https://raw.githubusercontent.com/eljaplacido/gnomonharness/master/docs/CONTRACTS.md): exit codes, enumerations, record shapes, the TOML subset gnomon parses, the `gnomon check` verdict schema ## Optional - [Positioning](https://raw.githubusercontent.com/eljaplacido/gnomonharness/master/docs/POSITIONING.md): where gnomon sits against other harnesses, and what has been measured - [Design](https://raw.githubusercontent.com/eljaplacido/gnomonharness/master/docs/DESIGN.md): the decisions forced by "behaviour is a property of the repository" - [Governance check design](https://raw.githubusercontent.com/eljaplacido/gnomonharness/master/docs/GOVERNANCE-CHECK-DESIGN.md): how `gnomon check` judges other harnesses' work - [Benchmark findings, 2026-11-04](https://raw.githubusercontent.com/eljaplacido/gnomonharness/master/docs/benchmarks/FINDINGS-2026-11-04.md): long tasks, hybrid on current builds, causal analysis - [gnomon Bench Standards](https://raw.githubusercontent.com/eljaplacido/gnomonharness/master/docs/benchmarks/README.md): draft open benchmarks for what a harness decides - [Sandbox design](https://raw.githubusercontent.com/eljaplacido/gnomonharness/master/docs/SANDBOX-DESIGN.md): what `[sandbox] exec = "docker"` does and does not contain - [Agents working on this repository](https://raw.githubusercontent.com/eljaplacido/gnomonharness/master/AGENTS.md): build, test and conventions for contributors - [Contributing](https://raw.githubusercontent.com/eljaplacido/gnomonharness/master/CONTRIBUTING.md): how changes are proposed, reviewed and merged - [Exec threat model](https://raw.githubusercontent.com/eljaplacido/gnomonharness/master/docs/THREAT-MODEL-EXEC.md): what `exec = "docker"` defends against, and what it does not - [Evidence](https://raw.githubusercontent.com/eljaplacido/gnomonharness/master/docs/EVIDENCE.md): every claim gnomon makes about itself, the measurement behind it and its date