Bring software-engineering discipline to PLC code

Git was built for text. A Studio 5000 project is a proprietary binary (.ACD) or one dense XML file (.L5X) — so plain Git gives you no diff, no review, no merge. CtrlLens closes that gap: it explodes the project into a per-routine tree, renders every change visually, resolves merge conflicts rung by rung, and keeps an always-current briefing on disk for your AI assistant.

CtrlLens is not a replacement for Studio 5000 — it is complementary. Studio 5000 owns hardware configuration, compilation, download, and online monitoring. CtrlLens owns the software-engineering layer Studio 5000 leaves open: version control, code review, multi-developer collaboration, CI/CD, and cross-platform access.

Install CtrlLens from the VS Code Marketplace — it runs in both VS Code and Cursor, from a single VSIX, on Windows, macOS, and Linux. Free features work immediately with no account and no network. The extension activates automatically when the workspace contains any Logix-related files, and stays dormant otherwise.

Auto-activation triggers

• RSLogix5000Content/RSLogix5000Content.xml — an exploded project
• acd_sync_config.yaml — a configured project
• any *.l5x or *.L5X file

Requirements

• l5xplode / l5xgit — the .NET CLI tools for L5X explode/implode, required for any L5X-level work on every platform.
• Logix Designer SDK (Windows only, optional) — needed only for ACD ↔ L5X auto-conversion. CtrlLens auto-detects the install directory; Git, diff, merge, preview, and editing all work without it.

Extension settings

The VCS Sync panel exposes the universal IDE triad. Each verb maps to a command:

First-time setup

1. 1Open the CtrlLens sidebar from the Activity Bar. The VCS Sync panel shows "No project configured".
2. 2Click New Project… and pick an .L5X (works everywhere, no SDK) or an .ACD (auto-converted on Windows + SDK) — or Open Project… to attach an already-exploded folder.
3. 3The ACD is an optional, per-project property. With no ACD linked the panel runs in L5X mode (Sync from L5X); ACD-only actions stay disabled with an explanatory tooltip until an ACD is linked or generated.

Joining an existing project (clone onboarding)

1. 1git clone <repo-url> the project repository and open the folder in VS Code.
2. 2CtrlLens detects the exploded structure and prompts: "Detected a CtrlLens project. Associate a local ACD file?"
3. 3Click Select ACD File to link your local ACD, or Later to skip and work in L5X mode.

Manual path configuration

If the onboarding prompt was dismissed, configure paths directly in the VCS Sync panel: click ... next to GIT REPO to browse for the project folder, and ... next to ACD to browse for the ACD file.

The CtrlLens sidebar contains three panels: the always-visible VCS Sync panel, the Project Organizer tree, and Git History.

Project Organizer (tree view)

Appears when a project loads and displays the PLC project structure. Click a node to open it:

Nodes carry inline descriptors: Tasks show [Continuous/Periodic/Event]rate & priority, RLL routines show (N rungs), ST routines (N lines), tag folders (N) count, and modules their catalog number.

Git History

Appears when a Git repository is detected. Shows commit history with hash, message, author, and date. Use the refresh button in the panel header to update.

Click any routine in the Project Organizer to open it. Graphical languages (RLL/FBD/SFC) render on a Konva canvas; Structured Text opens in VS Code's native Monaco editor with PM007-conformant syntax highlighting (100+ Rockwell instructions, bit access, region folding, conversion functions).

Canvas navigation

Toolbar & status bar

• Breadcrumb — Task > Program > Routine path, with badges for routine type and rung count.
• Edit button — toggles Preview ↔ Edit mode (exploded projects only). See Interactive editing.
• </> XML button — exposes the routine source to AI tools. See AI context.
• Status bar — rung info and modified indicator on the left, zoom controls on the right.

Click Controller Tags (N) or Local Tags (N) to open a Studio 5000-style tags table.

• Filter — type in the search box to filter by name (real-time, case-insensitive).
• Resize columns — drag any column-header border (minimum 40px).
• Right-click the Tags folder for diff and history options (see Visual diff).

Toggle the Edit button in the toolbar to enter edit mode. Editing is available for exploded projects only (not single .L5X files) and requires a Pro license.

Inline editing — three trigger zones (RLL)

Press Enter or Tab to confirm (Tab also advances to the next operand in tag-edit mode); Escape cancels. Double-click the comment line above a rung for a multi-line comment editor.

Selection, drag & drop, context menu

• Select — click an instruction or rung number; Ctrl+click to multi-select; Shift+click a rung number for a range; click a branch node (Start/Middle/End) to scope to the branch or path.
• Drag an instruction to move it (within or across rungs); Ctrl+drag to duplicate; drag a rung number to reorder rungs.
• Right-click an instruction, rung number, or branch node for Cut / Copy / Paste / Duplicate / Delete (plus Insert Rung After on rungs).
• Branch editing — +Branch inserts a branch at the selection; +BrLvl adds a parallel path. Deleting the second-to-last path auto-unwraps the branch.

