local · read-only · evidence-first

opstruth

AI coding tools are fast.OpsTruth checks what is actually true afterwards.

A local CLI that inspects your repo, picks safe probes, and writes evidence without deploying, mutating, or calling out to anything.

$npm install -g opstruth

$opstruth

$npx opstruth

View on GitHub

Current product demo

56 seconds · 16:9 · sound

Mobile proof short

26 seconds · 9:16 · sound

Catalogue probes: 30
Mutating actions: 0
Raw secrets printed: 0
Default report: Markdown evidence file

Current product video set

One product truth.Three formats for the screen in front of you.

The current videos are grounded in the 0.2.0 repo, package, release, website, and CLI truth. The landscape cuts explain the product and workflow; the portrait cut is sized for mobile screens without squeezing a desktop frame.

Package: opstruth@0.2.0
Release: GitHub v0.2.0
Video set: Product demo · tour · mobile short
Proof model: Exact-commit CI + explicit live evidence

Product proof demo

56 seconds · 16:9 · sound

Explains the problem, the read-only safety model, and the current 0.2.0 proof surfaces.

Mobile proof short

26 seconds · 9:16 · sound

A portrait cut for phone screens and social previews, using the same evidence-first product truth.

Product tour

96 seconds · 16:9 · sound

Walks through the real CLI flow: install, welcome, init, probes, secrets, routes, local checks, CI, Supabase evidence, and JSON output.

The gap

Generation is fast. Certainty isn't.

AI tools edit dozens of files in seconds. What they don't do is tell you, calmly and concretely, what the resulting state of your project actually is.

OpsTruth answers six questions, every run, in the same order:

01what changed?
02what is configured?
03what looks risky?
04what was verified?
05what was NOT verified?
06what did the tool explicitly NOT do?

Operational proof gap

The useful answer is not just pass or fail.

OpsTruth separates facts from assumptions so a human reviewer can see what became more certain, what remains a proof gap, and which actions were intentionally outside scope.

Verified

/project boundary resolved before scanning
/30 probes in the catalogue
/15 safe automatic probes selected here
/quality scripts run only when present

Not verified

/production route availability without --base-url
/local runtime liveness without --port or health input
/database exposure when Supabase config is absent
/remote CI or deployed state unless attached separately

Did not do

/deploy
/mutate databases
/call OpenAI or other model APIs
/restart services, kill processes, or trigger queues

Probe catalogue

Stack-aware checks, evidence per finding.

Each probe declares what it checks, what it proves, what it does not prove, and the next safe step.

Repo state

Working tree, branch, recent changes, diff check, and conflict marker scan inside the resolved boundary.

Proves what git can see; does not prove deployment state.

Stack detection

TypeScript, React, Vite, Next.js, Docker, GitHub Actions, Vercel, Netlify, Supabase, and Cloudflare signals.

Selects safe probes from the catalogue; does not invent missing checks.

Secret scanning

Pattern-based detection with redacted previews. Raw secrets never leave your terminal.

Shows file, line, pattern, why it matters, and next safe step.

Route checks

Reachability and status of declared routes when a base URL is provided. Skipped honestly otherwise.

Uses read-only HEAD/GET; does not authenticate or cover every flow.

Runtime checks

Opt-in probes against a running service. Local-first, no agents installed.

Checks explicit ports and health inputs; never starts or restarts services.

Supabase exposure

Heuristics for anon keys, public RLS gaps, and client-exposed config.

Static and config-aware unless stronger inputs are attached.

Cloudflare config

Inspects wrangler.toml, bindings, and deployment surface for obvious risk.

Reads local config; does not deploy or mutate Cloudflare state.

Evidence pack

A structured markdown report with file, line, and operational meaning for every finding.

Designed for PRs, CI artifacts, and AI-to-human handoffs.

Example output

Calm. Structured. Honest about gaps.

This excerpt is from the local checkout with evidence writing skipped for display. The normal run writes a Markdown evidence pack to evidence/opstruth-report.md.

verified
warning
not verified

advanced_pudding9228@web — opstruth

$ node bin/opstruth.js --skip evidence
Operational truth checks for AI-assisted engineering.
 
STATUS: Partial pass
One-command operational truth check completed.
 
✓ Verified
Project boundary: /home/johnh/opstruth
Probe catalogue entries: 30
Automatic safe probes selected: 15
Platforms detected: TypeScript, Node ESM, GitHub Actions
 
! Warnings
None
 
○ Not Verified
Production/public route availability was not checked
Local runtime liveness was not checked
Supabase database exposure was not checked
 
× Did NOT do
No deploys, database mutations, OpenAI calls, publishing, queue triggers, restarts, or kills
 
Next: add --base-url or --port when route or runtime proof matters.

GitHub-first workflow

The checks are open and reviewable.

OpsTruth is meant to be inspected, run locally, attached to PRs, and extended through concrete probe requests. The site sends developers back to the evidence, not a black box.

Safety model

read-only boundaries, ignored folders, reporting philosophy

Probe catalogue

what each probe collects, proves, and does not prove

Fixture evidence

Vite, Next, Node, Supabase/Cloudflare, and risky secret examples

Community testing

run real repos, report false positives, request missing probes

GitHub Actions evidence job

- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: 20
- run: npm install
- run: node bin/opstruth.js --strict --out evidence/opstruth.md
- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: opstruth-evidence
    path: evidence/opstruth.md

Boundaries

What OpsTruth will never do.

The read-only boundary is the product. It is enforced in code, visible in output, and documented per probe.

deploy
no push, no release, no environment change
mutate databases
no writes, no migrations, no seeds
publish content
no posts, no uploads, no outbound webhooks
restart services
no process control, no orchestrator calls
trigger jobs
no queues, no cron, no background workers kicked off
call AI providers
no OpenAI, no Anthropic, no model calls of any kind
print raw secrets
patterns are redacted before they reach your terminal

Evidence pack

One Markdown report. Easy to review, share, and attach.

Every default run writes a report you can paste into a PR, attach to a CI artifact, or hand to a reviewer. It is intentionally plain: evidence first, no dashboard required.

Example evidence reportread-only

# OpsTruth Evidence Pack

Status: Partial pass
Working directory: redacted fixture checkout
Commands run: git diff --check, npm run test

## Risks And Gaps

warn: src/config.js:1 matched OpenAI key pattern
evidence: redacted preview: service key value was replaced with [REDACTED]
warn: src/config.js:2 matched Supabase service role pattern
why it matters: secret-like values can create account, data, or infrastructure exposure.
next: move real secrets to secret storage and keep placeholders in source.

## Not verified

· production/public route availability was not checked
· local runtime liveness was not checked
· no OpenAI usage was monitored

Community testing

Run OpsTruth on a real repository. Report false positives. Request a missing probe.

OpsTruth is local, open, and inspectable. The probe catalogue grows with real operational pain — not with what sounds impressive on a homepage. It is for developers, founders, agencies, and teams who need to understand AI-assisted changes before touching production.

$opstruth

$opstruth --out evidence/opstruth.md

runs locally · writes one file · changes nothing

Start with the CLI

Run OpsTruth first. It can surface proof gaps in repo structure, deployment assumptions, secret exposure risk, runtime inputs, and what still needs a human decision.

Need more than a CLI report?

Some AI-built websites, apps, and automations need a focused diagnostic review before production changes. If the report shows risk you cannot interpret safely, open an issue with the evidence and ask for the next narrow review.

Open an issue