Installation

Clawa is a Pi package loaded from a git checkout. It is not a standalone agent runtime and it is not published to npm yet. Keep the package checkout separate from the folder that will become the Clawa’s home.

What you need

• Git.
• Node.js 24.15 or newer, but lower than 27.
• Pi 0.99.2 or newer, with a configured model provider.
• A clean folder for the home. First run explains the exact bootstrap boundary.

Pi extensions execute with your user permissions. Read the trust boundaries before putting personal context into a home.

Install legacy

Legacy 0.3.1, released on 2026-10-01, keeps the earlier Clawa architecture on the current Pi baseline. Choose where package checkouts live, then clone the release tag:

mkdir -p ~/src
git clone --branch v0.3.1 \
  https://github.com/IgorWarzocha/pi-clawa.git ~/src/pi-clawa

This leaves the checkout detached at the release commit. To follow maintenance between releases, replace v0.3.1 with legacy in the clone command.

Create a separate home:

mkdir -p ~/clawa-home
cd ~/clawa-home

You can try it directly:

pi -e ~/src/pi-clawa

For a permanent project-local install, run the helper from the home:

~/src/pi-clawa/scripts/install-project.sh
pi

The helper writes .pi/settings.json with the package checkout in packages. It refuses to replace an existing settings file. If the home already has Pi settings, merge this entry yourself instead:

{
  "packages": ["/home/you/src/pi-clawa"]
}

Do not use CLAWA_INSTALL_OVERWRITE=1 casually. It replaces the complete settings file, not only the package list.

Branches and releases

Install v0.3.1 to retain legacy. Modern v0.4.0 is the default for new homes and has a different architecture; it is not required to keep legacy working with current Pi. Both releases require Pi 0.99.2 or newer. The historical v0.3.0 tag stays unchanged. The release policy explains both lines, and the edition comparison helps you choose between them.

The files and runtime state page separates home data from disposable runtime artifacts and lists what belongs in a backup or ignore policy.

Next

Start Pi in the home and continue to First run. Clawa creates its own files; there is no separate init or setup wizard.