@lakeday/perch

perchscan.com  ·  docs  ·  Discord

Semantic code linting with Jev.

Getting started

Create an API key at console.typesafe.ai, then set the System One request URL and your key:

npm install -g @lakeday/perch
export PERCH_BASE_URL=https://api.typesafe.ai/v1/systemone
export PERCH_API_KEY='paste-your-TypeSafe-key-here'
perch scan

$ 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.

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

Extend perch with custom rules, in perch.yaml:

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

Documentation

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.

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

From a checkout: npm install && npm run build && npm link puts perch on the path.