SFC Action body / Transition editing

Inside the SFC editor, double-click an Action body or a Transition condition to open its ST code in a side Monaco tab (a virtual .st file). Edit, Ctrl S, and the content round-trips back into the SFC XML — the canvas refreshes automatically. Because the virtual file is a real document, AI tools can read and write these bodies directly.

Save flow

• Ctrl S (or the Save button) runs roundtrip validation (parse → serialize → parse) before writing the exploded XML.
• Closing a modified tab fires VS Code's native "Do you want to save the changes?"modal — Save / Don't Save / Cancel.
• Triggering Sync from ACD, a branch switch, or Merge while routines are dirty aggregates all modified tabs into one combined save prompt; Cancel aborts the upstream operation cleanly.

Tag hover popup

Hover any tag-bearing element for 500 ms to see a Studio 5000-style tooltip, available across RLL, FBD, SFC, and ST. The field set adapts to the operand kind:

The popup is read-only and never blocks clicks or drags. Sweeping to a different operand re-arms the 500 ms delay so it doesn't flicker.

Live tag values & power-flow

• Block instructions — each numeric operand row shows the resolved value in a value box below the operand text (Studio 5000 data-monitor style).
• BOOL highlight — BOOL operand rows get a green square at the right edge when the value is 1.
• Contact / Coil power flow — when the underlying BOOL is 1, the left/right wire stubs highlight green.
• Editing values (Edit mode, RLL) — double-click a value cell, type, Enter, then Ctrl S. CtrlLens writes back to the tag XML following program-local-then-controller scope rules; undo/redo keeps logic and values in lockstep.

Cam Editor (Motion CAM operands)

Block operand rows that accept a CAM-family tag render a … affordance. Click it to open the Studio 5000-style Cam Editor:

Position / Velocity / Acceleration / Jerk curves are drawn with a natural cubic spline (analytic derivatives), styled to match Studio 5000 Graph Properties, with pan/zoom and a resizable point table.

The VCS Sync panel is the central hub for all synchronization and Git operations. When configured it shows GIT REPO & ACD paths, the current branch, last commit time, ahead/behind sync status (e.g. ↑2 ↓1), and the remote URL.

ACD Modified banner

CtrlLens polls the ACD file's modification time every 10 seconds. When Studio 5000 saves the ACD, a yellow ACD Modified — needs sync banner appears.

Git operations

Sync operations

The panel adapts to the project's mode, derived from whether an ACD is linked and whether the SDK is available.

Content table

Shows per-component change status after syncing — Name (Program / Tags / DataTypes / Modules / Tasks), Status (Synced / Modified / Untracked), and a rung-level Changes summary (e.g. +2 ~1 -0 rungs). Click the Content header to collapse/expand; the state persists.

Commit

1. 1Type a commit message in the text area at the bottom of the panel.
2. 2Click Commit Changes (enabled only when modified items exist).
3. 3CtrlLens commits all changes in the exploded project directory.

SDK detection & platform gating

.ACD conversion requires the Logix Designer SDK (Windows only); the .L5X path is SDK-free everywhere. New Project… / Open Project… / Refresh are never gated — only ACD-specific buttons are.

Auto-detection checks your configured path first, then the standard Rockwell install locations; the detected directory is written back to the setting so it shows in the Settings UI. Override it via File → Preferences → Settings → "ctrllens" — the Sync panel re-renders immediately, no reload needed.

Default diff mode (HEAD vs working tree)

The Project Organizer decorates nodes against the last commit: ~M modified (yellow), +A added (green), -D deleted (red). Click any decorated node to open its diff.

Commit-to-commit diff

1. 1Click Compare Commits (git-compare icon) in the Project Organizer title bar.
2. 2Pick the FROM and TOcommits (or "Working Tree"). The picker spans all branches; branch tips show ref labels like HEAD -> main.
3. 3The tree updates with decoration badges. Click the Home button to return to HEAD vs Working Tree.

Routine-level diff

Right-click a Routine for View Diff — Compare Two Commits or Show Routine Commit History. Each language gets its own diff view:

Tags & program diff

• Right-click a Tags folder for View Tags Diff — Compare Two Commits or history — added/deleted/modified tags with name, type, value, and comment changes.
• Right-click a Program for Diff All Routines in Program vs HEAD — a summary of every routine change in the program.

When a Git merge conflicts in a graphical routine, CtrlLens opens a visual side-by-side merge view. It reads the three Git index stages (base / ours / theirs) directly rather than parsing conflict markers, so both sides always render as valid diagrams. Granularity depends on the language:

1. 1Click Merge in the Sync Panel after a conflicted pull.
2. 2Conflicted routines appear in the tree with U (unresolved) status; click one to open the matching Merge View.
3. 3Pick a winner per unit. For FBD, base-aware auto-seeding pre-resolves sheets that changed on only one side.
4. 4Click Confirm & Resolve to write the merged result. In-flight picks are saved to .git/ctrllens-merge-draft.json and restored if VS Code restarts mid-merge.
5. 5Conflicts CtrlLens cannot render (ST, tag definitions, add/add with no base) fall back to VS Code's native merge editor. Abort Merge returns to the pre-merge state.

