Skip to content
Back to search

cds-text-sync

πŸ”„ Git-friendly text synchronization for CODESYS. Export your project to ST files, edit with modern tools (or LLMs), and sync back. Lightweight and metadata-driven.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ArthurkaX/cds-text-sync with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ArthurkaX/cds-text-sync'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/arthurkax--cds-text-sync/badge.svg)](/listings/arthurkax--cds-text-sync)

HTML

<a href="/listings/arthurkax--cds-text-sync"><img src="/api/listings/arthurkax--cds-text-sync/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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](docs/install.md) if the scripts do not appear under **Tools > Scripting**.

New here? **[Onboarding: your first hour](docs/onboarding.md)** 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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

readMe.md Β· README Β· 390 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="img/cts-logo-dark.png">
  4. <img src="img/cts-logo.png" alt="CTS cds-text-sync" width="480">
  5. </picture>
  6. </p>
  7. <p align="center"><b>Your CODESYS project as text: Git, editors and AI agents work on it, the IDE stays in sync.</b></p>
  8. # cds-text-sync
  9. [![Release](https://img.shields.io/github/v/release/ArthurkaX/cds-text-sync?include_prereleases&sort=semver)](https://github.com/ArthurkaX/cds-text-sync/releases)
  10. [![CI](https://github.com/ArthurkaX/cds-text-sync/actions/workflows/ci.yml/badge.svg)](https://github.com/ArthurkaX/cds-text-sync/actions/workflows/ci.yml)
  11. [![Docs](https://img.shields.io/badge/docs-cds--text--sync.pages.dev-blue)](https://cds-text-sync.pages.dev/)
  12. [![License](https://img.shields.io/github/license/ArthurkaX/cds-text-sync)](LICENSE)
  13. [![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/TYJTeW64Kv)
  14. Turn a binary CODESYS project into a folder that Git, editors, CI tools and
  15. LLM agents can understand. Export the project, review or change its text on
  16. disk, then import it back into CODESYS.
  17. This is an independent MIT-licensed tool, not an official CODESYS product.
  18. <p align="center"><img src="img/cts-demo.gif"
  19. alt="A tour of cts on a demo project: the binary project becomes .st files in Git, the quick window carries an edit from disk into CODESYS and commits it, its own diff resolves a conflict per object, then static analysis, Format ST, a live FSM map, the diagram page and the command line an agent uses"
  20. width="100%"></p>
  21. ## 1. Quick start
  22. Requirements: Windows 10 or 11, CODESYS V3.5 SP16 or newer
  23. (tested on SP16 Patch 9 x86 and SP22 x64), and Git (the sync
  24. folder is a Git repository; Git for Windows includes the Git LFS a team's
  25. project file needs). `cts` and the in-IDE agent are .NET Framework 4.8
  26. programs, which Windows 10 1903 and later include.
  27. Install the tool and its CODESYS menu entry:
  28. ```powershell
  29. irm https://raw.githubusercontent.com/ArthurkaX/cds-text-sync/main/irm/setup.ps1 | iex
  30. ```
  31. > [!IMPORTANT]
  32. > **4.0.** cds-text-sync is now `cts.exe` and an agent inside CODESYS;
  33. > the `Project_*.py` scripts are gone. A 3.x sync folder is not taken over,
  34. > and the last 3.x release, 3.4.1, stays one choice away in the installer's
  35. > menu. [Upgrading to 4.0](docs/upgrade-4.md) lists what changes, what to
  36. > delete and how to go back.
  37. The `cds-text-sync` toolbar button
  38. (<img src="img/cts-button.png" alt="CTS two-arrow button" height="20">) starts the agent and opens the quick
  39. window, just like **Tools > Scripting > Scripts > C > cds-text-sync**. The
  40. installer places its script and icon in CODESYS's sibling **Script Commands**
  41. folder and adds the button to Standard. If CODESYS was open during setup, close
  42. it and run `cts install --toolbar`. For each project,
  43. the important path is:
  44. 1. Open the project in CODESYS and start the agent once each time CODESYS
  45. starts: the toolbar button or **Tools > Scripting > Scripts > C >
  46. cds-text-sync** (or open the project with `cts project open --launch`).
  47. Nothing starts it on its own. Until it runs, Alt+Q does
  48. nothing and `cts` finds no IDE.
  49. 2. Press **Alt+Q**, then `8` Settings and `1` Sync folder. Enter takes the
  50. suggested folder (the clone the `.project` lies in, else `<project>-cts`
  51. beside it), or type your own (`cts set-sync-folder PATH` does the same).
  52. The project keeps only an id; each machine remembers its own folder for it,
  53. so a copy of the `.project` opened anywhere finds it again. That folder becomes a Git
  54. repository root on the spot: `git init` when it has none, ignore rules for
  55. generated files, and a first commit. Later the same row opens a folder
  56. dialog to move it; `8` also changes the key if Alt+Q is taken.
  57. Joining a project someone else set up: get its repository the way your
  58. team shares repositories (`git clone`), open the `.project` you were given
  59. (or the one the repository holds) and press Alt+Q. The window opens on this
  60. row and asks where your clone is; pick it once. A folder of another project
  61. is refused. The `.project` in the repository is the owner's (the machine that
  62. set the project up): only `cts commit --publish` there replaces it, and your
  63. commits carry the `.st` files, never a `.project`.
  64. 3. In the quick window, on a new folder press `2` (IDE -> Disk) to write the
  65. project to `project-view/`. The window shows the branch and what changed on
  66. each side.
  67. 4. Edit `project-view/`, then `1` (Disk -> IDE) carries the edits into the
  68. IDE, `3` compares (the disk or a branch), `5` commits, and `7` opens the
  69. folder in your git program (GitHub Desktop, VS Code, Zed: your choice in
  70. Settings) for merging branches and the history. From a shell the same steps are
  71. `cts export`, `cts import`, `cts compare`, `cts commit` and `cts open`.
  72. <p><img src="img/quick-window.png"
  73. alt="The quick window: branch, sync folder and what changed on each side, then the numbered commands"
  74. width="420"></p>
  75. `cts compare` shows what differs between disk, the IDE and the last sync before
  76. either; `3` in the quick window opens the same difference in your diff program.
  77. An object both sides changed is merged; when the edits overlap, `1` and `2`
  78. open the conflict window first: each such object side by side, the lines that
  79. differ marked, and for each **Disk wins**, **IDE wins** or **Merge by hand...**:
  80. <p><img src="img/conflict-window.png"
  81. alt="The conflict window: FB_Motor changed in the IDE and on disk in the same line, side by side"
  82. width="100%"></p>
  83. The quick window's Settings page covers the sync folder, the program
  84. `7` opens, the quick key, this PC's role and the permissions; the files on disk
  85. have no settings (one `.st` per POU, `.csv` for text lists). See the
  86. [installation guide](docs/install.md) if the entry does not appear under
  87. **Tools > Scripting**.
  88. ## 2. Git workflows
  89. `project-view/` maps one-to-one onto the project: a POU, GVL, DUT or interface
  90. is one `.st` file (methods, properties and actions inside), a text list is a
  91. `.csv`, and devices, tasks, visualizations and other non-ST structure stay
  92. native XML. `cts export` gives you both what Git can review and what CODESYS
  93. can reimport; `cts import` carries a changed, new, renamed or removed file
  94. back object by object.
  95. The configured view root (`project-view/` by default) is the editable, Git
  96. tracked tree; cts keeps its temporary files under `.git/cts/`, outside it. Keep
  97. `project-view/` and `cds-text-sync.json` in commits. The sync base
  98. (`refs/cts/base`) records what disk and IDE last agreed on, so `cts` can tell
  99. which side changed. For a team, work on feature branches and have the project
  100. owner review changes before merging to `main`; [Working as a team](docs/team.md)
  101. walks through the owner's and a colleague's steps.
  102. <p align="center"><img src="img/cts-team.gif"
  103. alt="Two people on one project: the owner exports and publishes it, a colleague clones it, works on a branch and pushes it, the owner reviews and merges it in the git program and carries the merge into CODESYS, the colleague pulls and updates, and a library change travels as a new published project file"
  104. width="100%"></p>
  105. ## 3. I want to find errors in my project
  106. Export the project first, then run the analyzer against its `.st` files. It is
  107. offline: no CODESYS window or PLC connection is required.
  108. ```powershell
  109. cts analyze --workspace C:\path\to\sync-folder
  110. cts analyze --workspace C:\path\to\sync-folder --sarif findings.sarif # CI/code scanning
  111. cts analyze rules
  112. cts analyze explain CTS0007 # for example, indentation
  113. ```
  114. In the IDE, quick window More, `5` Static analysis opens the findings window.
  115. <p><img src="img/analyze-window.png"
  116. alt="The findings window: findings by severity, the marked line and the rule's documentation"
  117. width="100%"></p>
  118. Details: [static analysis](docs/analyze.md).
  119. ### One command for "is this shippable?"
  120. `cts verify` runs every applicable check β€” static analysis, SVG sketch lint,
  121. and (if CODESYS is open) the compiler β€” and returns a single verdict with a
  122. single exit code. The offline stages only read; the compiler stage touches IDE
  123. build state and `--with-test` writes to the PLC, so those two are not read-only.
  124. ```powershell
  125. cts --pretty verify --sync-folder C:\path\to\sync-folder
  126. cts verify --with-test # also run the .test/ plans on the PLC
  127. ```
  128. `cts test` runs ST tests in simulation: a second device in simulation holds a
  129. TestApp whose task tests the shared POUs, counts into a GVL `TestResult` and
  130. logs each test to the runtime's log; every run saves that log as a file
  131. (`cts guide tests`). The production application may stay online meanwhile.
  132. A check that cannot run (no IDE open) is reported as `skipped` and marks the
  133. run incomplete β€” it never turns into a failure. Exit codes: `0` pass, `1` real
  134. problems, `2` could not start, `3` incomplete with `--incomplete error`.
  135. <details>
  136. <summary><strong>β–Ά Click to open: Quick ST formatting inside CODESYS</strong></summary>
  137. When a Structured Text object looks untidy and opening the full Analyzer would
  138. be unnecessary, open the format window: Alt+Q, `0` (More), `1` Format ST, or
  139. quick window More, `1` Format ST. It aligns variable
  140. declarations and repairs structural code indentation in the open IDE objects.
  141. 1. The list shows every Structured Text object of the project, those the
  142. formatter would change marked with their line count; the filter box narrows
  143. it.
  144. 2. The object chosen shows side by side, as the IDE has it and formatted, the
  145. changed lines marked on both sides; **Previous change** / **Next change**
  146. (Shift+F8 / F8) move between them.
  147. 3. **Apply** writes that object and goes on to the next one to fix; **Skip**
  148. goes on without writing; **Reload** (F5) reads the IDE again. An object
  149. edited since the list was read is refused rather than overwritten. Use the
  150. normal CODESYS Undo command to revert an applied change.
  151. The same formatting runs from the shell: `cts fmt` lists what it would change,
  152. `cts fmt NAME --write` applies it.
  153. More details: [Script overview](docs/scripts.md#3-more-page-1-format-st-quick-st-formatting).
  154. </details>
  155. <details>
  156. <summary><strong>β–Ά Click to open: FSM transition map</strong></summary>
  157. If your code is built around state machines and you often have to read one
  158. quickly β€” an unfamiliar `CASE`, or your own from six months ago β€” open the quick
  159. window and choose More, `4` FSM map (Alt+Q, `0`, `4`). The agent's window lists the machines in the project's Structured Text
  160. (unsaved edits included) and draws the one chosen as a GRAFCET diagram:
  161. numbered steps, one bar per transition with its receptivity beside it, and a
  162. step with several ways out fanned out as a divergence. Click a step or a
  163. transition to read the Structured Text behind it. While the IDE is logged in,
  164. **Live** paints the step the PLC is in and the transition that led there, for
  165. the instance you choose. From the shell, `cts fsm`
  166. lists the same machines, `cts fsm --disk` reads them from the exported files.
  167. <p><img src="img/fsm-live.gif"
  168. alt="The FSM window in Live mode: a traffic light function block on a running PLC, the active step and the transition taken lit up"
  169. width="100%"></p>
  170. More details: [Script overview](docs/scripts.md#4-more-page-4-fsm-map-fsm-transition-map)
  171. and `cts fsm --help`.
  172. </details>
  173. ## 4. I want an LLM agent to control the project
  174. Start the agent in CODESYS (the toolbar button or **Tools > Scripting >
  175. Scripts > C > cds-text-sync**). It opens the quick window and exposes the
  176. currently open project to the `cts` CLI. An agent can then export, inspect,
  177. change, compare, import and build without clicking through the IDE:
  178. ```powershell
  179. cts status # check the project, PLC and sync folder
  180. cts set-sync-folder C:\path\to\sync --save # configure it through the agent
  181. cts set-sync-folder --save # or the suggested folder (the clone the .project lies in)
  182. cts export # CODESYS -> project-view/
  183. cts compare # inspect IDE vs disk
  184. cts import # project-view/ -> CODESYS
  185. cts build # build the active application
  186. cts analyze --workspace . # offline check; no IDE required
  187. cts verify # every applicable check, one verdict, one exit code
  188. cts config show # the quick window key and where it comes from
  189. ```
  190. An LLM agent (left) working on the project open in CODESYS (right) through
  191. `cts`: it edits a function block, adds a function, draws an HMI screen, builds,
  192. downloads to the simulation, reads and writes live values, runs the analysis and
  193. commits:
  194. <p><img src="img/agent_demo.gif"
  195. alt="An LLM agent driving the CODESYS IDE through cts: edit, build, visualization, simulation, live values, analysis, commit"
  196. width="100%"></p>
  197. ### Several IDEs at once: point the agent at one project
  198. Each running CODESYS IDE is addressed as `ide-<pid>`. In that IDE, Alt+Q, `0`
  199. (More), then `3` copies a ready line:
  200. ```
  201. !cts --target ide-6128 --expect-project example_lib --help
  202. ```
  203. Paste it into the agent's chat and it learns in one step which IDE and which project it should work with. Every later command carries the same
  204. `--target` and `--expect-project`, so it cannot land in the wrong IDE, and it
  205. refuses to write if someone has switched the IDE to another project. The
  206. `--help` at the end prints the command list and where to start (`status`
  207. with the same two flags shows that IDE's state). This is what lets two agents work on two projects in parallel, for
  208. example an application and the library it uses. With more than one IDE open,
  209. `cts` without `--target` goes to the IDE whose project's sync folder holds the
  210. current folder (or the `--sync-folder` given); when none does, it refuses and
  211. prints the available targets with their sync folders.
  212. A library project has no application to compile. `cts build` checks it, and
  213. `cts build --install` does what the IDE button "Save project and install into
  214. library repository" does, so an agent can develop a library end to end.
  215. The CLI also exposes project-tree operations, PLC interaction, tests and
  216. diagnostics. Run `cts --help`, `cts <command> --help`, and `cts guide` for the
  217. reference matching the installed version.
  218. ### Give an LLM agent the full picture of the project
  219. An agent working on the project blind β€” with no visibility into its own POUs
  220. or the library functions it calls β€” has to guess signatures or grep raw
  221. sources. `cts docs` reads the exported project and the libraries it actually
  222. references, offline, and writes what the agent needs to know without opening
  223. the raw CODESYS sources:
  224. ```powershell
  225. cts docs --workspace C:\path\to\sync
  226. cts docs --libraries "C:\ProgramData\CODESYS"
  227. cts docs --check # 0 fresh, 1 stale, 2 no bundle
  228. ```
  229. Output goes to `.cts-docs/`: `index.md` lists everything; `project/<Name>.md`
  230. is one card per object β€” kind, doc comment, interface, inherited members,
  231. its methods, properties and actions, what it calls, who calls it, the tasks
  232. that run it and the globals it reads and writes; `libraries/<Name>-<Version>-<Vendor>.md`
  233. is one page per referenced library from its installed LibDoc (signature,
  234. description, example, interface). `symbols.jsonl` holds every symbol as one
  235. JSON line and `manifest.json` the counts and the missing LibDoc with the
  236. reason. Only libraries the Library Manager references are documented, and only
  237. in the referenced version. `.cts-docs/` is generated, so export/import/compare
  238. ignore it and the `.gitignore` written when the sync folder is chosen covers
  239. it; `--out` writes elsewhere.
  240. Details: `cts docs --help`.
  241. The same reading draws the project as mermaid, to paste into a document or a
  242. pull request, or as one page to browse:
  243. ```powershell
  244. cts diagram classes FB_Conveyor # what it extends, implements, holds and refers to
  245. cts diagram calls --from MainTask # the task's programs and what they call
  246. cts diagram view # every call, class and state machine drawing in one HTML page
  247. ```
  248. The page opens in the browser and needs no network: pick a task, a class or a
  249. state machine on the left, drag and zoom the drawing, click a node to go to it.
  250. In the IDE, quick window More, `7` Diagrams writes and opens it.
  251. <p><img src="img/diagram-view.gif"
  252. alt="cts diagram view in a browser: the tasks' call tree, a click on a program shows what it calls, a click on a function block opens its class diagram, then a program's instances fitted on screen"
  253. width="100%"></p>
  254. ### Generate visualization screens from SVG
  255. An agent can create an SVG sketch as plain text, lint and preview it, compile it
  256. into a CODESYS visualization, and import the result through the in-IDE agent:
  257. ```powershell
  258. cts visu new --name Line1 --w 1024 --h 600 --out line1.svg
  259. cts visu lint --svg line1.svg --fix
  260. cts visu preview --svg line1.svg
  261. cts visu from-svg --svg line1.svg --create-screen --screen-name Line1 `
  262. --folder "PLC/Plc Logic/Application" --gvl VisuVars # the folder as cts project-tree prints it
  263. cts import
  264. ```
  265. ![Screen drawn as an SVG sketch and imported into the CODESYS IDE](img/visu_example_metal_panel_ide.png)
  266. Details: [HMI screens from SVG](docs/visu.md).
  267. ### Record the plant while commissioning, then let the agent analyse it
  268. The agent picks variables, and the PLC records them in a task's cycle into an
  269. SQLite file of its own (CODESYS' Trend Recording, made from files, no IDE
  270. clicks). Later the agent copies the samples to the PC and asks them with SQL:
  271. ```powershell
  272. cts trend set GVL_IO.rLevel GVL_IO.rFlow PLC_PRG.fbPump.xRun
  273. cts import
  274. cts build
  275. cts download # the first time a full download, then online changes
  276. cts trend on # off after every download; also writable in the IDE
  277. cts trend pull # pauses the recording for a consistent copy
  278. cts trend query "SELECT name, min(value), max(value), avg(value) FROM samples GROUP BY name"
  279. ```
  280. `cts guide trend` explains the slots, the tables and the analysis queries.
  281. For a moment rather than a night, the trace records every cycle into the
  282. PLC's ring buffer, around a trigger, with no download of the application:
  283. ```powershell
  284. cts trace set GVL_IO.rLevel PLC_PRG.fbPump.xRun --trigger PLC_PRG.fbPump.xFault
  285. cts trace start # downloads only the trace; the IDE logged in
  286. cts trace pull --wait 600 # after the trigger: a CSV and what each variable did
  287. cts disconnect # when done: the IDE offline, the application keeps running
  288. cts trace remove # off the PLC and out of the project
  289. ```
  290. `cts guide trace` explains the trigger, the condition and the buffer.
  291. ## Documentation
  292. All of it, with search: [cds-text-sync.pages.dev](https://cds-text-sync.pages.dev/).
  293. - [Installation](docs/install.md)
  294. - [Script overview](docs/scripts.md)
  295. - [Project layout](#2-git-workflows)
  296. - [Working as a team](docs/team.md)
  297. - [CLI and operating guides](products/codesys-agent/src/Cts.Agent.Core/Guides/)
  298. - [Static analysis](docs/analyze.md)
  299. - [HMI screens from SVG](docs/visu.md)
  300. - [Releases and rollback](docs/releases.md)
  301. - [Upgrading to 4.0](docs/upgrade-4.md)
  302. Issues, friction reports and feature requests are welcome in the [GitHub issue
  303. tracker](https://github.com/ArthurkaX/cds-text-sync/issues); questions and ideas
  304. also on [Discord](https://discord.gg/TYJTeW64Kv). Everything posted
  305. there is public: attach no project files or exports. Paste the output of
  306. `cts diag`, run in the sync folder, instead: it holds versions, settings and
  307. file counts, without file, object or project names. In the IDE, the quick
  308. window's More > `6` Report a problem adds this session's cts runs and errors
  309. with the names left out. See the
  310. [changelog](CHANGELOG.md) for release history.
  311. MIT License.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.