Gnomon Harness

A coding agent whose behaviour is fixed by files in your repository, not by your machine.

Point it at a project, and everything that decides how it acts — which models, which roles, which tools each role may touch, when it must ask permission — lives in one directory called .gnomon/. That directory is hashed. Clone the repo on another machine and you get the same agent.

# Linux / macOS — needs Node >= 22 (the installer tells you how if it is missing)
curl -fsSL https://raw.githubusercontent.com/eljaplacido/gnomonharness/master/scripts/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/eljaplacido/gnomonharness/master/scripts/install.ps1 | iex

Then, in your project:

cd my-project
gnomon setup       # scan the machine, pick a model, write .gnomon/ only on your yes
gnomon dashboard   # optional: the same steps and the project's records, in a browser
gnomon launch      # start working

The installer installs v0.5.0, the latest release. v0.5.0 is also published to npm as gnomon-harness once the release's npm workflow completes; until npm view gnomon-harness version prints 0.5.0, npm i -g gnomon-harness installs the old 0.3.2, so use the installer (it also brings the native binaries; see Install). Update with gnomon update; gnomon uninstall prints how to remove it.

Get started in 3 steps

1. Scan your machine and plug in a local model it can run. In your project, run gnomon setup. It shows your OS, RAM and GPU and which model servers are running, then recommends a model from a dated catalog and says why. With 24 GB of GPU memory or 64 GB of unified memory that is qwen3.6:35b, which solved about two thirds of a 32-task Terminal-Bench set alone on an RTX 5090 in gnomon's own runs (24/32 in R1H; 22/29 and 18/32 in later runs of the same lane, R3R and LG1). Smaller machines get a smaller model, marked "not measured by gnomon". It downloads only if you say yes, and offers a ~10 s speed check.
2. Connect a cloud model (optional). Pick OpenCode Go, OpenRouter, OpenCode Zen or any OpenAI-compatible URL. The key is read hidden and kept outside the repository, as gnomon key set does. Setup then suggests local only or cloud first; it never suggests hybrid. Hybrid is opt-in, not a quality upgrade: type hybrid (or pass --mode hybrid) and the cloud plans while your machine builds. On an RTX 5090 that did not beat cloud-only (R3R, R4H); on an NVIDIA GB10 it solved 22/32 against local-only's 16/31 (p = 0.07). A different mode ships in v0.5.0 as an opt-in cost mode: local-first with cloud rescue, where a cloud model takes over a stuck local turn. You declare it with [roles.<name>.escalate] (Local first, cloud rescue); setup does not configure it. In gnomon's v0.5.0 release runs it spent about 23% of the cloud-only arm's cloud cost, at −0.07 hidden-test share against cloud-only and +0.25 against local-only. Choose cloud-only for the best results. See docs/benchmarks/HYBRID.md.
3. Accept the diff, then gnomon launch. Setup shows its change to .gnomon/ as a diff and writes it only on your yes; gnomon dashboard shows the same steps and the project's records in a browser. gnomon doctor re-checks the machine any time and never changes anything.

Scripted, with nothing asked: gnomon setup --json prints the proposal and exits 4; add --yes to write it, and --expect-proposal <proposal.digest> to write only that reviewed change. --yes never downloads or spends: --pull qwen3.6:35b names a download, and --cloud-endpoint opencode-go --cloud-model deepseek-v4.1-flash names a cloud model. In a browser, gnomon dashboard walks the same steps as buttons.

Start here: the gnomon guide. What gnomon is in one page, a five-minute quick start on a local or a cloud model, copy-paste model recipes (Ollama, llama.cpp, OpenRouter, OpenCode, hybrid local + cloud), troubleshooting and an FAQ. Setting gnomon up for someone as an AI agent? Follow the agent procedure. This README is the full reference.

Why "gnomon"

The gnomon is the blade on a sundial — the part that casts the shadow.

It is also the only part that does not move. The sun travels, the shadow sweeps the hours, but the blade is fixed, and that is precisely why the dial can be read at all. Take the gnomon away and you have a decorated stone.

That is the whole design in one object. The model varies, the conversation wanders, the tools do different things each run — and the .gnomon/ directory does not. Behaviour is readable because something is holding still.

This is the beginning of the README. Read the rest at the original. Read the full README ↗