What you need

  • A Drupal site managed with Composer.
  • PHP 8.3 or newer with pdo_sqlite, where droost will run (inside the container on DDEV).
  • Claude Code for the full experience. Other agents work too, without the guard.
  • Node, for the browser tests.

This page installs the droost command (the brain and the workflow). For the module, which lets the agent ask the live site about itself, see The module: two commands, and the command's droost init then installs the module's skill too.

1. Install droost in its own folder

bash
mkdir -p tools/droost
composer init -d tools/droost -n --name=local/droost-tools
composer config -d tools/droost platform.php 8.3.0
composer require -d tools/droost 'droost/workflow:^1.0'

droost gets its own Composer project, so it never loads Drupal and never clashes with the site's packages. Set platform.php to the PHP the site runs, not your laptop's. Add tools/droost/vendor/ to .gitignore.

2. Install it into the project

bash
tools/droost/vendor/bin/droost init

This writes droost/droost.yml (your settings), AGENTS.md and CLAUDE.md (how every agent uses droost from now on), and the .claude/ skills and hooks. Running it again later refreshes droost's own files and never touches your droost/droost.yml.

3. Build the map of your code

bash
tools/droost/vendor/bin/droost code:index

This is the Droost Brain: an index of your modules, custom code and docs, read from your files. Run it again after a big change or an upgrade.

4. Check it

bash
tools/droost/vendor/bin/droost doctor
tools/droost/vendor/bin/droost brief

5. Pick the level

bash
tools/droost/vendor/bin/droost workflow:effort high

Run it in your own terminal; it refuses to run from the agent. It changes the preset: line only, and the file init wrote spells out some settings that beat the level, such as enforcement: soft. Settings says which lines to delete so the level decides them.

6. Install the tools the checks use

bash
composer require --dev drupal/core-dev     # phpcs with the Drupal standard, phpstan, phpunit
npm i -D @playwright/test                  # browser tests
npx playwright install chromium

phpunit also needs a phpunit.xml or phpunit.xml.dist at the project root.

7. Commit, and start a new session

bash
git add tools/droost/composer.json tools/droost/composer.lock droost/ AGENTS.md CLAUDE.md .claude/ .gitignore
git commit -m "Add droost"

Start a new Claude Code session in the project so it loads the hooks. Then add the Claude Code plugin if you want the run panel.

On DDEV

Run Composer and droost in the DDEV container so dependency resolution uses the project's PHP environment. Prefix the installation commands above with ddev composer in place of composer. Add the ddev droost command (one small file in .ddev/commands/web/), then:

bash
ddev droost init
ddev droost code:index

If your DDEV setup uses Mutagen and you change files on the host, run ddev mutagen sync before the next droost command.

On a site that already has code

Before the first run, record the old code's problems in a baseline, so runs are judged only on what they add. On an existing site walks through it.

Upgrading

bash
composer update -d tools/droost droost/workflow
tools/droost/vendor/bin/droost init
tools/droost/vendor/bin/droost code:index

Do it between runs, not during one.

Removing it

bash
tools/droost/vendor/bin/droost workflow:uninstall

takes out what init installed: the .claude/ skills, the guard's hooks and droost's blocks in AGENTS.md. Then delete tools/droost/ and, if you do not want to keep your settings and notes, droost/. Your site's database is untouched: the command never writes to it.