@lakeday/perch

perchscan.com  ·  docs  ·  benchmarks  ·  Discord

Semantic code linting with decision models.

Getting started

npm install -g @lakeday/perch
perch login
perch scan

Run perch login to sign in to Perch Cloud. The first $5 is free. Since decisions are cached, running perch again on unchanged code is free. Perch Cloud also scans pull requests in CI, without writing any workflows.

$ perch scan
checkout.py
  ID        Line  Severity  Type    Confidence  Problem                     Method
  bdc67421    14  P1 (0.8)  defect         81%  wrong_order                 place_order
  ddc5c917    24  P1 (0.8)  defect         92%  inverted_condition          can_fulfil

cart.py
  ID        Line  Severity  Type    Confidence  Problem             Method
  287bfb9d     9  P1 (1.0)  defect         90%  off_by_one          subtotal
  80d6ebbb    29  P1 (1.4)  defect         89%  unhandled_null      cheapest

✖ 20 problems in 5 files, all failing

Run perch issues to see them worst first, and perch issues <id> to view one.

perch check <id> asks again after you think you've fixed it. It doesn't record anything.

Agent skills

perch setup claude-code   # .claude/skills/perch/SKILL.md
perch setup codex         # .codex/skills/perch/SKILL.md
perch setup pi            # .pi/skills/perch/SKILL.md
perch setup cursor        # .cursor/rules/perch.mdc

Semantic linting

You can extend perch with your own linting rules by adding them to perch.yaml:

- name: private-logs
  where: "src/**/*.ts"
  each: method
  ensure: >
    Keep passwords and access tokens out of logs.

Models

By default, Perch Cloud routes your questions to the best model for answering them. To ask a specific decision model, override the endpoint, key, and model:

export PERCH_BASE_URL=https://api.typesafe.ai/v1/systemone
export PERCH_API_KEY='paste-your-TypeSafe-key-here'
export PERCH_MODEL_ID=jev-latest

Model	PERCH_BASE_URL	PERCH_MODEL_ID
Jev	https://api.typesafe.ai/v1/systemone	jev-latest
Liquid AI d1	https://api.liquid.ai/decisions/v1/systemone	d1:free
OpenAI gpt-6-luna	https://api.openai.com/v1/decisions	gpt-6-luna
DiffusionGemma Jev on Beam	https://app.beam.cloud/v1/models/jev/diffusiongemma/invoke	jev/diffusiongemma
SemiF on Beam	https://app.beam.cloud/v1/models/jev/semif/invoke	jev/semif

Any endpoint that supports the System One format will work, and so does OpenAI's Decisions API: perch recognizes a PERCH_BASE_URL ending in /decisions and reads its key from OPENAI_API_KEY when PERCH_API_KEY is not set. Each model gets as many questions per request as it says it takes. For a model that doesn't say, set PERCH_MAX_QUESTIONS. See the benchmarks for a comparison.

Documentation

Getting started	Install, sign in, the first scan.
Reading issues	The list, the filters, closing what does not matter.
Semantic linting	where, each, sees, min, gate, and the longhand grammar.
Checking a change	perch check on work in progress.
perch in CI	What a build can gate on, and what it cannot.
Command reference	Every command, its flags, and what each exit code means.
Inside a scan	The graph walk, the questions, and how probabilities turn into a ranking.

Perch files

Location	Contents
.perch/	Generated scan results and cache files, alongside the committed files below. Use --out <directory> to choose another results location.
.perch/rules/	Custom rules split across .yaml and .yml files. Commit these files.
.perch/closed.jsonl	Dismissed findings and their reasons. Commit this file.
perch.yaml	Custom rules. Updated by perch rules add, edit, and remove.
.claude/, .codex/, .pi/, .cursor/	Instructions installed for the selected assistant by perch setup <assistant>.

Development

npm run check     # lint, typecheck, test
npm run build     # bundle src/cli.js into dist/cli.mjs

To install perch from a checkout, run npm install && npm run build && npm link.