GitHub Trending Explorer

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 costs a tenth as much. 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`
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. Beam decision models only accept 32 questions per request, which is fewer than a security scan asks of one method. Until #257 is resolved, limit scan_types to defect and lint when using a Beam model. 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.

lakeday-org/perch

Star growth