# perch

Adopt this skill: https://proskills.md/skills/other/lakeday-org-perch

Page: https://proskills.md/skills/other/lakeday-org-perch
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: README.md
upstream: https://github.com/lakeday-org/perch/blob/HEAD/README.md

````text
<p align="center">
  <a href="https://perchscan.com">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset=".github/logo.svg">
      <img alt="perch" src=".github/logo-light.svg" width="300">
    </picture>
  </a>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@lakeday/perch"><img alt="npm" src="https://img.shields.io/npm/v/@lakeday/perch"></a>
  <a href="https://github.com/lakeday-org/perch/actions/workflows/ci.yml"><img alt="ci" src="https://github.com/lakeday-org/perch/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://nodejs.org"><img alt="node" src="https://img.shields.io/node/v/@lakeday/perch"></a>
  <a href="LICENSE"><img alt="license" src="https://img.shields.io/npm/l/@lakeday/perch"></a>
  <a href="https://perchscan.com"><img alt="perch" src="https://img.shields.io/badge/perch-lint%20%E2%9C%93%20%C2%B7%20docs%20%E2%9C%93%20%C2%B7%20security%20%E2%9C%93-ffb454?labelColor=1a1d26&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjIgLTIyNiAyNTAgMTYwIiByb2xlPSJpbWciIGFyaWEtbGFiZWw9InBlcmNoIj4gPGRlZnM+IDxsaW5lYXJHcmFkaWVudCBpZD0iYiIgeDE9IjAuMiIgeTE9IjAiIHgyPSIwLjU1IiB5Mj0iMSI+IDxzdG9wIG9mZnNldD0iMCUiIHN0b3AtY29sb3I9IiNmZmRmOWEiLz4gPHN0b3Agb2Zmc2V0PSI0NSUiIHN0b3AtY29sb3I9IiNmY2I5NWEiLz4gPHN0b3Agb2Zmc2V0PSIxMDAlIiBzdG9wLWNvbG9yPSIjZDI4MTFjIi8+IDwvbGluZWFyR3JhZGllbnQ+IDxsaW5lYXJHcmFkaWVudCBpZD0iYlNwaW5lIiB4MT0iMCIgeTE9IjAiIHgyPSIwIiB5Mj0iMSI+IDxzdG9wIG9mZnNldD0iMCUiIHN0b3AtY29sb3I9IiNmZmVhYmEiLz4gPHN0b3Agb2Zmc2V0PSIxMDAlIiBzdG9wLWNvbG9yPSIjZTc5YTJjIi8+IDwvbGluZWFyR3JhZGllbnQ+IDwvZGVmcz4gPGc+IDxwYXRoIGQ9Ik04IC03NCBMMTMuMyAtMTA1LjYgUTIyLjMgLTEyNS4zIDMxLjMgLTE2My4zIFE0Mi41IC0xNjMuMyA1My43IC0xOTQuOSBRNjUuOSAtMTgxLjUgNzguMSAtMjA2LjEgUTkwLjkgLTE4NC42IDEwMy44IC0yMDIuMyBRMTE3LjQgLTE3OC4zIDEzMC45IC0xOTEuMiBRMTQ0LjkgLTE2Ni40IDE1OC45IC0xNzQuNCBRMTczLjYgLTE1MSAxODguMiAtMTU0LjkgUTIwMy4zIC0xMzIuNCAyMTguNCAtMTMwLjcgUTIzMy44IC0xMDkuMSAyNDkuMiAtMTAwIEwyMzMgLTc0IFoiIGZpbGw9InVybCgjYikiIGZpbGwtb3BhY2l0eT0iMC43MiIvPiA8cGF0aCBkPSJNOCAtNzQgTDEzLjMgLTEwNS42IFEyMi4zIC0xMjUuMyAzMS4zIC0xNjMuMyBRNDIuNSAtMTYzLjMgNTMuNyAtMTk0LjkgUTY1LjkgLTE4MS41IDc4LjEgLTIwNi4xIFE5MC45IC0xODQuNiAxMDMuOCAtMjAyLjMgUTExNy40IC0xNzguMyAxMzAuOSAtMTkxLjIgUTE0NC45IC0xNjYuNCAxNTguOSAtMTc0LjQgUTE3My42IC0xNTEgMTg4LjIgLTE1NC45IFEyMDMuMyAtMTMyLjQgMjE4LjQgLTEzMC43IFEyMzMuOCAtMTA5LjEgMjQ5LjIgLTEwMCBMMjMzIC03NCBaIiBmaWxsPSJub25lIiBzdHJva2U9IiNlMDk0MmIiIHN0cm9rZS13aWR0aD0iMi4yIiBzdHJva2UtbGluZWpvaW49InJvdW5kIi8+IDxwYXRoIGQ9Ik00LjYgLTc0IEwxMy43IC0xMDggTDExLjQgLTc0IFogTTE3LjUgLTc0IEwzMiAtMTcwIEwyNy4zIC03NCBaIE0zNi42IC03NCBMNTQuNyAtMjA0IEw0OCAtNzQgWiBNNTkgLTc0IEw3OS4xIC0yMTYgTDcxIC03NCBaIE04My43IC03NCBMMTA0LjkgLTIxMiBMOTUuNSAtNzQgWiBNMTEwLjMgLTc0IEwxMzIgLTIwMCBMMTIxLjUgLTc0IFogTTEzOC4zIC03NCBMMTYwLjIgLTE4MiBMMTQ4LjcgLTc0IFogTTE2Ny42IC03NCBMMTg5LjUgLTE2MSBMMTc3IC03NCBaIE0xOTguMSAtNzQgTDIxOS42IC0xMzUgTDIwNi4zIC03NCBaIE0yMjkuNyAtNzQgTDI1MC40IC0xMDIgTDIzNi4zIC03NCBaIiBmaWxsPSJ1cmwoI2JTcGluZSkiLz4gPC9nPiA8L3N2Zz4="></a>
