Semantic code linting with Jev.
Create an API key at console.typesafe.ai and set
it as PERCH_API_KEY.
npm install -g @lakeday/perch
export PERCH_API_KEY=<your TypeSafe API key>
bash
$ 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
perch issues lists them worst first. perch issues <id> opens one up. perch check <id> asks again after a fix, and records what it finds nowhere.
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
Extend perch with custom rules, in perch.yaml:
- name: env-read-once
where: "src/**/*.js"
each: method
min: 70
ensure: >
This method takes its configuration as arguments. Reading process.env is the
command line's job.
| Getting started | Install, the key, 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. |
| 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 , andremove . |
.claude/ ,.codex/ ,.pi/ ,.cursor/ |
Instructions installed for the selected assistant by perch setup <assistant> . |
npm run check # lint, typecheck, test
npm run build # bundle src/cli.js into dist/cli.mjs
From a checkout: npm install && npm run build && npm link puts perch on the
path.