Install PlanQ
PlanQ's shared npm command supports macOS arm64, Linux glibc x86_64, and Windows x86_64 starting with 0.1.4. Homebrew remains an optional native package-manager channel on macOS, and winget remains optional on Windows. The support matrix below is generated from the release that npm actually serves; the native channels report the version they were last verified against, which can trail the current release.
Support matrix
| Operating system | Target | npm status | Optional native channel |
|---|---|---|---|
| macOS | Apple Silicon (arm64) | 0.1.8 is available | Homebrew planq-cli/tap/planq is available at 0.1.6 |
| Windows | x86_64 | 0.1.8 is available | winget PlanQ.PlanQ is pending at 0.1.6 |
| Linux | glibc x86_64 | 0.1.8 is available | None |
macOS x86_64, Linux arm64, Linux musl/Alpine, and Windows arm64 are currently unsupported. Do not install a package built for a different platform.
npm
The npm wrapper requires Node.js 20 or newer. The installed PlanQ executable is native and does not require GraalVM, a JDK, or Clojure.
The same commands apply to all three supported targets:
npm install --global @planq-cli/planq
planq version
npx @planq-cli/planq versionUpgrade or uninstall:
npm update --global @planq-cli/planq
npm uninstall --global @planq-cli/planqThe wrapper installs exactly one matching optional dependency: @planq-cli/darwin-arm64, @planq-cli/linux-x64, or @planq-cli/win32-x64. Do not use --no-optional.
Start from the project template
After installing the CLI, clone the public PlanQ starter repository to open a complete project without a source checkout or frontend toolchain:
git clone https://github.com/planq-cli/plan-starter.git
cd plan-starter
planq project validate
planq devThe repository contains a small starter plan and two complete examples. The optional project Agent Skill remains an explicit install:
planq skill install
planq skill statusmacOS Apple Silicon
Install:
brew install planq-cli/tap/planq
planq versionUpgrade or uninstall:
brew upgrade planq
brew uninstall planqWindows x86_64
Install from the winget community source:
winget install --id PlanQ.PlanQ --exact
planq versionUpgrade or uninstall:
winget upgrade --id PlanQ.PlanQ --exact
winget uninstall --id PlanQ.PlanQ --exactCLI and project Skill lifecycle
Package managers install or remove the planq executable. They do not modify your repositories, .plan files, home directory, editor configuration, or shell profile.
The optional planq Agent Skill is project-scoped. Its complete canonical payload lives at .agents/skills/planq/; an older skills/plan-gantt path is reported as a conflict and must be reviewed and migrated manually. planq skill install also creates lightweight project discovery forwarders for Claude Code and TRAE. Upgrading or uninstalling the global CLI does not delete these repository files. See Agent Skill.
If you are using a coding agent, the workbench's handoff prompt will ask the agent to verify its environment by running planq version and planq skill status before changing a plan.
Depending on the output of planq skill status, your agent will handle the following states:
- Missing: The agent runs
planq skill installonce and checks both the canonical status and its matchingresult.integrationsentry again. - Conflict: The agent pauses and reports the relative conflict paths.
- Current: The agent still explicitly reads
.agents/skills/planq/SKILL.mdbefore changing a plan.
The Skill command has no global mode: do not create .codex/skills, a user-Home Skill, or use --global, --agent, or --force.
For more details on how agents interact with the CLI and project skills, see Agent Skill.
License and release integrity
PlanQ is distributed under PolyForm-Noncommercial-1.0.0. Each GitHub Release contains SHA256SUMS and planq-release-v1.json beside immutable platform archives. Package channels are the supported install path; source builds and direct archive downloads are not substitutes for package-channel acceptance.
Continue with the Quickstart. For platform or installation errors, use Troubleshooting.