PangoLint User Manual

§ 01Quick start

1. Install the VS Code extension from the Marketplace:

   code --install-extension jd3lasersllc.pangolint

2. Open any .BeyondCode file. Syntax highlighting, diagnostics, completions, and the activity-bar sidebar light up automatically.
3. Open the PangoLint view container (laser-warning icon in the activity bar) to browse commands and objects.
4. To enable BEYOND runtime features, configure pangolint.beyond.talkTcpHost to point at your dev BEYOND machine (and pangolint.beyond.talkTcpPort if needed), then run PangoLint: Test BEYOND Connection from the Command Palette.

That's it for the extension. For the MCP server, see The PangoLint MCP server below.

§ 02The editor

Syntax & semantic highlighting

PangoLint registers .BeyondCode as the pangoscript language. You get:

• TextMate grammar with scopes for labels, commands, expression functions, variables, object paths, operators, OSC addresses, and string/comment forms.
• Semantic tokens so commands that PangoLint actually knows about render differently from unknown identifiers - useful for spotting typos at a glance.
• A document outline (Outline view, breadcrumbs) generated from script labels.

Diagnostics

PangoLint ships 22 diagnostic codes. The full reference with cause and how-to-fix lives in docs/references/diagnostics/README.md; this is the summary.

PangoLint biases permissive - most rules are warning or hint level. Real errors are reserved for unambiguous syntax failures (unclosed-string, unbalanced parens). Click any diagnostic in the Diagnostics sidebar panel and use the Why? action to open the bundled reference scrolled to that rule's section.

Run PangoLint: Validate Current Script from the Command Palette to refresh diagnostics for the active .BeyondCode buffer and write a portable report to the PangoLint: Validation Output channel. The report lists severity, rule code, line / column, and the same human-readable explanation shown by the editor hover. The completion toast offers shortcuts to the Diagnostics sidebar, the Output channel, and the Problems panel.

Completions, hover, signature help

• Command completions - type a command name and PangoLint suggests matches from the bundled catalog (529 command entries). Each suggestion carries a description, syntax form, and safety tier.
• Property completions - type Master. (or Zone.0., FX.0., etc.) and PangoLint suggests properties from the schemas.
• Goto label completions - after Goto or If ... Goto , PangoLint suggests labels declared in the current file. Declared variable goto targets keep their variable-reference behavior.
• Hover tooltips - hover any command name for a Markdown card with the syntax form, parameters, safety tier, and a primary example. Hover an object path for property listings, with segment-aware detail (root, array index/button name, property segment).
• Signature help - start typing a command's arguments to get an inline signature panel with parameter names, types, and ranges.

Quick fixes

Click the lightbulb (or Cmd+. / Ctrl+.) on:

• An unknown-command warning - accept a Levenshtein-ranked replacement.
• A property-typo hint - accept the closest valid property name.
• An unknown property-path root - register it as a user universe (inherits UniversePanel), a zone alias (inherits Zone), or a master alias (inherits Master). See User objects.

Formatting

Run Format Document (Shift+Alt+F) or wire format-on-save:

// .vscode/settings.json
{
  "[pangoscript]": {
    "editor.defaultFormatter": "jd3lasersllc.pangolint",
    "editor.formatOnSave": true
  }
}

The formatter is intentionally conservative:

• Preserves command order, strings, comments, labels, and unknown syntax verbatim.
• Normalizes whitespace and indentation only where it can do so safely.
• Will not collapse, reorder, or transform any line it doesn't fully recognize.

Snippets

Type the prefix and press Tab. All 10 snippets:

Color decorators

Inline color swatches appear next to the value for:

• ColorBGR <hex> literals
• ColorRGB <hex> literals
• <Object>.Color = <int> literal assignments

Click the swatch to open VS Code's color picker. The picker round-trips the change back into the source format (BGR stays BGR, RGB stays RGB, integer literals stay integer literals).

Navigation: Goto label, references, label highlighting

• Go to Definition (F12) on Goto MyLabel jumps to MyLabel:.
• Cursor on a label (declaration or any Goto reference) highlights every other occurrence in the file.
• Optional References code lens above each label declaration - enable with pangolint.codeLens.labelReferences: true.

§ 03The sidebar

Click the laser-warning icon in the activity bar. The PangoLint view container has four stacked panels: Commands, Objects, Diagnostics, and the BEYOND Watcher.

Commands view

A webview browser over 521 browsable PangoScript commands plus 7 expression functions. Prototype, internal, and do-not-use commands remain known for diagnostics and direct lookup, but stay out of the browsable list.

