PlanQ for Visual Studio Code
PlanQ brings Plan as Code authoring to .plan files:
- TextMate syntax highlighting
- diagnostics, completion, hover, definitions, references, and rename
- deterministic document formatting
- a read-only Gantt preview beside the editor
PlanQ owns parsing, validation, reference resolution, and formatting. The
extension starts the installed planq lsp process and does not reimplement
those rules in TypeScript.
Install
Install PlanQ by planq-cli from the
Visual Studio Marketplace.
The latest accepted Marketplace version is 0.1.7:
code --install-extension planq-cli.planq@0.1.7
For offline installation or recovery, use the byte-identical accepted GitHub
Release VSIX. Both channels provide version 0.1.7.
Download planq-0.1.7.vsix from the
PlanQ 0.1.7 GitHub Release,
then install the versioned file:
code --install-extension planq-0.1.7.vsix
The extension ID is planq-cli.planq. The extension requires VS Code 1.90.0
or later.
Install the PlanQ CLI
The extension does not download the PlanQ executable. Install the current
stable CLI from the PlanQ installation guide,
then verify it in the environment used to launch VS Code:
planq version
By default the extension starts planq lsp. If a GUI-launched VS Code cannot
find the executable, set the machine-scoped Plan: Server Path setting to
the executable's absolute path:
{
"plan.server.path": "/absolute/path/to/planq"
}
The setting is intentionally machine-scoped. Do not commit a developer-specific
path to workspace settings.
Open any .plan file to activate the extension. Format Document uses the
same deterministic formatter as planq format. Formatting on save is enabled
by default for the Plan language.
To turn it off, add a Plan language-specific setting at user or workspace scope:
{
"[plan]": {
"editor.formatOnSave": false
}
}
VS Code gives language-specific defaults higher precedence than ordinary global
or workspace settings. A non-language-specific "editor.formatOnSave": false
does not disable the Plan default; use the [plan] block above.
Date completion appears after valid :start, :end, :date, and :deadline
fields. Completion inserts absolute YYYY-MM-DD values. Language features and
diagnostics come from planq lsp; syntax highlighting alone does not imply
that a plan is semantically valid.
Open the Gantt preview
Run Plan: Open Preview to Side from a saved local .plan file. The
extension starts:
planq dev <absolute-file> --no-open --local
and embeds the workbench bundled with that CLI. The preview reads the last saved
version, reuses one panel per file, and refreshes after entry or include files
are saved. Use Plan: Restart Preview to restart that file's local bridge.
Click a task bar or work-item row to reveal and briefly highlight its source in
the original editor group, without moving focus away from the preview. Included
items open their defining file; an included-plan container reveals its include
statement. Unsaved or out-of-date source locations are skipped: save changes and
wait for the preview to update before retrying. Older CLI workbenches still render
normally but do not provide click-to-source navigation.
The preview does not require the PlanQ site or product login. --local
overrides any inherited PLAN_SITE; the VSIX does not contain another UI
bundle. Install the CLI and extension together.
Use Plan: Manage in PlanQ in the preview title to open Workspace and GitHub
management in your external browser. It does not upload this preview or send
local paths or tokens. Your .plan files are already saved locally; commit and
push the project, then explicitly connect GitHub. The site stores synchronized
results and management state.
Desktop localhost preview is supported. Automatic port mapping for Remote SSH,
Dev Containers, and Codespaces is not currently supported, and the extension
rejects those preview sessions before starting a process. LSP editing features
remain available when the configured planq executable is reachable.
Commands
- Plan: Restart Language Server
- Plan: Show Language Server Output
- Plan: Open Preview to Side
- Plan: Restart Preview
- Plan: Manage in PlanQ
Offline VSIX installation
The offline package is a versioned GitHub Release asset. Install it without
unpacking or modifying it:
code --install-extension planq-0.1.7.vsix
code --list-extensions --show-versions | grep '^planq-cli\.planq@'
Troubleshooting
- Run
planq version in the VS Code launch environment.
- Set
plan.server.path to an absolute executable path when PATH lookup fails.
- Open Plan: Show Language Server Output for startup, stderr, exit, and
restart details.
- Open the Plan Preview output channel for bridge startup or URL errors.
- Restart the language server after upgrading the CLI.
- Reinstall the CLI if bundled resources are missing or mismatched; restart
preview after updating. Old session records are not migrated.
- Confirm that loopback traffic is allowed when the local preview remains blank.
- See the PlanQ troubleshooting guide
for installation and environment-specific checks.
License
This extension is source-available under the
PolyForm Noncommercial License 1.0.0. It is not offered under an
OSI-approved open-source license.