@lakeday/perch

perchscan.com  ·  docs

AST powered semantic code linting with Jev.

Getting started

npm install -g @lakeday/perch
export TYPESAFE_API_KEY=...

perch scan                  # read the repository
perch issues                # what it found, worst first
perch issues 92c7781e       # open one up
perch check 92c7781e        # change it, ask again, nothing committed

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 your own rules, in perch.yaml:

- name: env-read-once
  where: "src/**/*.js"
  each: method
  min: 70
  ensure: >
    This method does not read configuration out of process.env. Reading the
    environment is the command line's job.

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.
How a scan works	The graph walk, the questions, and how probabilities turn into a ranking.

Results go in .perch. Nothing else is written to your tree.

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 your path.