Panda Suite Docs
v1.9.2GitHub ↗
Panda Suite / Installation

Install Panda Suite

Use one method to avoid duplicate skill names. Check out the versioned release:

git clone --branch v1.9.2 https://github.com/refactorroom/panda-suite.git
cd panda-suite

Run the commands below from that checkout. All source files are included; no recursive checkout or bootstrap is needed. This command installs from source.

License status: original Suite files use MIT; Buddhist Method retains its MIT license. The pinned Panda Debugger revision has no LICENSE file. Its owner authorized redistribution in the Panda Suite npm package; the Suite license does not cover it. See source notices.

Claude Code

From this repository, load without installing:

claude --plugin-dir "$PWD"

Then use /panda-suite:panda-lead or a specialist such as /panda-suite:panda-review.

For persistent local marketplace installation:

claude plugin marketplace add "$PWD"
claude plugin install panda-suite@panda-suite

The local plugin and marketplace manifests were validated with Claude Code 2.1.251, and its component inventory discovers all 22 skills. Persistent installation and interactive model invocation were not exercised.

OpenAI Codex

For local plugin installation:

codex plugin marketplace add "$PWD"
codex plugin add panda-suite@panda-suite

Use the installed skill selector. Codex 0.159.2's plugin inventory exposes panda-suite:panda-lead and panda-suite:panda-review; select those names, or reference $panda-suite:panda-lead in your request.

The portable root manifest and all 21 plugin skill paths were read by the actual Codex app-server. Standalone discovery below was also tested. Persistent plugin installation and interactive invocation were not exercised, and no global user configuration was changed during validation.

npm CLI for standalone skills

The npm CLI requires Node.js 20 or newer. Install selected skills and later update the managed copies with:

npx panda-suite@latest install --skill panda-plan --skill panda-execute
npx panda-suite@latest update

Use --all instead of the --skill options to install all bundled skills. The default destination is ~/.agents/skills; append --destination /path/to/skills to both commands to manage a different host or project directory. Restart or refresh the host after changes. @latest requests the latest published CLI; the skill contents come from that package version. In an interactive terminal, an older CLI checks for a newer npm release and asks whether to run the requested command with that version. Declining, offline use, and non-interactive runs continue with the current version; set PANDA_SUITE_SKIP_UPDATE_CHECK=1 to skip the check.

The CLI records managed files in .panda-suite-state.json in the destination. It refuses existing directories and stops the entire update if managed files were changed, added, deleted, or replaced by symlinks. Restore the original managed files from a backup before retrying. To migrate a Python-installed skill, first back up and remove its existing directory, then install it through the CLI. Keep unrelated skills and the state file intact. Plugin installations use their own update commands below.

If a process is interrupted, preserve a copy of the whole destination before recovery. Check that no CLI process is running. The .panda-suite-transaction directory contains manifest.json, any original state.before, staged files, and original directories under backup. Inspect those alongside the current files: restore the original directories from backup, remove any new directories created by the interrupted install, and restore state.before (or remove the state file if hadState is false). If a backup is absent, retain the original current directory; do not discard changes you cannot identify. Once the files and state are consistent, remove .panda-suite-transaction and the stale .panda-suite-lock directory, then retry. A lock without a transaction can be removed after confirming no process is running. If rollback reports an error, keep the transaction and recover from its backups before retrying.

For maintainers: branch from dev and open feature PRs back into dev, the integration branch. Promote dev to main through a PR and keep the merge commit. main is the default production branch and the source for releases.

Align package.json, plugin.json, and .claude-plugin/plugin.json versions and run the tests. Use a fresh checkout of the release commit for npm pack --dry-run and npm pack. This keeps local test artifacts out of the tarball. Smoke-test the tarball before publishing it manually. Verify package name ownership and all bundled redistribution rights in SOURCE_NOTICES.md. GitHub Actions runs source tests on Linux and deploys the documentation from dev.

Standalone skills and compatible hosts

The copy utility uses Python 3.10+ and the standard library. Choose your host's documented discovery directory. For a Codex project:

python3 scripts/install-skills.py --destination /path/to/project/.agents/skills --all

For selected user-level Codex skills:

python3 scripts/install-skills.py --destination "$HOME/.agents/skills" --skill panda-lead --skill panda-plan --skill panda-execute

For a standalone Claude Code specialist:

python3 scripts/install-skills.py --destination "$HOME/.claude/skills" --skill panda-spec

The installer copies complete directories and refuses existing names, including late directory collisions. It does not overwrite a previous installation. Review and back up an old copy before replacing it. An I/O error during copying can leave a partial newly created directory; inspect it before retrying. Restart or refresh the host if a new skill does not appear.

Standalone Codex invocation uses $panda-lead, $panda-plan, or $panda-spec; standalone Claude Code uses /panda-lead, /panda-plan, or /panda-spec. Other Agent Skills hosts need their own documented discovery/instruction-loading mechanism. Format validation alone does not prove those runtimes are compatible.

Update an existing installation

For a Git-backed Codex marketplace, refresh its snapshot and install the current plugin version:

codex plugin marketplace upgrade panda-suite
codex plugin add panda-suite@panda-suite

For a Git-backed Claude Code marketplace, update the marketplace and plugin:

claude plugin marketplace update panda-suite
claude plugin update panda-suite@panda-suite

For a marketplace configured from a local checkout, first update that checkout to the desired release, then run the relevant plugin command above. If you use claude --plugin-dir, restart Claude Code from the updated checkout. Restart the host after updating a plugin so it loads the new skills.

For standalone skills in Codex, Claude Code, or another compatible host, update the checkout first. The installer refuses existing skill directories. For each skill you want to refresh, move its existing directory to a safe backup location, then reinstall it from the checkout. For example, to refresh the user-level Codex panda-plan skill:

mkdir -p "$HOME/panda-skill-backups"
mv -i "$HOME/.agents/skills/panda-plan" "$HOME/panda-skill-backups/panda-plan"
python3 scripts/install-skills.py --destination "$HOME/.agents/skills" --skill panda-plan

Run the installer from the updated checkout. Choose an unused backup name if one already exists, and use your host's documented skills directory for other hosts. Repeat for each installed skill you want to update, then restart or refresh the host.