Install paqad-ai: Node.js 22, npm and npx

What you need first

Node.js 22 or later. The package declares "node": ">=22.0.0". Check your version with node --version. npm may still install on an older Node.js with a warning, but that setup is not supported.
npm, which comes with Node.js. Paqad's own instructions and its automatic updater both use npm.
At least one supported AI coding tool, such as Claude Code, Codex CLI, Gemini CLI, Cursor or GitHub Copilot. The full list is in the adapters overview.
git is recommended. Onboarding installs small git hooks when the project is a git repository and skips that step when it is not.

Install the command once for your machine

Install paqad-ai globally so the command works in every project:

npm install -g paqad-ai

This only puts the command on your machine. It does not change any project. During install a small script restores the "executable" permission on the hook scripts that ship inside the package, because the publishing tool strips it.

Check that it worked

paqad-ai --version

The command prints the installed version number, for example 1.91.1. If your shell says the command is not found, the global npm folder is not on your PATH; fix that in your shell settings and open a new terminal.

Try it without installing: npx

You can run onboarding once without a global install:

cd your-project
npx paqad-ai onboard

With npx, the link Paqad creates at ~/.paqad-ai/current points into npm's temporary download cache. npm can clear that cache later, and then the hooks and instructions that follow the link stop working until you onboard again. Use npx to try Paqad, and a global install for everyday work.

What Paqad writes outside your project

The global install itself writes only into npm's global folder. The first time you run paqad-ai onboard (or paqad-ai join) it also writes to your home folder:

~/.paqad-ai/current: a link to the installed framework files. Every project's .paqad/framework-path.txt refers to this path, so all projects on the machine use the same installed version. You can move it by setting the PAQAD_FRAMEWORK_HOME environment variable.
~/.claude/agents/ and ~/.codex/agents/: six helper agent definitions (one per workflow stage) used by Claude Code and Codex CLI when Paqad runs a stage in a separate agent.

Everything else Paqad writes goes inside the project you onboard. The Quick start lists those files.

Keeping Paqad up to date

There are two parts to an update: the command on your machine, and the framework-managed files inside each project.

Automatic (default). On Claude Code and Codex CLI, a hook runs when a session starts. At most every 12 hours it checks for a newer version and, if there is one, runs npm install -g paqad-ai@latest followed by paqad-ai update --silent in the background. Turn this off by setting auto_update=false in .paqad/configs/.config.app (for the team) or .paqad/.config (for you only).
By hand. Update the command, then refresh the managed files in each project:

npm install -g paqad-ai@latest
cd your-project
paqad-ai update

paqad-ai update regenerates the files Paqad manages and leaves files your project owns, such as the copied rules, alone. It prints a JSON report of what it regenerated and what it skipped. Review the changes with git status and git diff before you commit. Keeping Paqad's files current explains what update does and does not refresh, and the refresh and update reference lists its options.

To require at least a specific version on every machine, set minimum_version (default latest, meaning no fixed floor) in the same settings files.

Next step

Go to your project folder and follow the Quick start.

Install Paqad