• Full-text search across canonical name, aliases, description, and BEYOND category. Type into the search box at the top.
• Category groups partition the catalog into 35 BEYOND-style categories (General, Cue Clicking, Main Toolbar, Transition, Live Control, FX, and more). Click a category header to collapse / expand its commands; Expand All opens every group at once.
• Click any command row to expand the inline detail panel - signature, BEYOND category, primary example.
• Detail-panel actions:
  • Insert at cursor - drops the example into the active editor.
  • Copy signature - copies the syntax form to clipboard.
  • View in full reference - opens the bundled offline PangoScript reference site in your default browser, deep-linked to that command.
• Keyboard insert. With a row focused, press Cmd+Enter (macOS) / Ctrl+Enter (Windows / Linux) to insert the example at the cursor - no mouse needed.
• Cross-link from the editor. In any .BeyondCode file, hover a command name and click View in Commands sidebar, or right-click → View in Commands sidebar. The Commands view scrolls to that command and expands its detail panel.

Objects view

A webview browser over BEYOND's object surface, organized into three sections:

1. FX Effects - every visualizer FX category and effect.
2. Cue Types - every cue-type code with its description.
3. Objects - Master, Zone, UniversePanel, ColorChannel, DmxOutput, Projector, ProTrack, QShift, and the rest of the bundled schemas with their property listings.

Search filters across all three sections in one pass. Right-click any property path:

• If a setter command is mapped, Insert drops it at the cursor (e.g. right-click Master.BPM → inserts SetBpm).
• View in Commands sidebar - jump to the matching command in the Commands view.

The Objects view reads only bundled data - no network access, no live BEYOND inspection. (For live values, see Live hover values and the Watcher.)

Diagnostics view

Issues in the active .BeyondCode file, grouped by rule. Each rule group has:

• A row per diagnostic. Click to jump to the source range.
• A Why? action that opens the bundled diagnostics reference scrolled to that rule's section - works offline, no internet needed.

§ 04BEYOND runtime integration

PangoLint can talk to a developer-local BEYOND for connection checks, property readbacks, and gated script-batch sends. All runtime features require a trusted workspace. Readback-only features require an explicit command or pangolint.beyond.liveHoverValues: true. Write/script execution features additionally require pangolint.beyond.allowScriptExecution: true and an in-app confirmation prompt. Runtime target settings are machine-scoped so a workspace cannot silently repoint PangoLint at a different BEYOND host.

Test BEYOND connection

Command Palette → PangoLint: Test BEYOND Connection.

PangoLint sends a small OscOutTTS ping over the configured BEYOND Talk path, then waits for the OSC echo on oscListenHost:oscListenPort. The status bar reports success or the specific failure mode (DNS lookup, bind, no callback, etc.). Readback-only - no projector, output, geometry, or zoning state is touched.

User objects (register a universe / zone alias)

PangoScript code commonly references workspace-scoped identifiers like MyUniverse.Button1.X or MainStage.Brightness. PangoLint doesn't know these out of the box. When such a path appears, PangoLint surfaces a code action lightbulb:

• Register <Root> as a user universe - inherits the UniversePanel schema, with workspace-scanned button names merged in as arrayIndices.
• Register <Root> as a zone alias - inherits the Zone schema.
• Register <Root> as a master alias - inherits the Master schema.

Registry persists at .pangolint/user-objects.json (workspace-rooted). View / remove entries via PangoLint: Show User Objects and PangoLint: Remove User Object in the Command Palette.

When pangolint.folderScopedUniverses: true (default), PangoLint also auto-discovers universe panels by scanning sibling .BeyondCode files - if an unknown root appears in 2+ files in the same parent folder, it's treated as a universe panel without explicit classification. This mirrors BEYOND's workspace-scoped object visibility.

Send Talk batch to BEYOND

Two commands send straight-line PangoScript over BEYOND Talk:

• PangoLint: Send Talk Batch to BEYOND - sends the entire active .BeyondCode file.
• PangoLint: Send Selection as Talk Batch - sends just the highlighted selection. Right-click → Send Selection as Talk Batch works inside any .BeyondCode editor.

Both gates:

1. pangolint.beyond.allowScriptExecution: true - explicit opt-in.
2. Workspace must be trusted.
3. Confirm modal - by default, confirmRunEachSession: true shows the modal every run, not just the first. Recommended on for safety.
4. Lint-before-send refuses any text that fires an error-severity diagnostic, or any text where PangoLint's analysis limits prevent a full lint pass. Hint and warning diagnostics surface in the response but don't block.
5. Control-flow blocked - BEYOND Talk isn't editor-equivalent. PangoLint blocks labels, goto, if, loops, waits, and exit in this path. Paste full control-flow scripts directly into BEYOND's PangoScript editor instead.

