perch README

The project's README from github.com/lakeday-org/perch. As one markdown file: README.md.

perch

npm ci node license perch

perchscan.com  ·  docs

Semantic code linting with Jev.

Writing a rule, and perch catching this README with it

Getting started

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>

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

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.

perch (lakeday-org/perch)

Searching Database…

353 ·GitHub
Perch
What is this?Perch is a command-line semantic code linter that scans a codebase for real issues using Decision Models, rather than plain syntax rules, and ranks what it finds worst-first.
Is this a CLI tool or does it work from inside my editor?It is primarily a CLI tool (perch issues, perch check), but it also installs 'agent skills' so coding assistants like Claude Code, Codex, Cursor and pi can use it directly.
How do I get it running?Create an API key at console.typesafe.ai, set it as the PERCHAPIKEY environment variable, then run perch issues to see your first scan results.
Do I need an API key before I can scan anything?Yes, perch calls a hosted service and requires a PERCHAPIKEY generated from console.typesafe.ai before it can run.
Is the ranking of issues a fixed rule check, or more of a judgment call?Scans work by walking a graph of questions and turning probabilities into a ranking, so results are closer to a weighted judgment than a deterministic rule match.
What is the difference between perch issues and perch check?perch issues lists all findings worst-first and lets you open one; perch check re-scans work in progress after a fix and records what it still finds.
What does .perch/closed.jsonl store?It records findings you dismissed along with the reasons you gave, and is meant to be committed alongside your rules.
Which coding agents can perch integrate with?perch setup installs instructions into .claude/, .codex/, .pi/, or .cursor/ folders, covering Claude Code, Codex, pi, and Cursor.
What are similar projects?openqodex, jevlint, knip, jev-code-reviewer, ast-grep, oc, GitNexus, react-doctor
Which topics is it in?tree-sitter, code-analysis, linter, devtools, code-quality, code-review, static-analysis, ci, cli-tool, cursor, command-line, agent-skills
Creator
lakeday-org
Size
40.4 MB
Stars
353
Updated
CommitOct 16Releasev0.4.3Oct 11
Age
1mo
Commits · 90 Days