cds-text-sync

Turn a binary CODESYS project into a folder that Git, editors, CI tools and LLM agents can understand. Export the project, review or change its text on disk, then import it back into CODESYS.

This is an independent MIT-licensed tool, not an official CODESYS product.

1. Quick start

Requirements: Windows, CODESYS V3.5 SP10+ (SP13+ recommended), and Python 3.11+.

Install the tool and CODESYS menu scripts:

irm https://raw.githubusercontent.com/ArthurkaX/cds-text-sync/main/irm/setup.ps1 | iex

For each project, the important path is:

1. Open the project in CODESYS and run Project_directory.py. Press Enter to take the suggested <project>-cts folder beside the .project file, or pick your own.
2. Run Project_export.py. All supported .st and .csv text exports are enabled by default.
3. Edit project-view/ and commit the changes to Git.
4. Run Project_import.py to apply disk changes back to CODESYS.

That is enough for the first export/import cycle. Project_options.py is only needed for advanced settings such as sync mode, layout, profile or projection selection; the same settings can be read and changed offline with cts config show / cts config set. See the installation guide if the scripts do not appear under Tools > Scripting.

New here? Onboarding: your first hour walks the same path with the detail this list leaves out — where the commands live in the menu, how to put the ones you repeat on a quick-access toolbar button, and the one choice that is fixed once you export.

2. Git workflows

Choose the workflow on an empty sync folder before the first export. The mode is fixed for that folder; changing it later means creating a new empty sync folder and exporting again.

I only want readable .st files

Choose text-first in Project_options.py.

• .st is the source of truth for Structured Text edits.
• Structural XML is kept in the tool-owned .dump/xml/ mirror instead of the normal Git view.
• This is the convenient mode for external editors, code review and LLM work.
• XML objects that must stay hand-editable, such as visualizations, can still be kept in the view.

I need full control, including XML

Keep the default XML-first mode.

• Native XML in project-view/ is the canonical round-trip format.
• Readable .st and .csv projections are generated beside it; all supported text projections are enabled by default.
• This mode is the right choice when Git must show and control devices, tasks, visualizations and other non-ST project structure as well.

More detail: sync modes, project layout, and team workflow.

3. I want to find errors in my project

Export the project first, then run the analyzer against its .st files. It is offline: no CODESYS window, daemon or PLC connection is required.

cts analyze --workspace C:\path\to\sync-folder
cts analyze --workspace C:\path\to\sync-folder --format sarif  # CI/code scanning
cts analyze rules
cts analyze explain CTS0007  # for example, indentation

You can open the desktop findings view with Project_analyze_ui.py. Safe autofixes are previewed before they are applied, including structural indentation fixes where available.

▶ Click to open the animation: Static Analyzer findings UI

Details: static analyzer.

One command for "is this shippable?"

cts verify runs every applicable check — static analysis, SVG sketch lint, and (if CODESYS is open) the compiler — and returns a single verdict with a single exit code. The offline stages only read; the compiler stage touches IDE build state and --with-test writes to the PLC, so those two are not read-only.

cts --pretty verify --sync-folder C:\path\to\sync-folder
cts verify --with-test      # also run the .test/ plans on the PLC

A check that cannot run (no IDE open) is reported as skipped and marks the run incomplete — it never turns into a failure. Exit codes: 0 pass, 1 real problems, 2 could not start, 3 incomplete with --incomplete error.

▶ Click to open: Quick ST formatting inside CODESYS

Use Project_fmt.py from Tools > Scripting when one Structured Text object looks untidy and opening the full Analyzer would be unnecessary. It aligns variable declarations and repairs structural code indentation directly in the open IDE object.

1. Select a POU, GVL, or DUT in the project tree.
2. Run Project_fmt.py from Tools > Scripting.
3. Filter the object list or select a block. The list shows which blocks need formatting.
4. Open one block, or choose Review All to review blocks from the top.
5. Compare the Before and After panes. Changed characters are highlighted, and Previous change / Next change navigate the preview.
6. Choose Apply, Skip, or Stop. Use the normal CODESYS Undo command if you need to revert an applied change.