After a successful send, PangoLint: Re-send last Talk Batch replays the same batch (skips the lint, keeps the gates) - useful for tight iteration when nothing's changed.

Talk TCP can show BEYOND command replies and parser errors in the PangoLint: Run Output channel. Talk UDP is a valid primary transport, but it is send-only from PangoLint's side, so the Output channel reports datagram send status instead of BEYOND parser replies.

Fetch / set object values

• PangoLint: Fetch object value from BEYOND - Command Palette or right-click → reads a property path you enter (e.g. Master.Brightness). Sends OscOutTTS with a typed return tag, awaits the OSC callback, and shows the value inline.
• PangoLint: Set object value on BEYOND - Command Palette or right-click → writes a value to a property path. Gated like Send Talk batch. String values are entered without wrapping quotes; PangoLint serializes exactly one assignment line before sending.

Watcher: pin a property

The BEYOND Watcher is the bottom panel of the PangoLint sidebar. It's always visible; pinned properties appear inside it. Pin / unpin from the editor:

• Right-click a property path → Pin property to BEYOND Watcher.
• Right-click a watched item in the view → Unpin from Watcher.

Watcher view actions:

• Refresh Watcher - re-reads every pinned property in one batch.
• Clear all watched properties.

The watcher does not poll automatically - refreshes are explicit. This keeps network traffic predictable.

Validate objects in this file against BEYOND

Command Palette → PangoLint: Validate objects in this file against BEYOND.

PangoLint walks every property path referenced in the active file and issues a readback against BEYOND. Paths that resolve are cached as live-confirmed; paths that time out or return an error are reported in the PangoLint: Run Output channel and summarized in a notification. Useful as a pre-flight before sending a script, especially when you've added new universes / zone aliases since the last verified send.

Live hover values

Set pangolint.beyond.liveHoverValues: true to augment property-path hover tooltips with the current BEYOND value. Cached for 30 seconds per path. Off by default - generates network traffic on every hover. A nice quick-glance feature when actively tuning, but unnecessary the rest of the time.

§ 05The PangoLint MCP server

pangolint-mcp is a Model Context Protocol stdio server that exposes the same curated knowledge to AI coding agents. It ships from the mcp/ workspace in this repo and reads from the same data/pangoscript/ knowledge base the extension uses, so upgrades stay in lockstep.

When to use it

• You ask Claude / Codex / Cursor / another agent to write or edit PangoScript and you want command-name verification against PangoLint's curated catalog, not hallucinated names from training data.
• You want the agent to lint generated PangoScript before showing you the result.
• (Opt-in) You want the agent to send lint-clean PangoScript to a developer-local BEYOND for fast visual feedback.

If you don't use AI agents in your PangoScript workflow, you don't need the MCP server.

Install & configure

Install the published package from npm:

npm install -g pangolint-mcp
which pangolint-mcp

Or install the pangolint-mcp tarball attached to a GitHub Release:

npm install -g ./pangolint-mcp-0.7.29.tgz
which pangolint-mcp

For local development, build the same tarball from this repo:

npm run package:mcp
npm install -g ./mcp/pangolint-mcp-0.7.29.tgz
which pangolint-mcp

Wire it into your MCP-aware client by adding a stdio entry:

Use PangoLint as the client-side server key when your client allows mixed-case names. Some clients show this key in tool-call UI.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "PangoLint": { "command": "pangolint-mcp" }
  }
}

