lakeday-org/perch

perchscan.com  ·  docs  ·  benchmarks  ·  Discord

Semantic code linting with decision models.

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.

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

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.

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

Any endpoint that supports the System One format will work. 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.

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.