psalm: seven executables at the root of a short README

Six executables sit at the root and the page names none of them

The repository root carries seven bare executable names: `psalm`, `psalter`, `psalm-refactor`, `psalm-review`, `psalm-plugin`, `psalm-plugin-api` and `psalm-language-server`. A `bin/` directory sits in the same listing. So the tree contains one directory that conventionally holds command line entry points and seven files that are themselves entry points, and nothing on the landing page says which of the eight you run, or what six of them do.

One of those names is also the repository's own name, which makes the collision easy to miss. After installing the package, the thing you type and the thing you cloned are spelled the same way, and the README never spells either.

The variation among the seven is the interesting part. Two share the root name and add a verb, `psalm-refactor` and `psalm-review`, which implies a mode and a gate rather than a single analyser. One, `psalter`, drops the prefix entirely. One, `psalm-language-server`, is named for a protocol that editors speak, and one, `psalm-plugin`, is named for the extension point. The tree tells you the project's shape more precisely than the README's prose does, and it does so by accident.

The documentation link points at master while the default branch is 6.x

The default branch of this repository is `6.x`. The documentation link on the README goes to the `docs` folder on a branch named `master`:

`https://github.com/vimeo/psalm/blob/master/docs`

Those two names do not agree, so a reader who follows the page's own documentation link is reading a folder on a branch that is not the one the repository treats as its front door. The page also says the documentation on psalm.dev is generated from that same `docs` folder, which means the published site and the branch a reader is sent to are stated to be the same source, while the link that points at it names a different branch than the one marked as default.

The release list makes the version picture concrete. Psalm 7 (7.0.0) was published on 2026-11-02, a few hours after 7.0.0-rc28, and 6.20.7 followed on 2026-11-03. The most recent push is dated 2026-11-02. With 7.0.0 out while the default branch keeps a 6.x name and 6.x patch releases continue, two lines are live at once, and nothing on the page says which branch a new user should track.

A config schema, a committed baseline, and no configuration section at all

The root of this repository is where the configuration surface lives. `psalm.xml.dist` is the distributed default config, `config.xsd` is an XML schema, and `psalm-baseline.xml` is a baseline file sitting in the root of the project itself. The baseline is the interesting one: a baseline is the list of issues a project has agreed to tolerate, checked in so that a clean run stays clean, and a tool that ships one in its own repository is being run against its own rules.

Alongside those sit `dictionaries/` and `stubs/`, which are where custom type information about third party functions lives, and two configuration files for other tools entirely: `phpcs.xml` for code style and `phpunit.xml.dist` for the test suite.

None of this appears in the README. There is no configuration section, no mention of a baseline, no mention of the schema, no list of what can be configured and no sample config. The page's entire contribution to setup is one sentence pointing at `docs/running_psalm/installation.md`.

Packaging, scoping and a signing key all live in version control

Four files in the root describe how this project is built and shipped rather than how it is used. `scoper.inc.php` is the configuration for scoping the tool's dependencies, which is the step that lets a PHP project bundle its libraries under rewritten namespaces so two copies can coexist in one process. `box.json.dist` is the configuration for building the project into a single distributable archive.

Then there is `keys.asc.gpg`, a key file committed to the tree.

Alongside that, `composer.json` is the package manifest and `vendor-bin/` isolates the tools used to build the project, a common arrangement for keeping development dependencies out of the dependency graph of the thing you install. None of these files is mentioned in the README, and neither is the release process, though `UPGRADING.md` sits in the same listing for anyone who needs to know what changed between major versions.

One active maintainer, and support is arranged through a personal site

The README names its people precisely. Matt Brown built it. Daniil Gentili and Alies Lapatsin are listed as maintainers, and Daniil Gentili is described as the only active maintainer of Psalm. Two others are listed as former maintainers, and Vimeo's engineering team is credited with encouragement by name, in a sentence that reads the engineering team at Vimeo have provided a lot encouragement, missing the preposition.

The single sentence about support is the one that carries a business model:

You can support Psalm development by requesting a support contract from Daniil Gentili, the only active maintainer of Psalm.

The contracts are described as covering three things, full integration of Psalm into existing codebases, support for Psalm issues, and development of additional Psalm features. Pricing and contact details are not on the page; they sit behind a link to a personal domain. So the arrangement is that the project's one active maintainer sells integration work and feature development on the tool, which is a coherent way to fund a solo-maintained analyser and also means the roadmap and the support queue are the same person.

Community conversation is pointed at two Telegram channels, one for news and one for the community, and a Discord server.

Two continuous integration systems are configured, one of them for Windows

The root carries `.appveyor.yml` and a `.circleci/` directory. AppVeyor is a Windows oriented continuous integration service, and CircleCI is the other one, so the project is wired to run on both rather than having settled on a single provider. There is also a `.github/` directory, which is where the workflow definitions live for anyone who wants to read what actually gates a merge.

Alongside the CI definitions sit the files that describe how the project is edited and tested: `.editorconfig` for whitespace, `.gitattributes` for line endings, `phpunit.xml.dist` for the test suite, and a `tests/` directory. `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md` are both present, and the README defers to the contributing guide rather than duplicating it, which is more than most projects of this size manage.

The shipped examples are plugin templates, and the summary loses security

The `examples/` directory holds three entries: `TemplateChecker.php`, `TemplateScanner.php` and a `plugins/` folder. That is the whole of it, and the names describe the extension API rather than any end to end example, a checker and a scanner being the two things a plugin contributes. It fits the `psalm-plugin` executable and the `dictionaries/` directory, both of which exist to let a project describe functions the analyser cannot see.

The mismatch worth flagging is in the project's own summary. The repository description calls it a static analysis tool for finding errors and security vulnerabilities in PHP applications. The README's own one line summary calls it a static analysis tool for finding errors in PHP applications. Security vulnerabilities are absent from the page's own description of itself, and there is no section on the README that introduces them, so the more alarming claim lives only in the metadata line under the repository name.

For a tool people install precisely to catch security problems, that is a backwards split between what the badge-level promise says and what the project explains.

Editorial conclusion

Psalm is the right tool if you want static analysis of PHP with a config file you validate against a schema and a baseline you can commit, and the wrong tool to evaluate from its landing page. Before adopting a version, check which branch you are on, since the default branch is 6.x while 7.0.0 has already been released, and note that the documentation link on the README points at a different branch name. Before writing custom checks, read the config schema and the baseline that ship in the root, because the README explains neither. And budget for the maintenance picture the page states plainly: one active maintainer, with paid support arranged through that person's own site.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. vimeo/psalm on GitHub