</p>

<p align="center">
  <a href="https://perchscan.com">perchscan.com</a> &nbsp;&middot;&nbsp;
  <a href="https://docs.perchscan.com">docs</a> &nbsp;&middot;&nbsp;
  <a href=".benchmarks">benchmarks</a> &nbsp;&middot;&nbsp;
  <a href="https://discord.gg/znTcuKRK">Discord</a>
</p>

Semantic code and security scanner.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset=".github/greptile-dark.svg">
  <img alt="Known bugs caught on the Greptile benchmark and the cost of a pull request: Greptile 82% at about $1, perch on OpenAI Decisions 76% at $0.007, Cursor Bugbot 58% at about $1.50, GitHub Copilot 54%, CodeRabbit 44% at $1–3, perch on Jev 44% at $0.003, Graphite 6% at about $2" src=".github/greptile-light.svg" width="880">
</picture>

## Getting started

```sh
npm install -g @lakeday/perch
perch login
perch scan
```

`perch login` signs you in to [Perch Cloud](https://perchscan.com), where 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.

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

## Agent skills

```sh
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

You can extend perch with your own linting rules by adding them to `perch.yaml`:

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

## ReviewBench

<picture>
  <source media="(prefers-color-scheme: dark)" srcset=".github/reviewbench-dark.svg">
  <img alt="Recall on ReviewBench and the cost of a pull request: Laude RevEngine Prime 46.3%, perch on OpenAI Decisions 40.0% at $0.024, then the leaderboard's other reviewers down to Cursor at 9.6%, and perch on Jev 7.9% at $0.011" src=".github/reviewbench-light.svg" width="880">
</picture>

[ReviewBench](https://review-bench.ai) is GitHub's benchmark for AI code review. Perch is credited when it flags the method holding
a labelled bug; the leaderboard credits a review comment that a judge model matches to one. The runs, the answers and how to
reproduce them are linked from [`.benchmarks/reviewbench`](.benchmarks/reviewbench).

<details>
<summary>The numbers</summary>

| Reviewer | Recall |
| --- | ---: |
| Laude RevEngine Prime | 46.3% |
| **Perch · OpenAI Decisions, $0.024 a pull request** | **40.0%** |
| block/review | 32.6% |
| Klaussy | 29.8% |
| Copilot code review | 26.0% |
| DeepSeek Harness Reviewer | 25.6% |
| Devin AI | 23.8% |
| Qodo | 22.1% |
| Codex | 18.5% |
| Cubic | 16.3% |
| Greptile | 16.2% |
| Cursor | 9.6% |
| **Perch · Jev, $0.011 a pull request** | **7.9%** |

</details>

## Greptile benchmark

[Greptile's benchmark](https://www.greptile.com/benchmarks) runs code reviewers on 50 pull requests, each with one known bug.
The runs and their labels are linked from [`.benchmarks/greptile`](.benchmarks/greptile).

Perch is credited when it flags the function holding the known bug. The published tools were credited for a line comment
identifying it.

## Models

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:

```sh
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
```

| Model | `PERCH_BASE_URL` | `PERCH_MODEL_ID` |
| --- | --- | --- |
| [Jev](https://docs.typesafe.ai/models) | `https://api.typesafe.ai/v1/systemone` | `jev-latest` |
| [Liquid AI d1](https://docs.liquid.ai/lfm/models/decision-models) | `https://api.liquid.ai/decisions/v1/systemone` | `d1:free` |
| [OpenAI gpt-6-luna](https://developers.openai.com/api/docs/guides/decisions) | `https://api.openai.com/v1/decisions` | `gpt-6-luna` |
| [DiffusionGemma Jev](https://github.com/razorback16/openjev) on Beam | `https://app.beam.cloud/v1/models/jev/diffusiongemma/invoke` | `jev/diffusiongemma` |
| [SemiF](https://github.com/TheoLeeCJ/SemIf) on Beam | `https://app.beam.cloud/v1/models/jev/semif/invoke` | `jev/semif` |

Any endpoint that supports the
````
