Schramm2/spyglass

their work. It connects browser actions, HTTP calls, database reads and
repository checks to one run. Each run records its source identity, every
attempt (failed attempts too) and its artifacts. The evidence stays after
cleanup, so another agent or person can inspect the result later without the
original chat or shell.
> [!NOTE]
> Spyglass 1.3.0 uses version 1 profile, plan and result schemas.
## Why Spyglass
An agent can say "the tests pass" or "the page works". That statement is not
proof. Spyglass makes each verification step a recorded fact:
Real tools, no mocks. Spyglass drives a real browser, real HTTP requests,
a real PostgreSQL database and the repository's own checks.
Evidence that stays. Screenshots, responses, query rows and logs go to a
Git-ignored evidence folder with checksums. Cleanup does not remove them.
Honest results. Failed attempts stay in the record. A report stays
incomplete until each claim has a completed step and its evidence.
Source identity. Each run records the commit and working-tree state.
Evidence from source that changed after the run started cannot pass as
proof for the original source.
Safe by default. The browser can open only the configured origins.
Database queries run in a read-only transaction. Reports mask credentials,
cookies and authorization headers.
Built for agents. Each command gives a versioned JSON result with
--json, uses stable exit codes and never prompts.
Spyglass does not decide whether a claim covers the request, or whether a
screenshot looks correct. The operator (the agent or person) selects the
claims and judges the results. Spyglass makes sure that the cited steps
completed, the artifacts exist, the source is current and the cleanup is done.
## Requirements
Node.js 24 or later
Git
These tools are necessary only for some surfaces:
| Tool | Necessary for |
| agent-browser 0.38.2 | up for a profile with a web origin. Browser checks (ui) also need its Chromium. |
| Docker Compose | Container status and logs (ps, logs) |
| A PostgreSQL database | Database reads (db). The driver is included. |
Spyglass does not install tools, fetch secrets or start your app during init.
## Installation
Spyglass is not on npm yet. Install it from source:
sh
git clone --branch v1.3.0 https://github.com/Schramm2/spyglass.git
cd spyglass
npm ci
npm run build
npm link
spyglass --version
## Quick start
The terminal quickstart runs a local demo app. It records
a deliberate failure and a passing check, and keeps the report after cleanup.
It takes approximately five minutes and uses no paid services.
In your own repository, the workflow is:
sh
spyglass init # write spyglass.json; review it
spyglass up --run my-change --plan verification-plan.json --json
spyglass check verify --run my-change --claim CLAIMID --json # run a check; link it to a claim
spyglass result set --run my-change --claim CLAIMID --outcome passed --observed "WHAT YOU SAW"
spyglass status --work --run my-change # what each claim still needs
spyglass result --check --run my-change # validate; record nothing
spyglass finish --run my-change --json # result, doctor, down and report
finish runs result, doctor, down and report in order. You can run each