Developer teaches Claude Code and Codex to edit Bitrix24 business processes via .bpt

A business process in Bitrix24 outlives the memory of its authors. A request still has to be approved, an owner assigned, a notification sent. But over the years the scheme turns into a tree where blocks are named "Condition" and "Notification", and to change a route you have to recall someone else's intentions. Neural networks have long been parsing repositories, yet here everything is done by hand. The project's author decided to fix this and gave AI agents proper tools.

What the agent gets

A request like "fix the business process" gives the model nothing: it does not know how Bitrix stores a template. A screenshot of the scheme does not help either, since it does not show block properties, expressions and links between actions.

That is why the repository contains a single skill: a file describing the workflow, four reference documents (template structure, expressions, action types, gateway) and Python scripts. They unpack the file, show the tree, search for nodes and check links. An exported .bpt is PHP serialization on top of zlib, not XML or JSON. You cannot simply replace a Russian name in the text: string length is recorded in bytes, and the file would break. Editing goes through the structure: load, change a property, reassemble.

There are two modes. In file mode, the agent works with the export, and importing to the portal remains a separate step; this also suits the cloud if the portal allows export and import. In the second mode, a paid module for the on-premise edition provides a gateway: through the bpagent.py client the agent reads the process, finds the branch and submits an edit. MCP is not used here, and the module has no built-in model.

What the work looks like

First the validator is run on the original template, so that old defects are not later blamed on the agent. Then comes search: by node type, by substring, for example an old domain, and reading a subtree. By default the client does not return a large tree whole if it has more than 150 nodes. A good practice: keep search and replace separate, because the same domain may appear in an email body, in a condition or in executable code.

In practice, the agent found incorrect URLs and problems with assigned employees. The author is candid: there are no precise measurements of time savings, and he has not created a process from scratch this way.

Write safety

A read returns the tree and a version hash. A write requires this hash in the If-Match header, otherwise the server refuses. Before saving, the gateway checks types, permissions and sizes, runs the validator and takes a snapshot. The write goes through the standard CBPWorkflowTemplateLoader::update(), without direct SQL. The access key can be restricted by read, write, create and run permissions, as well as to specific templates. Changing embedded PHP (CodeActivity) requires a separate templates:write_code permission, because it is executable code on the portal's server.

Limitations

The validator checks only structure. An existing reference to an existing constant may be formally correct and wrong in meaning. Writing is closed for NodeWorkflowActivity. Version 0.3.1 has no atomic locking against concurrent saves from the visual editor, so agree on who is editing the process right now. One more point: even when Bitrix is installed on your own server, template contents go to an external agent and fall under the terms of your AI tool. The module is still going through moderation in the 1C-Bitrix Marketplace.

What to do

If you have dozens of accumulated processes, start with file mode on a copy of the export: ask the agent only to find and explain, changing nothing. After approval, check the edit in the designer and run it on a test entity. The general pattern is useful beyond Bitrix: give the agent a format, tools and the order "study, change, verify", rather than just a huge JSON.