More details: Project_fmt script guide.

▶ Click to open the animation: FSM transition map

If your code is built around state machines and you often have to read one quickly — an unfamiliar CASE, or your own from six months ago — run Project_fsm.py from Tools > Scripting, or cts fsm ui from the shell. It reads the exported .st files offline and draws each machine as a GRAFCET diagram: numbered steps, one bar per transition with its receptivity beside it, and a step with several ways out fanned out as a divergence. Click a step or a transition row to highlight it; right-click either one to read the Structured Text it was drawn from.

More details: Project_fsm.py script guide and cts fsm.

4. I want an LLM agent to control the project

Start Project_daemon.py from CODESYS Tools > Scripting. It exposes the currently open project to the cts CLI. An agent can then export, inspect, change, compare, import and build without clicking through the IDE:

cts status                 # check daemon, project and sync folder
cts set-sync-folder C:\path\to\sync --save  # configure it through the agent
cts set-sync-folder --save # or automatically use the saved project directory
cts export                 # CODESYS -> project-view/
cts compare                # inspect IDE vs disk
cts import                 # project-view/ -> CODESYS
cts build                  # build the active application
cts analyze --workspace .  # offline check; daemon is not required
cts verify                 # every applicable check, one verdict, one exit code
cts config show            # effective settings and where each value came from

▶ Click to open the animation: using the cts CLI

Several IDEs at once: point the agent at one project

Each running CODESYS IDE has its own daemon window. The top of that window shows a target line, IDE: ide-<pid> · <project>, with a Copy button. Copy puts a ready-made line on the clipboard:

!cts --target ide-6128 --expect-project example_lib --help

Paste it into the agent's chat and the agent learns in one step which IDE and which project it should work with. Every later command carries the same --target and --expect-project, so it cannot land in the wrong IDE, and it refuses to write if someone has switched the IDE to another project. The --help at the end prints the command list together with the state of that instance. This is what lets two agents work on two projects in parallel, for example an application and the library it uses. With more than one IDE open, cts without --target refuses and prints the available targets.

A library project has no application to compile. cts build checks it, and cts build --install does what the IDE button "Save project and install into library repository" does, so an agent can develop a library end to end.

The CLI also exposes project-tree operations, PLC interaction, tests and diagnostics. Read the CLI reference.

Give an LLM agent the full picture of the project

An agent working on the project blind — with no visibility into its own POUs or the library functions it calls — has to guess signatures or grep raw sources. cts docs reads the exported project and the libraries it actually references, and writes compact per-symbol markdown so the agent knows every POU's kind, interface and doc comment, and every referenced library function's signature, without ever opening the raw CODESYS sources:

cts docs --workspace C:\path\to\sync
cts docs --daemon --libraries "C:\ProgramData\CODESYS"

Output goes to .cts-docs/: project.md and libraries/*.md (one section per POU — kind, name, doc comment, interface table), an index.md summary with a Missing LibDoc and Not referenced section, and machine-readable symbols.jsonl / manifest.json. Only libraries the Library Manager actually references are documented; nothing outside the project's own dependencies is pulled in. .cts-docs/ is generated, so export/import/compare ignore it and the recommended .gitignore entries cover it; --output writes elsewhere.

Details: documentation bundle.

Generate visualization screens from SVG

An agent can create an SVG sketch as plain text, lint and preview it, compile it into a CODESYS visualization, and import the result through the same daemon:

cts visu new --name Line1 --w 1024 --h 600 --out line1.svg
cts visu lint --svg line1.svg --fix
cts visu preview --svg line1.svg
cts visu from-svg --svg line1.svg --create-screen --screen-name Line1
cts import

Details: HMI screens from SVG.

Documentation

• Installation
• Sync modes
• Script overview
• Project layout
• CLI reference
• Static analyzer
• HMI screens from SVG
• Profiles
• Operating guides — also shipped in the package, listed with cts guide
• Releases and rollback

Issues, friction reports and feature requests are welcome in the GitHub issue tracker. See the changelog for release history.

MIT License.