# Perch — semantic code linting with Jev

> Perch is an open-source semantic linter powered by TypeSafe Jev. It checks code for defects, security issues, and project rules written in plain English.

Perch is a product of Verglas LLC. The CLI is published as `@lakeday/perch` on npm, with source code under the MIT license at [lakeday-org/perch](https://github.com/lakeday-org/perch).

## Scans

`perch scan` checks defects and security by default, along with configured lint rules. Documentation and refactoring checks are opt-in. Perch parses the repository with tree-sitter and includes relevant callers and callees when checking a method.

Use Perch to catch regressions in agent edits, check endpoint authorization, enforce business requirements, or review documentation and code comments. Run it alongside unit tests, type checks, and conventional linters.

## Install

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

Follow the [quick start](https://docs.perchscan.com/install/) to configure the CLI and run a scan.

## Project rules

Save requirements in `perch.yaml`. A rule can check a file, method, or test. The `where` field selects files; `ensure` states the requirement.

```yaml
- name: discount-limit
  each: method
  where: cart.py
  ensure: Discounts can be no larger than 20%.
```

`perch scan --filter rule=discount-limit` runs that rule across the repository. `perch check cart.py::apply_discount --rules discount-limit` checks the method from disk during an edit. See [writing rules](https://docs.perchscan.com/rules/) for the full configuration.

## Coding agents

Install the Perch skill with `perch setup claude-code`, `perch setup codex`, or `perch setup cursor`. The skill teaches the agent to turn a requirement into a rule and check its changes. [Agent setup](https://docs.perchscan.com/skill/) covers each tool.

## CI

`perch scan --since origin/main` limits a scan to files changed from the base branch, with surrounding code for context. Fetch the base branch in CI. A gated finding exits `3`; configuration or runtime failures use `1` or `2`. Add the scan beside tests and require the job before merging. The [GitHub Actions guide](https://docs.perchscan.com/ci/) includes a complete workflow.

## Results and source code

New model judgments are probabilistic. Perch reuses cached results for unchanged requests; a fresh request can produce a different judgment. A passing scan does not prove the code is correct or secure. Keep executable regression tests for behavior you can test directly.

Scans send relevant source code to TypeSafe for analysis. Findings are saved locally in `.perch`. [Scan details](https://docs.perchscan.com/scan/) explain scope, scoring, and results.

## Documentation

- [Introduction](https://docs.perchscan.com/index.md): Semantic code linting with Jev.
- [Quick start](https://docs.perchscan.com/install.md): Install perch, set the key, and run the first scan.
- [Scanning your code](https://docs.perchscan.com/scanning.md): Scan a repository, a directory, a file, or what a branch changed.
- [Reading issues](https://docs.perchscan.com/issues.md): The ranked list, what a row means, and how to narrow it.
- [Semantic linting](https://docs.perchscan.com/rules.md): Custom linting rules in perch.yaml, asked in the same reading as perch's own questions.
- [Checking a change](https://docs.perchscan.com/check.md): perch check asks about one point in the code as it reads on disk. It records nothing and exits 3 while something is wrong.
- [perch in CI](https://docs.perchscan.com/ci.md): Scan every pull request with GitHub Actions or GitLab CI.
- [Coding assistants](https://docs.perchscan.com/skill.md): perch setup installs a skill that teaches Claude Code, Codex, pi or Cursor how to scan a branch, read the JSON, and write a rule.
- [Command reference](https://docs.perchscan.com/cli.md): Every verb, every flag, and which ones need a key.
- [Inside a scan](https://docs.perchscan.com/scan.md): The graph walk, the questions, and how probabilities turn into a ranking.

## More from Perch

- [Articles, examples, and case studies](https://perchscan.com/llms.txt): Published guides and project walkthroughs.
- [Complete documentation](https://docs.perchscan.com/llms-full.txt): All documentation pages in one file.