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 Microsoft Marketplace for VS Code / Cursor, or from Open VSX for Kiro, VSCodium and compatible editors. Free features work without an account. The extension loads when the workspace contains Logix project files.

Choose your marketplace

Editor compatibility

Editor API compatibility and marketplace access are both required. Package targets and runtime validation are distinct; check the support status below.

Extension load triggers

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

Activate Pro

Free needs nothing. To unlock Pro (Git, Visual Diff, editing, Merge UI, AI Context) you activate a license once — pick the path that matches your machine:

Requirements

• Git must be installed — the version-control, diff, and merge features depend on it. If you don't already have it, download and install from git-scm.com (most PLC / electrical engineers won't have Git yet; the default installer options are fine).
• No CLI tools to install — L5X explode / implode and all Git operations run fully inside the extension on every platform, with zero setup.
• Preview, Git, visual diff/merge, interactive editing, AI queries and L1 checks run on Windows, macOS and Linux. ACD conversion and Typed Patch L2/Apply require Windows and the SDK; L2 also requires a supported Studio 5000 v37+ project.

Extension settings

CtrlLens works with zero configuration. Explode / implode and Git run in-process — there are no CLI paths to set. The ACD ↔ L5X converter (ctrllens-acd, Windows only) ships inside the extension and is resolved automatically; you never point at it. The only optional setting is the SDK location, and even that is auto-detected:

Logix Designer SDK (Windows only) — version 2.2.x required (the bundled ctrllens-acd is built against the 2.2.1109 client and must match the installed SDK 2.2 backend). Example default install location:

C:\Program Files (x86)\Rockwell Software\Studio 5000\Logix Designer SDK

CtrlLens auto-detects this on launch and fills the setting for you. If it isn't found, CtrlLens shows a one-time prompt with install / set-path options — or set ctrllens.logixDesignerSdkPath manually.

Behavior & display 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.

CtrlLens creates new tags, tasks, programs, routines, and Add-On Instructions through Studio 5000-style dialogs and writes them straight into the exploded tree — so a new component is an ordinary Git change you can diff, review, and revert. Needs an exploded project and a Pro license.

Where each dialog lives

What the dialogs refuse

Every field is checked against what Studio 5000 actually accepts on import, so CtrlLens cannot produce a project you are then unable to open. Values validate on each keystroke and Create stays disabled until the reason on screen is cleared.

• Names follow the IEC 61131-3 identifier rule Studio 5000 enforces — begin with a letter or a single underscore, letters/digits/underscores only, at most 40 characters, never two underscores in a row, never a trailing underscore. The error names the exact rule you broke.
• Task — Period 0.1 … 2,000,000 ms, Watchdog 1 … 2,000,000 ms, Priority 1 … 15.
• Add-On Instruction logic is Ladder, Function Block Diagram, or Structured Text — SFC can call an AOI but cannot implement one. Picking the Safety class narrows the choice to Ladder.
• AOI Revision — major 1 … 65535, minor 0 … 65535.
• Controller-scope-only data types (AXIS_*, MOTION_GROUP, COORDINATE_SYSTEM) cannot be created program-local.

After a tag is created

Open routines pick it up on their own: the red undefined-tag highlight clears, and the tag appears in the Tag Browser and in operand autocomplete without reopening anything. From the Command Palette this is immediate; created on the canvas it follows within about half a second.

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.

Cross Reference (Pro)

The Studio 5000 Cross Reference workflow, inside CtrlLens. In edit mode, right-click any element that carries a tag — an RLL instruction, an FBD IRef / ORef / block, an SFC Step or Transition — and choose Cross Reference For "<tag>". A Cross Reference tab opens with the Studio 5000 “By Logic” table: one row per occurrence across every RLL, FBD, SFC, and ST routine in the project, including Add-On Instruction definitions — with Container / Routine / Location anchors, the alias base tag, the tag description, and a Destructive column (Y the instruction can write the tag · N read-only · ? unknown).

• Double-click a row to jump there — the routine opens with the referencing instruction / element selected; ST references open the .st source at the line.
• Filter and sort — Show toggles All / Destructive / Non-Destructive, the Name box accepts a member path (Timer1.DN) or a trailing-* prefix wildcard (Mot*), and column headers sort. A base-tag query includes member references — Timer1 also finds Timer1.DN and Timer1.ACC.
• Agents get the same data — the ctrllens_find_references MCP tool returns identical rows for AI-side impact analysis (see AI integration).

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 TO commits (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 htm-extracted full instruction 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)
• System status flag access rules (S:FS, S:N, S:Z, S:V, S:C, S:MINOR, S:R) — a read-only flag used as the target of a writing instruction is a precise error, exactly as Studio 5000 verify behaves

Add-On Instruction definition rules

An AOI definition is checked as a whole, not just rung by rung. Encrypted AOIs are skipped — Studio 5000 validated them when they were sealed and their bodies cannot be inspected.

• Input and Output parameters must be an atomic type; structures, strings, arrays and MESSAGE belong on an InOut parameter.
• Local tags may not be MODULE / MESSAGE / ALARM / Motion types, or multi-dimensional arrays.
• Instructions Studio 5000 blocks inside an AOI are rejected in every scan-mode routine — Logic, Prescan, Postscan and EnableInFalse: BRK EOT EVENT FOR IOT JSR JXR MAOC PATT PCLF PCMD PDET POVR RET SBR SFP SFR. A Structured Text FOR … DO … END_FOR loop is a language construct rather than the FOR instruction, and is left alone.
• Circular AOI call chains are an error; nesting deeper than 8 levels is a warning.
• Transitional instructions (ONS, OSR, OSF, MSG, PXRQ, SRT) inside an AOI with no EnableInFalse routine are a warning.
• Safety AOIs must use Ladder Diagram logic.