Merge Review on a clean merge

Even when a git merge finishes with no conflicts, CtrlLens pops a Merge Review panel summarising the routine changes about to be committed — so an automated or fast-forward merge never lands unseen. Turn it off with ctrllens.merge.showReviewOnSuccess: false.

CtrlLens statically validates a project against the instruction catalog and Studio 5000 scope rules, surfacing issues in VS Code's native Problems panel.

What it checks

• Tag references resolve across all four scopes (Program-local / Controller / AOI parameter / AOI local tag)
• Operand kind / Type / Format / exhaustive-enum, from the 346-mnemonic htm-extracted catalog
• No duplicate rung numbers; routine names unique within a Program; no cross-scope duplicate tag names
• FBD orphan blocks; SFC Step ↔ Transition alternation
• Periodic-task overlap static estimate (rung-count × 10 µs vs Task rate)
• Instruction ↔ editor-language compatibility (RLL / FBD / ST); ST syntax (bracket pairing, keyword spelling)

Navigation, live feedback & gate

• Click a Problems entry to open the routine and scroll the canvas to the offending rung / block / element; F8 cycles natively.
• Live red highlight — a rung wire turns red the instant an operand is invalid and recovers when you type a valid tag or Ctrl Z; FBD/SFC shapes border red the same way. On by default in edit mode only — view mode stays clean because an imported L5X is already Studio 5000-valid, so any view-mode red would be a validator false positive. Pro users can opt into view-mode highlighting with ctrllens.validateInViewMode; the on-demand Verify commands report to the Problems panel regardless of mode.
• Pre-commit gate — before a Sync Panel commit, error-severity issues show a modal: Commit Anyway proceeds, Fix First jumps to the Problems panel.

Studio 5000 authors the logic; CtrlLens turns each project into a branchable, reviewable Git repo. Two PLC engineers work in parallel, while a senior engineer reviews and merges their pull requests — without ever installing Studio 5000, on any OS. Each step below is tagged with the tool that performs it, so you can see exactly where CtrlLens takes over from Studio 5000.

Local configuration

Each developer's machine-specific paths live in acd_sync_config.yaml at the project root. It is git-ignored on purpose:

# CtrlLens — local sync config (git-ignored)
source_acd_path: D:\Projects\MyProject.ACD
source_l5x_path: D:\Projects\MyProject.L5X
last_sync_timestamp: 1743465600000

A project carries whichever path key matches its mode; an L5X-mode project upgraded via Generate ACD gains a source_acd_path. last_sync_timestampdrives the 10-second ACD change detection that raises the "ACD Modified" banner.

Restore to a new ACD

If you cloned a project without a local ACD, click Restore to…, name a new .ACD in the Save As dialog — CtrlLens implodes the project → L5X → ACD — then open the result in Studio 5000.

CtrlLens is built to work alongside AI coding tools (Claude Code, Copilot, Cursor). Three layers cooperate so the agent reads, modifies, and extends a Logix project safely — without CtrlLens ever calling an AI API itself.

The </> XML bridge

AI tools can't see a Konva canvas — only files open in the text editor. The </> XMLbutton in the breadcrumb opens the routine's underlying XML so any agent in the IDE can read it. After the agent saves, a file watcher re-renders the canvas in under 300 ms.

The context bundle

On sync / open / Refresh Now, CtrlLens regenerates a deterministic markdown snapshot under <gitDir>/.ctrllens/context/, split across four files:

Everything is local-only and git-ignored. On first sync CtrlLens offers (once, declinable) to write an AGENTS.md at the root — the vendor-neutral standard read by Cursor / Copilot / Codex — plus a thin CLAUDE.md that imports it. Write your project-specific policies into AGENTS.md; CtrlLens never touches it again.

Cross-view validation & Tag Browser

If the AI references a tag that doesn't exist in scope, every shape that displays it turns red across all three views; when the AI creates the tag in a watched directory, the highlight clears within 2 seconds — no manual reload. The Studio 5000-style Tag Browser opens from any inline editor (Ctrl Space / Alt ↓) with virtual scrolling for 5k+ tag projects.

Supported AI tools

l5xplode / l5xgit are scriptable .NET CLI tools — run explode/implode and validation on any CI runner (GitHub Actions, Azure Pipelines, GitLab CI, …). The Verify pre-commit gate statically checks operand types, tag scope, and instruction signatures against the 346-mnemonic Rockwell catalog, blocking regressions before they reach a controller.

Ladder preview (canvas)

Edit mode

What's free vs Pro

A free user who triggers a Pro feature gets a one-time-per-session upgrade prompt — nothing is blocked silently.

License commands (Command Palette)

The status bar shows the current state — Free / Pro / Grace / Borrowed / Active Elsewhere / Expired; clicking an "Active Elsewhere" badge offers to take the slot back.