Claude Code (.claude/mcp.json or your CLI's MCP config)

{
  "mcpServers": {
    "PangoLint": { "command": "pangolint-mcp" }
  }
}

Codex CLI

codex mcp add PangoLint -- "$(which pangolint-mcp)"
codex mcp get PangoLint

If the old lowercase pangolint alias is already registered, run codex mcp remove pangolint first, then add it again.

To enable read runtime tools in Codex, add the startup env vars when you register the server:

codex mcp add PangoLint \
  --env PANGOLINT_MCP_RUNTIME_READ=enabled \
  --env PANGOLINT_MCP_BEYOND_TALK_TRANSPORT=tcp \
  --env PANGOLINT_MCP_BEYOND_TALK_TCP_HOST=127.0.0.1 \
  --env PANGOLINT_MCP_BEYOND_TALK_TCP_PORT=16063 \
  -- "$(which pangolint-mcp)"

Cursor / VS Code (with MCP)

{
  "servers": {
    "PangoLint": { "command": "pangolint-mcp" }
  }
}

To enable read runtime tools (network access to a local BEYOND), pass PANGOLINT_MCP_RUNTIME_READ=enabled and your BEYOND target as env vars. Add PANGOLINT_MCP_RUNTIME_WRITE=enabled only when you also want agents to send scripts through runScript.

{
  "mcpServers": {
    "PangoLint": {
      "command": "pangolint-mcp",
      "env": {
        "PANGOLINT_MCP_RUNTIME_READ": "enabled",
        "PANGOLINT_MCP_BEYOND_TALK_TRANSPORT": "tcp",
        "PANGOLINT_MCP_BEYOND_TALK_TCP_HOST": "127.0.0.1",
        "PANGOLINT_MCP_BEYOND_TALK_TCP_PORT": "16063"
      }
    }
  }
}

The full env-var list lives in mcp/README.md.

Knowledge tools (always on)

Eleven offline tools the agent can call without any opt-in:

Runtime tools (opt-in)

Four tools that talk to the configured BEYOND host. Read runtime and write runtime are separate opt-ins. Each tool returns { ok: false, blocked: true } unless the matching runtime tier was enabled at server startup.

MCP resources

Eight resources for browsing the bundled knowledge base directly:

Each advertises a size hint so MCP clients can budget context before fetching.

§ 06Reference: settings

All settings live under the pangolint.* namespace. The pangolint.beyond.* runtime settings are machine-scoped; configure them in user or machine settings, not workspace settings.

§ 07Reference: commands

Every command is also reachable from the Command Palette under PangoLint:.

Editor & validation

BEYOND runtime

User objects

Sidebar

§ 08Reference: keybindings

§ 09Safety, privacy, and data

PangoLint biases conservative on three axes:

• Network behavior. Nothing on the network unless you've explicitly configured a BEYOND host and invoked a runtime command.
  • Knowledge tools, sidebar, completions, hover (without liveHoverValues), formatting, diagnostics - all 100% offline.
  • Test BEYOND Connection is readback-only (an OscOutTTS ping).
  • Send Talk Batch, Set object value, and the MCP runScript require explicit opt-in (allowScriptExecution: true for the extension; PANGOLINT_MCP_RUNTIME_WRITE=enabled for the MCP server) and a trusted workspace.
• Workspace mutations. PangoLint writes to two places only: .pangolint/user-objects.json (when you accept a register-as code action) and the active editor (when you explicitly insert a command / accept a quick fix). No silent edits.
• What's bundled. The repo ships a curated knowledge base derived from BEYOND's published exports. Verbatim Pangolin reference materials (BEYOND command export .txt, OSC HTML, local help) are not in the public repo. End users get the pre-generated data/pangoscript/commands.merged.json and do not need private source inputs.

§ 10Troubleshooting

Test BEYOND Connection times out.

Confirm pangolint.beyond.talkTcpHost matches the BEYOND machine's IP (not 127.0.0.1 if BEYOND is on a separate box), and confirm pangolint.beyond.talkTcpPort matches the Talk TCP server port. If you explicitly use UDP, check pangolint.beyond.talkUdpHost and pangolint.beyond.talkUdpPort instead. Confirm BEYOND is configured to send OSC Out callbacks back to your laptop's IP on pangolint.beyond.oscListenPort. macOS / Windows firewall must allow the listener port.

Talk batch sent, BEYOND unchanged.

Check whether the script uses control flow (label: / goto / if / loops / waits / exit). BEYOND Talk is for straight-line command batches only; paste full scripts directly into BEYOND's PangoScript editor. The BEYOND Notification Center (in BEYOND itself) is the runtime oracle for failed sends; check it when a probe inexplicably no-ops.

Pasted script collapsed into one line.

BEYOND's paste path treats LF-only clipboard text as one logical line. .BeyondCode files intentionally check out with CRLF endings. Confirm CRLF before copying.

Property hover says "unknown root".

The root identifier isn't in the canonical schemas and hasn't been registered as a user object yet. Click the lightbulb on the unknown root to register it as a universe / zone alias / master alias, or enable pangolint.folderScopedUniverses so PangoLint auto-discovers universes from sibling files.

MCP runtime tool returns { ok: false, blocked: true }.

The server was started without the required runtime tier. Add PANGOLINT_MCP_RUNTIME_READ=enabled for healthCheck / readBeyondProperty, or PANGOLINT_MCP_RUNTIME_WRITE=enabled for runScript, then restart the client. The agent is instructed not to retry - it should tell you how to enable runtime instead.

Markdown reference link from Why? doesn't open.

The bundled diagnostics doc lives inside the VSIX. Reload the VS Code window after upgrading PangoLint so the new doc path resolves.