Limits that follow your controller

Several Rockwell limits are not a single number — they move with the controller family and the Logix Designer version. CtrlLens reads the project's own processor type and major revision and applies the matching one, so you are never warned about a ceiling your controller does not have. An unrecognised catalog number skips the check instead of guessing a family.

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_timestamp drives 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). Four layers cooperate so the agent reads, modifies, and extends a Logix project safely — context files, an XML bridge, cross-view validation, and a built-in MCP tool server — 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 </> XML button 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:

Scan-behaviour contracts. PROJECT.md also spells out the rules an AI model reliably gets wrong from training data alone: how the two Structured Text assignment operators differ across scan modes ([:=] resets on prescan, := keeps its last value), when S:FS really fires, and the conditionally-scanned timer hazard that can silently lose up to 69.9 minutes. The naming-convention section now also explains what each prefix it detects in your project conventionally means, instead of only listing it.

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. The AGENTS.md template also scaffolds a Sample Projects section: list your reference projects once (path + one line each) and every agent session knows where they live — agents can read them directly or point the MCP tools at a sample via projectRoot. A Style Guide section works the same way: list your coding-standard documents once (naming conventions, state-machine patterns, comment style) and agents read them before generating or reviewing logic — a markdown or PDF your agent can read is enough.

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.

15 MCP tools — understand, validate, review, apply

The built-in local stdio MCP server gives agents evidence-backed project queries and a two-phase Typed Patch workflow. CtrlLens does not call an AI API; your chosen agent controls any model connection and its data policy.

Prefer Typed Patch for new logic. Validate in an isolated copy, review the exact contract/diff/impact and gates, then explicitly approve Pro Apply. L1-only validation cannot authorize a typed apply. Both write paths refuse Safety, protected and encoded source.

Review changes with their evidence. Combine ctrllens_get_commit_diff, ctrllens_get_change_impact and routine context to explain changes using returned source anchors. Static MAY_IMPACT findings describe possible effects, not proven runtime behavior.

Annotate legacy routines. The separately approved legacy ctrllens_apply_rung can retain rung text and add comments. Review the resulting diff: untouched rungs are preserved, but XML separator line endings can change. Typed Patch can test body and comments separately; Safety explanations stay outside the source.

Run CtrlLens: Set Up AI Agent Tools (Client and Project Binding). Choose Codex or Claude Code, the client session folder, and the default PLC project separately. Preview the merge before choosing Write configuration; other servers and unrelated settings are preserved. Reload the client’s MCP server or start a new session in that folder, then confirm tool discovery.

Rerun setup after an extension upgrade or project move. Explicit projectRoot overrides the configured default; invalid bindings fail instead of selecting another project. CtrlLens: Show AI Tools Configuration and Binding Status reports configuration, not proof of a live client connection.

Understand a project from source evidence

Start with get_project_map, locate relevant objects with search_project, then inspect get_routine_semantics. Pro trace_signal follows bounded may-influence paths. Results carry snapshot IDs and exact, conservative or unknown certainty. Optional state-machine analysis exposes native SFC structure; RLL/ST candidates are experimental and do not prove reachability or scan order.

Open the returned navigation.openUri in the editor hosting CtrlLens to inspect read-only XML/ST after snapshot checks. If a client cannot open it, use Developer: Open URL with the exact URI. This opens source, not a canvas selection; historical, missing, stale or protected evidence may be unavailable.

Supported AI tools

A PlcPatchSetV1 declares the intended change and its checks as PLC-domain data. Validation runs in a disposable copy. Your project is written only after approval of the exact reviewed evidence.

Supported changes

Offline exploded Standard Program routines only: insert, replace or delete RLL rungs, or replace a complete ST routine. A patch can contain up to 50 operations across declared targets. FBD/SFC writes, Safety/protected/encoded source, Tag/UDT/AOI schema and hardware/task/program/motion configuration are outside this path.

From a proposal to a reviewed change

1. 1Get patchPreconditions from ctrllens_get_routine_context for every target. Use the exact snapshot and routine/rung hashes; declare expected reads, writes, calls, constraints, invariants and acceptance tests.
2. 2Call Free ctrllens_validate_patch with validationLevel: "L2". Fix failures and validate again. For a saved patch JSON, run CtrlLens: Review and Validate Typed Patch….
3. 3Review the contract, before/after logic and comments, impact, invariants, acceptance, L0/L1/L2 results, patchHash and reviewHash. The panel offers Apply, Reject and Export Patch. Eligibility is not human approval.
4. 4After explicit approval, Pro ctrllens_apply_patch accepts receiptId, patchHash, reviewHash and the same projectRoot. Inspect the resulting diff and validation after application.

What each validation level checks

Receipts expire, can be used once, bind to one project and are invalid after the MCP server restarts. Apply rechecks the live snapshot and staged hashes, creates affected-file backups under .ctrllens/backups/, writes atomically and rolls back on failed post-checks. If project bytes change, obtain fresh preconditions and validate again.

Comments and acceptance tests

Text-present/absent tests can target scope: "body" or scope: "comments". RLL replacement supplies the complete new comment: include existing text to retain it; omission or an empty value clears it. Comment-only changes remain reviewable, and XML separator line endings may change.

Exploded L5X is plain text, so your project is just a standard Git repository — push it to any CI/CD host (GitHub Actions, Azure Pipelines, GitLab CI, …) and branch protection, pull-request review, and history all work out of the box. The Verify gate statically checks operand types, tag scope, and instruction signatures against the full Rockwell instruction catalog at commit time, 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.