Skip to content

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 systemTargetnpm statusOptional native channel
macOSApple Silicon (arm64)0.1.8 is availableHomebrew planq-cli/tap/planq is available at 0.1.6
Windowsx86_640.1.8 is availablewinget PlanQ.PlanQ is pending at 0.1.6
Linuxglibc x86_640.1.8 is availableNone

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:

bash
npm install --global @planq-cli/planq
planq version
npx @planq-cli/planq version

Upgrade or uninstall:

bash
npm update --global @planq-cli/planq
npm uninstall --global @planq-cli/planq

The 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:

bash
git clone https://github.com/planq-cli/plan-starter.git
cd plan-starter
planq project validate
planq dev

The repository contains a small starter plan and two complete examples. The optional project Agent Skill remains an explicit install:

bash
planq skill install
planq skill status

macOS Apple Silicon ​

Install:

bash
brew install planq-cli/tap/planq
planq version

Upgrade or uninstall:

bash
brew upgrade planq
brew uninstall planq

Windows x86_64 ​

Install from the winget community source:

powershell
winget install --id PlanQ.PlanQ --exact
planq version

Upgrade or uninstall:

powershell
winget upgrade --id PlanQ.PlanQ --exact
winget uninstall --id PlanQ.PlanQ --exact

CLI 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 install once and checks both the canonical status and its matching result.integrations entry again.
  • Conflict: The agent pauses and reports the relative conflict paths.
  • Current: The agent still explicitly reads .agents/skills/planq/SKILL.md before 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.

PlanQ documentation