DEV Community: Evgeny Khramov

STL to BREP: A FreeCAD Tool for AI Agents

Evgeny Khramov — Sat, 31 Oct 2026 17:24:49 +0000

I asked an acquaintance who works in CAD professionally what is still missing from working with CAD through an AI agent. The first item on their list was:

Automatic stitching of STL into BREP solids.

I decided to start there. A mesh-to-solid converter already sounds solved, so the interesting part is what "stitched" actually gives you.

A valid solid, and still faceted

An STL file is a triangle mesh. Stitch it into a closed BREP solid and you get something valid, but a round hole can remain a ring of narrow flat faces. Here is the same part, tiltservomount_std.stl (2884 triangles), stitched without surface recognition:

808 faces, every one of them a plane. The solid is valid, but the holes and the lug are made of narrow flat strips, not cylindrical surfaces.

I wanted the tool to recognize planes and cylindrical regions in the mesh and replace them with real analytic BREP surfaces. The result for the same file:

31 faces: 21 Plane and 10 Cylinder. The surface types are read from the BREP itself; the orange color is applied for the figure only. The tool is convert_mesh_to_brep in my open-source fork of FreeCAD MCP, so an AI agent driving FreeCAD can call it.

What was checked, and what was not

I ran six STL files from Pan and Tilt for Standard Servo by micromet (CC BY-SA) through a single tool, with repair=true and default tolerances, without selecting faces or dimensions by hand.

All six results are closed, valid solids, and they survived a save-and-reopen test.
The volume change on every part is under 0.04%.
A residual-faceting scanner found no remaining chains of faces it knows how to recognize.

That is a weaker claim than it sounds, and I want to be specific about why:

All six parts come from one set, and the tool was developed against them.
Close volumes do not prove accurate surfaces. I did not measure the maximum distance between the source mesh and the result.
A closed solid does not mean the cylinders were recovered. That is why the report keeps BREP validity and residual faceting (reconstruction_status) as separate fields.
NURBS surfaces, cones and spheres are not reconstructed, and the tool does not recover the part's modeling history.

Where I need your help

I am not a CAD professional, and six parts is clearly not enough. I would like to find STL files that break this tool: cylinders left faceted, wrongly recognized surfaces, distorted holes, extra geometry, or a mesh it cannot process at all.

If you try it, a problem STL, a screenshot of expected vs. actual, your FreeCAD version and the JSON report help the most. For commercial or confidential models, an anonymized or deliberately simplified example that reproduces the defect is enough. Bugs and ideas go to GitHub Issues.

The full write-up is on my site: the multi-pass pipeline (up to four recognition passes), the per-part results table, a working call example and the report fields: https://hram.github.io/en/articles/freecad-mcp-mesh-to-brep/

I Extended FreeCAD MCP After 1.5 Hours of Assembling Through Chat. Then the Agents Built It Alone

Evgeny Khramov — Wed, 28 Oct 2026 11:13:44 +0000

"No, you rotated them, I asked you to swap them."

That's a message I sent to a coding agent that was supposed to assemble a two-axis pan-tilt mechanism in FreeCAD. A bit later I was telling it which part to rotate, around which axis, by how many degrees, and then along which single coordinate to shift it. The agent executed CAD operations, but I was the one assembling, through a chat. It took 1 hour 37 minutes, and the base was still unassembled.

So I extended the MCP server: hram/freecad-mcp, a fork of neka-nat/freecad-mcp (MIT). Afterwards, Claude and Codex each assembled the same mechanism on their own, in about 15 and 17 minutes. But the geometry checks in the new tools missed a mistake: Codex had swapped the two side plates.

This post covers the tool, the two runs, and what the checks can and can't catch.

The task and the first attempt

I'm building a platform that rotates a phone in two planes, pan and tilt, with two MG996R servos. I'm a software developer, not a CAD user. I used the Pan and Tilt for Standard Servo design by micromet. The archive has five printed parts (base, rotating tray, two different side plates, top platform), a sixth STL for an IR sensor mount, and no CAD assembly or servo models.

On October 26 I gave Codex the archive. A good-looking screenshot wasn't enough to tell whether things were placed correctly: one part ended up inside another, and when I asked it to swap the side plates it rotated them instead. After a few rounds I switched to commanding each step. My messages from the log (originally in Russian):

"no you rotated them and I asked to swap them"

"let's start over. lay out all the parts. I'll tell you step by step what to assemble with what"

From there I chose axes and angles, picked which hole to align with which, forbade touching neighboring parts, limited corrections to a single coordinate, and asked for rollbacks. The 1 hour 37 minutes is time to partial acceptance. It isn't a benchmark, only an illustration of how much human involvement the process needed. What bothered me wasn't that the agent made mistakes; it was that it couldn't reliably detect and fix them without me.

Why "script executed" isn't enough

Take a typical task: bolt a bracket to a base through two holes. With upstream, the agent writes the Python itself: finds the faces, converts coordinates to world space, computes a Placement, applies it. Then it gets this back:

execute_code(<own script: find faces → compute Placement → apply>)
→ "Script executed successfully"
get_view()  → one picture from one angle

If the holes are off by 0.3 mm, you only see it by eye. A single projection doesn't answer whether holes are coaxial, what the gap between planes is, or whether parts intersect. I asked a different agent to assess the toolset and its assessment matched my concern; then I had a coding agent extend the server. That was my judgment call, not a proven root cause of the earlier failures.

What the fork does

The fork keeps all 17 original tools unchanged and adds 14. The mounting task becomes a sequence of ready-made operations:

define_interface(base)          define_interface(bracket)      # which face, which holes
plan_alignment(...)             # a plan; the document is not changed
preview_alignment(plan_id)      # the part in its proposed position, 3 views
apply_alignment(plan_id)        # move in a transaction; roll back if tolerance is violated
check_assembly(plan_id)         # independent re-check
inspect_region(...)             # isometric + top + right in one response

The result is measurements, not "success". Real output from a test scene (FreeCAD 1.1.4, add-on 0.2.1): two 40×24×6 mm blocks with two holes each, bracket initially offset and rotated.

passed: true
max_hole_error_mm: 6.2e-14      hole_axis_angles_deg: [0.0, 0.0]
gap_mm: 3.6e-14                 opposing_faces_error_deg: 0.0
collisions: [{part: "Base", overlap_mm3: 0.0}]
collision_scope: ["Base"]       whole_assembly_checked: false

Values around 1e-14 mm are floating-point noise, so the holes match exactly.

The cycle on that same test scene.

Design details that matter in practice:

Holes are ordered. define_interface takes a contact plane and at least two holes in a given order. The tool doesn't guess which side of a part faces outward or resolve symmetry; the agent has to decide.
Apply is a transaction. apply_alignment moves the part, recomputes, re-measures, and rolls back if hole match, axis angle, contact gap or intersection volume violates the tolerance. It doesn't save the file.
Plans go stale safely. Geometry fingerprints, a document change counter and document identity mean a plan built before the model changed is rejected.
Long operations are jobs. A normal call waits up to 20 seconds, then returns a job_id. With start_assembly_operation, a repeated request_id with the same arguments returns the same job instead of re-running the move. outcome_unknown is reported instead of a false error when the GUI stalls, and cancellation works between safe stages.
Unsaved state is visible. get_document_status reports the GUI modified flag, whether the file exists, and whether a recompute is needed, as separate fields.
Permanent links. create_assembly and create_fixed_joint use FreeCAD's own Fixed/Grounded Joint, with a geometry check after the solver runs.

The new operations need the fork's own add-on (0.2.1); scripts/install_addon.py installs it and keeps a backup of the previous one.

Two agents, no coordinates from me

Claude, 15 min 7 s. On October 27 I asked Claude to assemble the same archive on its own. When it started reading an earlier project of mine, I stopped it: "forget the stand project. do it yourself, don't peek." It had already seen some service information and earlier commit titles, so the run isn't perfectly isolated, but after that I gave no placement hints. It reconstructed the five parts as geometry suitable for face and cylinder analysis, checked volumes against the source models (difference up to 0.04%), added two simplified servo models and a horn, checked body pairs for intersections, saved an FCStd and rendered four views.

One caveat from the logs: Claude did the main layout with its own Python scripts and used the new alignment API on the two side plates only afterwards, to verify and reproduce their position. So this isn't an isolated test of each new command.

Claude's own collage, unretouched. The mechanism looks right, but the green caption inside the image, "all axes aligned to 1e-6 mm, no intersections", is wrong: the measurements are below.

Codex, about 17 min 29 s. I repeated the task in Codex to rule out "it's just a different model". It also finished without step-by-step instructions, this time using define_interface, plan_alignment, preview_alignment, apply_alignment, check_assembly and inspect_region for a number of joints. It created two placeholder servo models, horns, and also included the sixth archive part, the IR sensor mount.

Codex's result, deliberately left uncorrected. The side plates are in each other's places.

What the checks missed

When I looked at the Codex model, the side plates were in the wrong places. Codex had also added four 1 mm spacers that weren't in the original design, while trying to remove intersections near the top. In my assessment the spacers were needed because of the swap: instead of fixing the placement, the agent compensated with extra parts. That causal link is my reading of the result; I did not run an experiment with the spacers removed and the plates swapped back.

Meanwhile its checks showed hole deviation below 5e-14 mm for the joints it had defined, zero angular error, and no volumetric intersections among 91 pairs of bodies in the neutral pose.

There's no contradiction. The tool verified what the agent itself declared correct: the chosen pair of holes, the allowed gap, no intersection at the checked position. It did not verify whether the agent understood which side plate is left and which is right. You can align the wrong parts, the wrong way round, with mathematical precision.

Claude's checks weren't clean either. Its final measurements showed an axis offset of 0.5831 mm, up to 0.25 mm across matched mounts, one hole without a match, and an 84.823 mm³ intersection between the placeholder servo shaft and horn disk. Its final image nevertheless claimed all axes aligned to 1e-6 mm with no intersections. One of its own checks had also first shown zero deviations because, before measuring, it restored the reference positions of the parts; the agent noticed the suspicious zeros and fixed the script. Verification code can be wrong in the same way the thing it verifies can.

Limits of the tool and of my claims

Collision checks are partial. Intersections are checked only between the moving part, the fixed part and the obstacles you list. Every response says whole_assembly_checked: false.
The agent still chooses. Picking the contact faces and the hole order stays with the agent.
Not supported yet: App::Link, moving App::Part containers, and editing arbitrary existing networks of Assembly constraints.
Tested scope. 286 tests pass on the version I examined, and live smoke scenarios cover nested Placements, PartDesign Body, rollback on collision and cancel, preview, and Fixed Joint after save and reopen. That's tested scenarios, not a guarantee for an arbitrary CAD model.
Timings aren't a speed metric. The runs differ in agent, context, geometry representation and set of parts, so I can't say the tools made assembly six times faster.
No physical result yet. The servos were simplified CAD mockups. I haven't shown that real MG996R servos fit without rework or that the mechanism survives a phone's load.
When upstream is enough. If you draw parts, edit objects, run FEM or generate models by script, you don't need the new tools.

What did change is my role. On day 1 I explained how to rotate and where to shift. On day 2 I said what to assemble and reviewed the result. When Codex erred, I didn't re-teach it geometric transformations; I spotted a wrong engineering decision on a finished model. Checking how precisely parts are joined is now automated; checking whether the agent chose the right parts to join is still on me.

Try it

uv sync
uv run freecad-mcp --host 127.0.0.1

You need Python 3.12+, uv, and FreeCAD running with the MCP RPC on port 9875, plus the fork's add-on. Details are in the README: hram/freecad-mcp. The mechanical models and assembly images in this post are based on micromet's design, distributed under Creative Commons Attribution–ShareAlike (the license version wasn't established in my research); the MCP's MIT license doesn't apply to them.

I keep the full case study, with the longer chronology, on my site: https://hram.github.io/en/articles/freecad-mcp/

Don't write the prompt. Get interviewed

Evgeny Khramov — Thu, 22 Oct 2026 06:03:54 +0000

Everyone teaches you to write prompts. In practice, a person looks at a sample a couple of pages long, with a stack, constraints, formats and edge cases, and closes the tab: there's no way I'll write that.

I needed a document camera: an Android phone on a tripod above the desk, a live preview in the PaperLedger browser page and a "Capture" button. Instead of a technical specification I told the agent: interview me, find out the stack, the architecture and the boundaries of the decisions.

An hour later there were 72 messages from me and 71 answers from the agent. Some of the questions were ones I would never have thought of myself: for example, what happens if the portal is open in several tabs at once. There was also a mistake by the agent: it questioned me at length about integration with PaperLedger before looking at its code.

I never wrote the final "prompt". It came together from the answers: the scenario, the boundaries, the contract between the phone and the portal. Then, on the "get started" command, the agent built the app, moved into the Python portal and connected both sides.

If a prompt feels out of reach, don't start with it. Ask the agent to ask you one question at a time and answer as you would. The decisions you would have made anyway end up written down.

The whole interview, without cuts, and what the agent did after it, are in the article: https://hram.github.io/en/articles/mobile-ledger/

My Coding Agent Kept Asking Which Branch to Use. Now It Asks an MCP That Reads Merged MRs

Evgeny Khramov — Sun, 18 Oct 2026 11:15:07 +0000

I used to tell my coding agent something like this:

Update develop/1.65.0. Create feature/<task key> from it. Implement the task. Then make an MR into develop/1.65.0.

Tomorrow the same release could already be in alpha, and a bit later in beta. So I had to know the current stage of every release myself and pass the right branches to the agent every time.

The release stage was the one piece of my release process that lived outside Git, CI and Jira: in people's heads and in a Confluence table I updated by hand. This post is about how I made it computable, first for myself in a portal, then for the agent as an MCP tool, and where the algorithm can be wrong.

Some context. In my Git Flow every release has its own chain of branches, stage/version:

develop/1.65.0 → alpha/1.65.0 → beta/1.65.0 → prod/1.65.0

Several versions live at the same time: one in development, one in testing, one in beta, one in production. Fixes made in an older version must be carried into newer ones. The model is described in part 1, and the CI checks built on top of it in part 2.

Branches don't tell you the stage

The obvious algorithm, "find the latest existing branch", does not work. When a new release is set up, the branches of all its stages are created at once. prod/1.65.0 exists from day one, even if the release has only just started being developed.

A different signal is needed: the action by which, according to our process, a release is moved forward. For us that action is a merged merge request into the branch of the corresponding stage. The target branch is named <stage>/<version>, and the MR is linked to a Jira task. If a matching MR was merged into alpha/1.65.0, the release reached alpha. If such an MR later appeared in beta/1.65.0, it reached beta.

The tool finds merged MRs with a Jira key in the title, branch name or description, matches their target branches against the release and the order of stages, and picks the latest stage that has such evidence:

Release 1.65.0

Branch                Merged MR as evidence?

develop/1.65.0        yes
alpha/1.65.0          yes                ← current stage
beta/1.65.0           no
prod/1.65.0           no

Result: stage = alpha, baseBranch = alpha/1.65.0

This is not a universal property of Git. It is our definition of a release state, and it works because the process was agreed in advance. If your team moves stages in a different way, you need different evidence.

I am stating this definition in hindsight. At first I only wanted to get rid of the table. The formal algorithm and its limits took shape while I was building the tools.

The agent side: an MCP that answers "where do I start?"

I did not want the agent to guess the release state from a local checkout, pick the default branch, or memorise each project's quirks in a prompt. It needed a tool that answers one concrete question: where do I start work on this Jira task, and where do I send the MR afterwards?

That tool is an MCP server I called Delivery Manager. The name can mislead: it does not replace a real delivery manager. A human still plans releases and sets the Fix Version in Jira. The MCP receives a task that is already planned and works out how to handle it within the existing release process.

Given the project, the version and the task key, it queries GitLab, determines the current stage and returns parameters for the work. Schematically:

# Fictional example; a shortened illustration of the contract,
# not the literal JSON response of the MCP.
fixVersion: 1.65.0
currentStage: alpha
baseBranch: alpha/1.65.0
baseBranchExists: true
featureBranch: feature/DEMO-123
mergeRequest:
  targetBranch: alpha/1.65.0

The agent does not need to understand why 1.65.0 is on alpha today. It gets a verified baseBranch and the MR target branch.

The rule I gave the agent is hard: it does not choose the base release branch on its own. The only source is the release MCP. Work does not start by guesswork if:

the task has no Fix Version;
the current stage cannot be determined;
the needed release branch is missing;
GitLab is unavailable;
the task is not in the "To Do" status, so it cannot be considered prepared for implementation.

The last one fired in a quite down-to-earth case: I forgot to move a task to the right status myself, and the work stopped. That is not a tool error. It refused to bypass the process just to start writing code.

Where the algorithm came from: a portal instead of a Confluence table

The algorithm did not start in the MCP. Before that I had a Confluence table: rows are release numbers, columns are stages and operations. When a release moved on, I wrote in the date, removed the green fill from one cell and painted another. Its accuracy depended on me, while GitLab had already recorded every action I was copying by hand.

I am an Android developer and had never written web portals. I discussed the idea in ChatGPT, got an implementation prompt and handed it to a coding agent. That is how my gitlab-panel portal started. It builds the picture from GitLab data: a matrix with versions as rows and stages as columns.

The matrix shows two directions of change flow. Horizontally, changes go through the stages inside one release. Vertically, the portal checks the rule "fixes from an older release must reach the newer one": it compares the branches of neighbouring releases and finds commits present in the older version but absent from the newer one, with merge commits filtered out. That rule used to be just an obligation of the team.

From an arrow in the matrix the portal can also start a "pour", our word for transferring changes between stage branches or between releases. I confirm the source, target and changes; the portal uses an existing Jira task or creates a sub-task, moves it to CodeReview (and stops if that fails), creates a temporary feature/<KEY> from the source branch and an MR into the target. Squash is deliberately off, so the commit history can later be used to check how commits moved between releases. The portal also tries to enable merge after a successful pipeline, but that is not guaranteed; some steps may need attention.

The portal does not decide whether it is time for a release to move to the next stage. A tester reports readiness, a delivery manager plans further progress and creates the pour task. What is automated is the actions after the decision.

Two implementations, no shared library

The portal and Delivery Manager are separate projects with separate codebases. I did not make the MCP depend on a running portal.

When the MCP was needed, I asked the agent working on the portal to explain where exactly in the source the stage-detection algorithm lives: files, methods, logic. I handed that note to another agent, the one building the MCP, and it carried the domain idea over.

So there are now two implementations that rely on one process and on the GitLab history, but there is no automatic code synchronisation between them. Stage order is another compromise: in the MCP it is established from the project's release branches and known stage names, then fixed in the space settings; in the portal there are separate screens for it.

Where it can be wrong

The computation rests on three assumptions:

The stage is the furthest confirmed transition. A merged MR into beta/<version> means the release reached beta. The algorithm does not try to reconstruct business logic from task names.
A release moves only forward. My model has no rollback from beta to alpha, so the latest confirmed stage stays current. If your team can officially roll stages back, this algorithm is not enough.
No confirming MRs means the first existing stage. That is the normal state of a freshly created release: all branches exist, no pour has happened yet. It is a deliberate fallback, not a proven transition.

There are engineering limits too: two implementations mean a rule change has to be ported between them by hand. The stage check did not become part of the old jira:check CI script from part 2; other tools do it now. And I did not measure how many hours this saved, so I will not quote percentages.

What changed is easy to describe without numbers. I used to remember the release stage, update the table, explain branches to a person or an agent and run a sequence of actions in GitLab. Now the state comes from history, the portal shows discrepancies, and the agent asks the MCP instead of asking me.

What I would reuse

Pick the event in Git that counts as evidence of a stage in your process. For me it is a merged MR with a task key into <stage>/<version>. Branch existence is not evidence if branches are created up front.
Decide explicitly what happens when there is no evidence yet and which movements your algorithm does not model, such as rollbacks.
Give the agent a tool that answers "from where and to where", instead of putting branch names in the prompt.
List the stop conditions. If the tool cannot answer with justification, the right action is to stop, not to guess.
Keep the decision to move a stage with people. Automate what follows the decision.

The full case study, including the pour wizard and the two-directions diagram, is on my site: https://hram.github.io/en/articles/hram-git-flow-ai/

Versioned Branch Names Let GitLab CI Enforce My Release Process Instead of Me

Evgeny Khramov — Thu, 15 Oct 2026 18:49:24 +0000

We agreed on the release process three times. I drew diagrams, explained where to merge changes and who decides when a release moves forward. In practice I still had to explain the rules again and again: some people did not understand which branch to pick, others mixed up the order of steps, and others frankly did not want to follow them.

In a presentation I prepared for colleagues later there is a phrase: "I felt like an overseer." That describes that period well.

So I decided: if a rule can be checked by a program, nobody has to stand next to every merge request. This is what that looked like in GitLab CI. The branching model itself, which I have used for more than ten years, is described in part 1: versioned stage/version branches, and release scope decided by planning, not rebuilt by developers with cherry-pick and revert.

The starting point: buttons you have to babysit

The project I joined had plain develop and master. A deploy could be started manually for different environments: from develop you chose dev or stage, from master the same plus prod.

For every release you had to remember which button to press and for which version. Worse, the deploy buttons became active only after version, build and pre-deploy had passed. The code is already merged, and you still have to open the pipeline, wait for the green stages and not forget to press. In effect, sit and refresh the page.

I replaced that with versioned branches:

dev/1.2.1
stage/1.2.1
prod/1.2.1

The stage and the version are now in the name, so the pipeline runs only the actions that belong to that stage.

GitLab has long been able to run jobs by branch name. What changed is that the branch now describes not just where the code lives, but where a specific release is in the process.

The check that replaced my review comments

I used to leave comments in reviews, and the MR stayed blocked until they were fixed. Then I wrote jira:check, a Python script that runs in GitLab CI for every merge request. It checks:

the Jira task key can be extracted from the name of a feature/bugfix branch;
the target branch has a valid stage prefix;
the task is in the required status and has the agreed fields filled in: tech stack, component and Fix Version;
the version in Jira matches the version number of the target branch;
the MR title follows the naming convention.

Errors are collected into a report, and the job fails if anything is wrong. With "pipelines must succeed" enabled, such an MR cannot be merged until the data is fixed. An MR can be created whenever it is convenient; it just cannot be merged.

This is a real log of a failed check (translated from the original Russian output, task key removed):

Checking target git branch: develop/1.66.0
OK
Checking field "Status"
Error: field "Status" must be "CodeReview", current value: "In development"
Checking version match: 1.65.0 -> 1.66.0
Error: the task is marked for version "1.65.0" but the MR targets a branch of another version: "1.66.0"

This only works because the team had agreed on the rules before any script existed: product components, tasks assigned to versions in advance, branch names and the order of MR handling. If the Fix Version is not set, there is nothing to compare. Planning stops being an optional note in a chat and becomes input data for development.

Protected branches

The release branches themselves are protected with GitLab Protected Branches, set by masks (develop/*, alpha/*, beta/*, prod/*), so a new release such as alpha/1.66.0 immediately falls under the right restrictions.

In the project I describe, merging into develop/*, alpha/* and beta/* through a merge request is open to developers and Maintainers; direct push is for Maintainers only. For prod/* both merge and push are left to Maintainers. Force push is disabled everywhere.

I have seen processes where a release was triggered by putting a tag on an arbitrary commit. In the projects I saw, access to such tags was not restricted properly. That is not a flaw of tags as a tool, since GitLab can protect tags too. But in my process the release event is a merge into the protected branch of the right stage, and who may merge is determined by GitLab's role model.

The branch name selects the build and the environment

Since a branch is named <stage>/<version>, GitLab can determine from it what to build and where to send the result. In the Android project the branch selects the build variant (flavor), the API the app works with, and the environment of the internal release service the APK is uploaded to. Nothing is chosen by hand.

The number of stages is a property of the product, not a universal law: the backend project uses develop → test → stage → prod, and another product built for both web and Android uses develop → stage → prod. In every case the stage and the version in the branch name give CI/CD a clear event.

One merge triggers the routine

What usually happens after a merge where the process lives in documentation? Someone builds the right configuration, publishes the build, finds the list of changes, tells the tester, gives them a link, moves the task to QA and assigns it.

I bound these actions to a single event, a successful merge of an MR into a stage branch. After it CI:

builds the right variant of the application or service;
publishes the artifact to the corresponding environment;
forms the list of tasks for the release notes;
sends a notification with a link to the build and the list of changes;
starts the Jira update: moves the task to "Ready for testing" and assigns QA.

The release notes script takes the changes brought in by the merge commit, extracts Jira keys from the commit messages and builds a list of tasks. It is not a universal analyzer of Git history: the result depends on the commit format and on changes reaching the branch through a merge commit. That is why the naming convention matters: the automatic result depends on it.

Notifications used to arrive in Telegram, now it is Mattermost. The tester does not need to ask where to find the build.

This chain is not magic either. In the current configuration jira:update and the notification run with allow_failure: if the Jira operation or sending the message fails, the pipeline may still finish successfully. That has to be watched in the logs and handled separately. I don't want to pass a set of scripts off as a system in which every state is guaranteed to be consistent across all services.

The version has to reach the user

Whenever someone reports "the screen doesn't work" or "the server responds wrongly after the update", my first question is: which version?

In the Android project versionName is built from the release number taken from the branch name: for alpha/1.64.0 it is 1.64.0, and the stage is shown next to it. In the backend project the version is written to a resource at build time and returned in the Version response header. A report then contains a release number and a stage instead of "the latest build".

What I did not hand over to automation

People decide on moving between stages. In my process, releasing from develop to the first distribution stage is my responsibility as development lead. After internal testing, QA decides on the next step. Then delivery joins the decision about production, taking into account the beta test results and metrics. A promotion is formalized as a task and an MR; GitLab performs the permitted operation and its technical consequences.

Some checks CI still does not cover:

it compares the version of the MR, but does not work out whether the release is currently at the right stage;
it does not check the source branch of the feature; the final scope of a change remains a matter for code review;
new secrets and variables of the next environment still have to be prepared by a person: at a transition I check CI variables and Vault. Without that, even a successful deployment can end with a system that does not work.

And no script replaces the manager who has to decide the contents of a release in advance.

What I would reuse

The scripts did not teach everyone to understand the process in the same way, and they certainly did not make managers plan better. What they changed is that formal rules stopped depending on my constant personal checking:

Put the stage and the version in the branch name. Then CI has an unambiguous event instead of a button.
Compare the planned version in the tracker with the target branch in the MR check. It turns planning into input data for development.
Bind routine post-merge actions to the merge event, and mark which of them are allowed to fail.
Protect release branches by mask, so new releases are covered automatically.
Keep the decisions on stage transitions with people, and say so explicitly.

The full case study and supporting artifacts are available on my site: https://hram.github.io/en/articles/hram-git-flow-ci/

GitFlow as cement between planning and development

Evgeny Khramov — Sat, 10 Oct 2026 14:55:20 +0000

"We're not shipping this feature yet. Take it out of the release." "And this one needs to go into the previous version, urgently."

At some point requests like these become routine. You find the commits, run cherry-pick or revert, check the dependencies, work out what you touched by accident, and reassemble the release scope.

The Git commands are not the problem. What bothered me was a different question: why is it the developer who, by default, absorbs the consequences of decisions about release scope and timing? When the release process is loosely organized, that responsibility drifts to whoever knows Git.

For more than ten years, across different projects and companies, I have used my own variant of GitFlow built to prevent that. This is how it works.

The state of a project at any moment

Here is what the branches look like in my model on an ordinary day:

Version   Current stage
1.27.0    develop
1.26.0    develop
1.25.0    alpha
1.24.0    beta
1.23.1    prod

This is not an emergency. It is the pipeline working normally. In real work three or four versions are alive at once: one on beta, the next in internal testing, one more in active development. Sometimes functionality is ready one or two releases ahead.

Each version is its own chain of branches, one branch per stage:

develop/1.25.0 → alpha/1.25.0 → beta/1.25.0 → prod/1.25.0

These are not four shared branches for the whole project. They are four stages of one specific version. The next version has its own chain: develop/1.26.0 → alpha/1.26.0 → …. The stage names depend on the product; test → stage → prod works just as well as alpha → beta → prod.

The rules

Three rules produce this picture.

1. A release is promoted as a whole. Management plans the sequence of releases and their scope; what you call that role (product, release manager, delivery, team lead) matters less than the responsibility not vanishing between job titles. When a release moves from one stage to the next, we carry over its state instead of selecting tasks from a list. Scope can still be discussed and changed, but the normal place for that is planning, not the moment the code is already assembled.

The handoff from development to the first distribution stage is a signature from the development lead: everything planned is implemented, covered by tests, and verified by the team. The safety net for work that did not make it is feature flags. All new functionality is developed behind them, so an unfinished feature can travel to production switched off. There is no need to cut it out with revert.

2. A new version branches off the current stage of the newest version. If the newest version is 1.24.0 and it is on alpha, then develop/1.25.0 starts from alpha/1.24.0. If the newest is 1.65.0 on beta, then develop/1.66.0 starts from beta/1.65.0. You do not wait for prod/1.24.0, and there is no single eternal develop where future releases get mixed together.

3. Fixes move forward. A fix made in an older version must end up in all newer versions that have already branched off from it. Explicitly, through a merge request.

I call the smaller version number "older" and the larger one "newer": 1.24.0 is older than 1.25.0.

Why this is not classic Git Flow

Classic Git Flow (Vincent Driessen's model) has one permanent develop branch. It is the branch of the next release: features are merged into it once it is decided they go into the nearest release, and a release branch is cut from it for stabilization. With one release at a time it works well, and I do not consider it a bad scheme.

The questions start when the plan is longer than one release. There is no room for release N+2. Its features either sit in feature branches waiting for the previous release branch to be cut, or they get merged into the shared develop all mixed together. I have seen both many times. In the first case the branches fall behind and accumulate conflicts. In the second, develop stops reflecting anything definite, and a feature that ends up not shipping has to be reverted. That is not a defect of the model; it is a consequence of having room for exactly one future release.

I do it the other way around. The product already has a delivery plan: which releases, in what order, at what stage. It lives in the tracker (Jira, in my case). I do not invent a separate scheme for Git; I reflect the plan in branches one to one. Each release has its own chain, each stage has its own branch, and the stage on the board determines which branch is current.

Practical consequences:

The next release does not wait. As soon as it appears in the plan it has its own develop/<version>, and developers merge into it right away.
The scope is visible from the branch: develop/1.25.0 contains what was planned for 1.25.0, not everything that happened to get merged.
"What do we revert?" comes up rarely, because scope is defined in advance and unfinished work sits behind a flag.

A mirror does not make the plan better. If the plan is chaotic, the branches show the same chaos. The difference is that it is visible in the branches immediately, instead of hiding in a queue of feature branches waiting for their release.

Scenario: 1.24.0 is in testing, 1.25.0 is already in development

This is a real situation from my project. We had created develop/1.25.0 and were working on new tasks while 1.24.0 was still at alpha. Testers found a bug.

Stopping 1.25.0 until 1.24.0 reaches production is bad. Fixing the defect only in the new version and leaving the old one in an undefined state is also bad.

The bug is fixed where it was found: in alpha/1.24.0, the same stage of the same release. QA keeps checking that release. Development of 1.25.0 does not stop.

In our scenario, once testing of 1.24.0 is complete and it moves to the next stage, we carry the accumulated fixes, via a merge request, into the current-stage branch of 1.25.0. Not one cherry-pick at a time, but by merging the older release's changes into the newer one.

Two different movements of changes happen here and must not be confused. The first is horizontal: 1.24.0 goes through its stages, for example alpha → beta → prod. The second is between versions: changes made in 1.24.0 after the branch-off must end up in 1.25.0.

Note the order: we do not drag every fix into the new version the moment it appears. First the checking of the older release is completed. Other projects may have different checkpoints, but the requirement is the same: fixes must not get lost.

Conflicts do happen in such a merge, but as a rule they are simple. They occur in shared files where different releases each append a line: string resources, the list of feature flags, analytics events. Two new lines, one under the other, simply both stay.

Hotfixes

Where is the line between "fix it at the current stage" and "ship a hotfix"? For us it is beta. Beta is already a rollout to a test group of users, almost a release. A bug found on alpha is fixed right there and the release moves on. A bug found in beta/1.24.0 is a hotfix: the fix goes into a new patch version 1.24.1, which continues from beta.

The same applies to production. If a problem is found in prod/1.62.0 that cannot wait for the next regular release, a patch version 1.62.1 is created from it and goes through its own cycle of checks. After the release, the fix is carried into the newer releases, for example into the current stage of 1.63.*, and further if even newer versions have already branched off.

cherry-pick and revert: the numbers, and what the model costs

Over the last five years, as far as I remember, we used cherry-pick and revert to change a release's scope once or twice. The business really wanted a feature moved into an earlier release, and we went along with it. That figure is from memory, not from a count, but it is the normal difference between a rule and an exception: sometimes a request is worth stepping outside the process.

The problem starts when the exception becomes the way you ship. Once selective transfer is a standard procedure, planning gets a cheap workaround: "let's build everything first and decide what to ship later." As long as there is always a developer with cherry-pick at hand, the process has no reason to change.

Responsibility is split like this:

management defines the scope and sequence of releases;
the development lead is responsible for the version being ready to hand over to distribution;
QA and delivery are responsible for the checks and for the decisions to promote through the stages;
developers implement the tasks, fix defects, and resolve conflicts when changes are carried between versions.

The costs are real. You run several versions in parallel, you must remember to merge fixes from older releases into newer ones, and you have to agree on checkpoints and rare exceptions. In a team where release scope is, as a matter of principle, decided at the last moment and selective delivery of changes is the core business model, this process will be inconvenient.

I am not claiming this is a universal recipe. It is the process I have carried from project to project for more than ten years, and it works for me.

Takeaway

A product has two kinds of work: release planning and development. Different people do them, and both are needed. If there is no reliable joint between them, it gets patched by hand with "take the feature out" requests, cherry-picks and reverts, and the developers pay for it.

The branches here are not an invented scheme but the delivery plan in explicit form. Branch names and merge rules only make the agreement about responsibility visible. It is that agreement the joint rests on.

I keep the full text, with the hero illustration and the complete set of diagrams, on my site: https://hram.github.io/en/articles/hram-git-flow-base/

My OCR Pipeline Asked for 44 GB of RAM to Read Three Invoice Columns. The Fix Wasn't a Better Model.

Evgeny Khramov — Sat, 03 Oct 2026 12:06:49 +0000

The task was narrow. Take a phone photo of an UPD (a standard Russian invoice form), read the VAT rate from column 7, group the rows by rate, sum columns 8 and 9, and check the sums against the document total.

photo → find three columns → read the numbers → group by VAT rate → check the sums

My wife is an accountant and does this by hand, so I started building a tool for it with a coding agent. I assumed OCR would be the hard part. It turned out to be one of the easiest.

The first version: give the whole page to PaddleOCR

My own spec asked for the obvious architecture: OpenCV preprocessing, then PaddleOCR's table recognition as the main path, with classical geometry only as a fallback.

The agent built it: page detection, perspective warp, deskew, CLAHE, then two full-page passes — TableRecognitionPipelineV2 for structure and a separate PaddleOCR(lang="ru") for text.

The first real phone photo, about 5 MB, made PaddleOCR try to allocate roughly 44 GB and the request died with ResourceExhaustedError.

The obvious hypothesis was "the photo is too big", so the agent capped the long side at 2600 px. A large synthetic image now completed — in about 44 seconds, peaking near 10 GB RSS. It looked like a fix.

Then the same class of failure came back on another real document.

The image size was a symptom

From that point the agent ran every experiment under systemd-run with a hard MemoryMax and swap disabled, so a bad hypothesis would kill one process instead of freezing the laptop.

The first reproducible run under a 14 GB limit:

	value
input image	1462×2600
model loading	~85 s
RSS after loading	~1.97 GB
first full-page inference	over 14 GB, process killed

Even the downscaled image didn't fit. The cause was the composition of the pipeline: PaddleOCR(ru) ran its own text detector over the whole page, and TableRecognitionPipelineV2 carried its own models for layout, OCR, and table structure. The page went through several heavy models, with part of the work duplicated.

PaddleOCR wasn't the problem. Feeding it a whole page to get three columns was.

The new scheme:

ORIGINAL → small working copy → classical CV: geometry → coordinates
ORIGINAL → small crops at those coordinates → text recognition model only

Working image for geometry, original for reading. With recognition running only on crops, peak memory in a control run was about 627 MB.

But that only works if the geometry is right. And the standard way of getting it right made things worse.

Aligning by the sheet edge was worse than not aligning at all

The first geometric version did what a document scanner does: find the sheet contour, warp it to a rectangle. But the sheet often didn't fit in the frame, and the paper edge isn't necessarily parallel to the printed table.

Morphology then found zero or one long horizontal line instead of about thirty. Rotating by the angle of the horizontals fixed them and tilted the verticals by about 0.31° — so the distortion was shear or perspective, not rotation. A shear correction helped.

At that point I asked the agent why step two was fixing a tilt that step one should have removed. It proposed moving the tilt measurement into step one — tidier, but the reference object was still the sheet of paper.

Years ago I wrote a Sudoku recognizer, and I told the agent how it worked: look for near-vertical and near-horizontal lines on the uncropped frame within a range of angles, find their intersections, and derive the transform from those.

The useful part wasn't the code, it was the choice of reference. If I need the table's geometry, the table is what should be aligned.

source frame → LSD line segments → horizontal/vertical lines
→ intersections = table nodes → homography (RANSAC) → one warp of the original

A Sudoku grid is regular, so every node's ideal position is known. An invoice has columns and rows of different sizes, so the agent did a rough transform from the outer geometry and refined it over many nodes with outlier rejection. Debugging took several iterations: LSD found both edges of a thick line, and digits in a narrow column produced false segments.

Then all variants were measured with one metric:

Variant	Tilt, horizontals / verticals	Mean node residual
No alignment	0.032° / 0.053°	0.76 px
By sheet contour	0.374° / 0.010°	1.97 px
Contour + shear	0.105° / 0.004°	0.98 px
By table grid	0.010° / 0.002°	0.26 px

Look at the second row. Aligning by the sheet contour was quantitatively worse than doing nothing: the tilt we kept correcting was partly introduced by our own preprocessing. The grid-based method cost about 0.8 s more per page at that stage.

A one-pixel error on the working copy clips a digit on the original

With the grid found on the reduced copy, I scaled the coordinates back and cut cells from the original. Some money values lost their last digit: one pixel on the working copy is several on the original, and morphology widens the table lines further.

The fix was a second coarse-to-fine level. The working-image grid gives an approximate boundary; then, in the original, the algorithm searches a ±10 px window for the actual printed line and crops from there.

The control metric was edge_ink — crops with ink touching the edge. It went from 67 of 84 to 3 of 84, and those three were specks and pen marks, not clipped digits.

The biggest accuracy gain was a crop, not a model

With detection and table recognition gone, one small text recognition model remained. Two findings from comparing inputs:

Binarization helped geometry and hurt recognition. The model read grayscale better.
A strip of several columns scored slightly higher than separate cells at first, but I kept separate cells: one lost comma in a strip breaks the parsing of its neighbors, while a cell keeps its own bbox, crop, and result as evidence.

The remaining errors clustered in double-height rows. There the value occupies a small part of a tall cell, and the model resizes the whole crop to a fixed 48 px height, so the digits shrink.

Adding a tight crop around the connected ink components, on a hand-labeled golden document:

separate cells: 76 → 82 out of 83
strip:          79 → 83 out of 83

Enabling MKL-DNN for the recognition model, on the same tight crops, cut a single call from about 155 to 44 ms for cells and from 366 to 93 ms for the strip.

The tight crop brought its own errors — dots, pen marks, and grid-line remnants stretching the box — and the component rules had to be tightened.

Constrain the decoder by what the field can contain

One error remained: a smudged 10% read as 1Q%. A Q → 0 rule would encode one photo's defect. But I know the field's semantics: a VAT rate is digits, a percent sign, or the text «без НДС» ("no VAT"); a money amount is digits and separators.

The restriction went into CTC decoding as a per-field character whitelist. That gave 83 of 83 on the golden document.

It can't be global. The column-number row contains labels like 1а and 10а, and a numeric whitelist corrupts them.

Perfect characters, a row that never existed

A second form, TORG-12 (another Russian delivery note), arrived rotated and on curved paper.

Orientation: PaddleOCR's classifier on the central crop got 1 of 24 artificial rotations wrong, because the page center held signatures instead of text. Voting over a 3×3 grid of regions, skipping empty ones, gave 24 of 24. Document type came from the already-read column-number row, with UNKNOWN returned when features conflict.

The dangerous problem was structural. Global row detection found 16 rows instead of 18: the curvature merged two pairs of neighbors. Since columns are read independently, the pipeline could take an amount from one physical row and the VAT from the next and emit a record that was never on the paper — with every character read correctly.

The fix was to stop solving the whole page again: search for row boundaries only inside the narrow strip of needed columns, where curvature barely shows. That found all 18 rows, with no mixed values on this document.

Speed: a dictionary beat a heavier model

By now a document took 4.4–4.8 s, 75–80% of it in the recognition network. The agent compared seven recognizers (several PaddleOCR generations and Tesseract) in two modes on two documents.

PP-OCRv6_tiny was fastest, but confused 6 and 8 and broke the column-number row.
en_PP-OCRv3_mobile_rec was about 1.8–2.6× faster than the original model, with one systematic error: the smudged 10% became 19%.

A heavier model was one option. But the set of legal rates is finite: 0%, 5%, 7%, 10%, 20%, 22%, «без НДС». So for this field the decoder computes the CTC probability of each legal entry and picks the most probable. That is more than a character whitelist: the decoder knows the full dictionary of values. On the smudge, 10% wins.

Result with en_PP-OCRv3_mobile_rec as the default: 135 of 135 labeled values on the two-document collection, and 4.84 → 2.81 s on the TORG-12, 6.06 → 3.19 s on the UPD.

That is two documents, not an accuracy claim. And the fastest hybrid, with the tiny model, was rejected because it lost one real value.

What the agent did and what I did

The first full-page pipeline matched my own spec — I asked for it. After the crashes we switched to an experiment log: hypothesis before a change, measurements and artifacts after. The agent ran variants under the memory limit, measured time and RSS, saved crops and overlays, and moved the winners into the main pipeline.

The agent found the real cause of the OOM, after the resize fix failed. I changed the direction where the model of the task had to change: the Sudoku episode replaced the paper edge with the table grid as the reference.

Where this stands

It started as image → OCR → data. It is now:

image → geometry → physical rows and cells → OCR
→ domain constraints → structured data → validation

The neural network sits in the narrowest spot, reading a small fragment that is already located and cropped. Almost none of the big gains came from a bigger model: memory dropped because the network stopped seeing the page, geometry improved because the reference became the table, accuracy improved because the crop got tighter and the decoder learned the field's semantics.

PaperLedger is not a finished product. My wife doesn't use it in her daily work; I run experiments on her real scenarios and show her the results, and real use would need her company's approval because of the data in the documents.

The full case study is on my site: https://hram.github.io/en/articles/paper-ledger/

A Coding Agent Added Jetpack Compose Support to My Android Renderer MCP. I Wouldn't Have Started This Task Myself.

Evgeny Khramov — Fri, 02 Oct 2026 14:36:21 +0000

Android UI Renderer MCP is a local MCP server that lets a coding agent render Android UI without an emulator or a device: it gets back a PNG plus a component tree it can query for bounds, text, and state.

It already handled classic Android UI — XML/View, RecyclerView, Activity + Fragment, overlays, different screen configurations. For XML there's a clear entry point: load the layout resource, apply a fixture, measure, lay out the View hierarchy, draw it, serialize the tree.

XML layout → inflate → fixture with data → measure/layout → PNG + View tree

Jetpack Compose has no equivalent entry point. There's no file to inflate. There's a Kotlin function:

@Composable
fun BookItem(
    book: Book,
    selected: Boolean,
    onClick: () -> Unit
)

Rendering it means understanding its signature, building correct Kotlin values for every parameter (enums, nullable types, data classes, collections, callbacks), resolving the app's theme, and only then calling the composable inside an environment where Compose can actually draw. In a real app, a ViewModel, DI, navigation, and data loading show up right next to it.

That's not "support one more UI format." That's a separate research problem, and it's exactly the kind of problem I usually never got around to starting — not because it's unsolvable, but because the cost of finding out how to approach it could easily exceed the value of the feature itself.

This time I handed that research problem to a coding agent. What follows is what it built, where it broke, and what I had to check before trusting the result.

I rejected the agent's first proposal

The safe option was the obvious one: let every Compose project provide its own renderer entry point — a function that already knows how to build the needed state, wire dependencies, and call the composable, with the MCP just invoking that prepared adapter.

It would have worked. It also would have killed the point of the tool.

The renderer isn't meant to be another test framework bolted onto a project. It's meant to support a loop an agent runs on an existing project with no manual prep:

change UI → render → inspect PNG + structure → fix

If a developer has to hand-write an adapter for every screen first, agent autonomy ends exactly where the real UI begins. So instead of asking "how do we render a composable," I set a constraint on the result:

The MCP must adapt to Kotlin/Compose on its own. The project must not have to write a special renderer entry point.

I didn't know how to implement that. I specified a property the result had to have, and left the research and implementation to the agent.

What `render_compose` does

The MCP got a new tool. Instead of an XML layout, the agent passes the fully qualified name of a top-level composable plus named JSON arguments:

{
  "function": "io.github.example.ComposeBookItem",
  "arguments": {
    "selected": true,
    "book": {
      "title": "Designing Data-Intensive Applications",
      "status": "AVAILABLE"
    }
  },
  "widthPx": 1280,
  "heightPx": 800,
  "densityDpi": 240
}

From there the renderer:

finds the Kotlin file with the target top-level @Composable;
parses the function's parameters;
checks for extra and missing arguments;
builds typed Kotlin values from the JSON;
generates an ordinary Kotlin call to the composable;
substitutes no-op lambdas for missing callbacks;
finds the project-level AppTheme, or uses an explicitly passed wrapper;
creates a temporary Kotlin probe;
runs it via Gradle/Robolectric;
draws the ComposeView to a PNG.

The project's own sources aren't touched — the temporary probe lives in .android-ui-renderer. Nullable values, enums, data classes, mutable properties, List, and Set are all supported, so the agent never has to pre-build a renderForMcp() function inside the app.

To verify this wasn't just working on a toy composable, I asked the agent to clone an open-source Jetpack Compose sample project end to end. The repo now has two equivalent apps, sample/ (XML/View) and sample-compose/ (Compose), sharing the same book library and the same seven scenarios: a book row, a long title at fontScale = 1.3, a list, master-detail, full screen, a loading state, and a Russian dark theme.

Same scenario, two different UI stacks, both captured on a 1920×1200 px canvas at 240 dpi. This isn't a pixel-perfect comparison between XML and Compose — it demonstrates that the renderer reproduces equivalent states on the same canvas through two different mechanisms.

The first PNG worked. The tool's contract still didn't.

The most useful failure showed up almost immediately. On a real Compose component, the agent got back a normal, correct-looking PNG. By screenshot-tool standards, that's "done."

But tree serialization broke right after: one of the Compose semantics nodes had no className, which the renderer's existing protocol expected on every tree node. The image existed; a full MCP response didn't.

For a plain screenshot tool, that's a rounding error. For an agent tool, it isn't — an agent doesn't just look at a PNG, it needs to ask the renderer concrete questions afterward:

where is this element? what are its bounds? what text does it have?
is it clickable? selected? checked? what's inside it?

XML answers that through the View tree. For Compose, the renderer now returns a semantics tree instead — bounds, text, contentDescription, enabled, clickable, selected, checked, and child nodes. The agent added a fallback for semantics nodes without a conventional className, rebuilt the renderer, and reran the same request. Here's a fragment of the resulting view-tree.json, with bounds and state the agent can act on next:

{
  "id": "semantics-33",
  "className": "androidx.compose.ui.semantics.SemanticsNode",
  "clickable": true,
  "bounds": { "left": 650, "top": 500, "right": 799, "bottom": 560 },
  "children": [{
    "id": "semantics-35",
    "text": "Reserve",
    "bounds": { "left": 686, "top": 515, "right": 763, "bottom": 545 }
  }]
}

Only after that fix did the tool's actual contract pass — image and structure, not just a picture an agent has to eyeball.

Then a second failure, unrelated to Compose itself

The renderer temporarily injects test dependencies via a Gradle init script. In the new Compose demo project, this hit a strict repositoriesMode: the project's Gradle settings forbade adding a Robolectric dependency that way.

So the UI rendering already worked, but the reproducible open demo didn't build. The agent changed sample-compose's repositories mode to PREFER_PROJECT and left a comment explaining why the renderer needs to add a temporary test dependency at all. This is a familiar shape in agentic work: "add Compose support" doesn't stop at the Compose API — the agent has to walk the whole path to a reproducible result, including Gradle policy that has nothing to do with Compose semantics.

Timeline: under two hours from constraint to working demo

Per the session log: 12:26, first note of the technical problem. 12:41, I rejected the mandatory project-side entry point. ~13:00, first real Compose render — PNG succeeds, semantics tree serialization fails. Then a second successful run, the Gradle policy fix, tests, and all seven scenarios. 14:05, the main commit lands in main: Compose support, tests, Compose demo. 14:09, a follow-up commit after I flagged that the two comparison images had been captured at different canvas sizes.

From stating the constraint to a fixed, public result: about 1 hour 43 minutes.

I'm not turning that into "a human would take N days." I don't know how long this would've taken me, because the honest answer is I probably wouldn't have started it — I'd have had to separately learn how to call an arbitrary composable programmatically, how Compose compiler transformations affect that, how to get a semantics tree, how to run all of it on Robolectric, and how to avoid turning the project into a pile of special test entry points. All of that is researchable. The cost of that research was the actual stop factor, and that's what changed: not the speed of writing code, but the economics of deciding whether an idea is worth trying.

What the agent did, and what I did

Looking only at the diff, my part looks small. The agent designed and implemented render_compose, built the typed Kotlin call generator, built the Compose probe and semantics tree, added unit tests for enums/data classes/mutable state/callbacks, verified against a real Compose component, created the open sample-compose project with seven reproducible scenarios, and fixed both failures above.

I didn't write that code. What I did do:

rejected the mandatory project-side adapter and set the actual constraint (MCP adapts, project stays a normal project);
required verification against a real, working component instead of a toy composable;
caught the canvas-size mismatch in the XML/Compose comparison after the first "success."

That's a real shift in where my time goes. The old chain was study the unfamiliar area → find an approach → implement → debug → test → demo → verify. The new one is state the required property → set constraints → let the agent run research/implementation/tests/demo/fixes → verify it's actually the result I need. The technical complexity didn't disappear — it's still in the code. I just stopped having to walk the whole research path myself before I even get to decide if the idea is worth it.

Limits, stated plainly

The current implementation is deliberately narrow. The renderer works with a top-level composable, not a production navigation flow — no DI, no real data loading, visual state passed explicitly as arguments. Callbacks are replaced with no-op lambdas, so there's no simulated user interaction. Kotlin signature parsing is a custom regex-based parser, not the Kotlin compiler API, so complex overloads, type aliases, and unusual annotations may need more work. Compose returns a semantics tree, not an Android View tree, so identifiers are synthetic. And I haven't verified pixel-perfect agreement with a physical device — I'm not claiming that.

For the task I actually had, this is enough: take a specific visual state, render real Compose UI, get a PNG plus a machine-readable structure, with no adapter pre-written inside the project.

The actual result for me isn't Compose support

The formal result is simple: the renderer now supports both XML/View and Jetpack Compose, with two equivalent sample apps and side-by-side output.

But the thing worth taking away is the shift in how I size up a feature. I used to ask "how long will it take me to even figure out how to do this?" — and that question quietly killed a lot of useful-but-optional ideas before they started. Increasingly the question I can ask instead is "can I state precisely what the result needs to be, and which constraints actually matter?" I didn't know how to implement Compose rendering, and wouldn't have started researching it on my own. I did know exactly what I wanted from the tool. That was enough for the agent to cover the part I didn't know, including the two failures it had to debug on the way to a working public demo.

I keep the full case study, including the detailed session timeline and the complete set of assets, on my site: https://hram.github.io/en/articles/android-ui-renderer-compose/

My Coding Agent Built a Gas Station Monitor

Evgeny Khramov — Wed, 30 Sep 2026 06:05:15 +0000

At 02:01 one night, Telegram got a message from my personal portal:

🟢 You can go for 95-octane

It pointed to the right station and said there was no line. About an hour later I decided to use it. Home automation logged the car leaving at 03:07 and coming back at 03:30: a 23-minute trip.

The real notification and the two home-automation messages that followed (in Russian).

The useful part isn't that the recommendation happened to be right. It's that until that moment I didn't have to watch anything. Getting there took one wrong turn: the coding agent quickly built a working MVP, and I then realized I had automated the wrong part of the problem.

The problem

A fuel shortage turned filling up into a small operational process. There are a few stations near me worth driving to, I only need 95-octane, and "fuel showed up" means little if there's a line of dozens of cars. Public services already reported availability and lines, but every check still meant: open the service, find my stations, check 95 specifically, look at lines, judge how fresh the data is, compare, decide. Then repeat a while later.

The data existed. What was missing was a personal layer that knew my criteria and did the routine part.

MVP: a few `curl` calls, a problem description, a template

I gave a coding agent (I don't remember which one, and it doesn't matter here):

a description of the problem;
about 5–6 curl examples that made the available API clear;
a requirement to use my existing FastAPI project template.

The agent worked out the data structure, wrote the project documentation, and implemented the MVP: station search, a watchlist, periodic data collection, history, and a screen with the current state of the selected stations.

In git, the first commit with the plan landed on September 12 at 09:24, and the MVP commit at 11:44. That is not "2 hours 20 minutes of human work": git doesn't show how much time a person spent or what happened inside the agent session. It does show how fast a raw input became a working product.

It worked, and answered the wrong question

Technically the MVP did exactly what I had asked: it collected data, showed my stations, gave a current snapshot. Looking at the whole screen, I still had to read several cards and interpret the situation myself. I had automated getting the data, not the part that annoyed me.

The first version answered "What's happening at my gas stations right now?" I needed "Should I go for 95-octane now, or wait?"

I took the working screen to ChatGPT, not as a coding task but as a product review: what decision should the user get on the main screen? One AI had acted as the implementer of the original spec; the second one looked at the result from outside. That review produced the idea of turning the monitor into a decision assistant.

Why one `status` field isn't enough

The naive version:

95-octane available -> go
95-octane not available -> don't go

It fails on real data. The source API has no formal public spec, and different parts of a response can describe the situation with different freshness and semantics. The overall status can say fuel is available while more recent data shows a line of 20–50 cars at the same station.

A decision has to account for:

whether 95-octane specifically is confirmed;
how fresh that confirmation is;
what the line looks like, and how fresh that is;
whether the current state can be trusted at all.

And one rule had to be stated explicitly:

No fresh data does not mean no fuel.

If the system doesn't know, it says UNKNOWN instead of pretending there's no fuel.

From snapshots to a deterministic decision

A normalization layer now sits between the external API and the decision:

API snapshot
    ↓
StationState
    ↓
StateTransition
    ↓
DecisionEngine
    ↓
GO / WAIT / NO_OPTIONS / UNKNOWN

StationState describes the situation in the app's own terms: is my fuel available, what's the line, when was it observed, how fresh is the data. DecisionEngine looks at all watched stations at once:

GO: at least one suitable station has confirmed 95-octane and an acceptable line;
WAIT: fuel is available, but the options don't work for me, e.g. because of the line;
NO_OPTIONS: no watched station has a confirmed suitable option;
UNKNOWN: fresh data isn't enough for an honest decision.

This is a plain deterministic algorithm. There's no LLM at runtime. The answer had to be repeatable, depend on measurable conditions, be easy to diagnose, be explainable through the underlying facts, and behave the same after every restart. AI was used to build the system, review the interface, and design and implement changes; the runtime decision is plain rules.

AI helps build the decision system, but the decision system itself doesn't have to be an AI system.

Decision first, evidence after

The station cards stayed, but became secondary. The main element is the aggregate verdict with an explanation, for example GO followed by "95-octane confirmed: Gazpromneft, Primorskoe Highway 251 — no line."

Top: the decision across all stations. Below: the per-station data it's based on (UI in Russian).

The first version said: here are three cards, figure it out. The second says: you can go now, here's why, and the underlying data is below.

Each station also has a history by day, week or month, with an hour-by-hour timeline: 95 with no line, short line, long line, no 95, no data. There is no ML model predicting when a fuel truck arrives. The history lets a human spot patterns (what part of the day a station tends to get 95, when lines form), so the operational decision goes to the algorithm and the deeper interpretation stays with me.

The hardest part: teaching it to stay quiet

Once DecisionEngine existed, the system started understanding transitions: fuel appeared, the line changed, data recovered, the verdict changed. Every one of them is interesting technically. To the user, most aren't:

fuel appeared
↓
the line is still too long
↓
final verdict = WAIT

A Telegram message about that demands attention and changes nothing about what I do. The rule became:

I don't care about every transition and intermediate status. I only want to know when I can actually go.

Telegram stopped being a log of internal events and became a channel for actionable events only. The pipeline got a third step:

data
  ↓
decision
  ↓
is it worth interrupting the person right now?

The detailed log didn't go away; it moved inside the portal as an audit trail. For every Telegram message you can see the previous state, what changed, what event occurred, whether the overall verdict changed, why the portal decided to notify, and the exact text sent. If it tells me "go" at three in the morning, I can reconstruct afterwards exactly which change made it decide to bother me. With a rule-based system, that full cause-and-effect chain is available.

Who did what

The coding agent got a few curl calls, a problem description and a template, and built the first working service. After that, AI implemented the new state models, the decision engine, transitions, Telegram, history, audit and tests.

The most important changes didn't come from the code. The MVP worked, and only seeing it in a real interface showed it answered the wrong question. Then the working Telegram integration exposed that a correct event system can still be too chatty.

real problem → task for the agent → working MVP
→ human looks at the result → wrong thing was automated
→ external AI review → new product model
→ real-world use → one more simplification

I spent much less time implementing classes and more on: what problem the system actually solves, how to tell the first version isn't enough, which decision can be trusted to an algorithm, what data is sufficient, when the system may interrupt a person, and whether the result is useful in real life. Sometimes a working product is exactly what you need to see that the task should have been framed differently.

A thin personal layer over mass-market data

Existing services aren't bad; they show information to thousands of people with different routes, cars and tolerance for lines. They don't need to know that I care only about 95-octane, only a few stations, won't accept a certain line, and want to be called only when there's a practical reason to go.

someone else's data
+ my context
+ my rules
+ my history
+ my notifications
= a personal decision assistant

A service like this for one person used to look disproportionately expensive in time. With coding agents, that experiment costs something else entirely.

The best quality criterion I found for it isn't the number of screens or endpoints, or whether "AI" appears in the architecture. It's that most of the time the system asks nothing of me, and shows up exactly when there's something for me to do.

The full case study, including the first MVP screen, the station history and the Telegram audit log, is on my site: https://hram.github.io/en/articles/gdebenz/

My Coding Agent Could Render One Android Layout. A Real Screen Needed Activity, Fragment, RecyclerView and Overlays.

Evgeny Khramov — Tue, 29 Sep 2026 20:32:52 +0000

My coding agent could already render a single Android XML layout through Robolectric and get back a PNG plus a View Tree with pixel bounds. Then I pointed it at a real screen from a work app, and one layout stopped being enough.

A real screen is an Activity shell, a Fragment container, a RecyclerView with data, and states like a loading overlay. Launching the production Fragment would drag in DI, navigation, networking and the rest of the app's runtime. I wanted something narrower: a screen real enough for visual checks, without running the app.

This is how android-ui-renderer-mcp got composed-screen rendering.

The work screen can't be shown, so every image here is a render of an open demo app in the same repository (sample/). It has the same structure — Activity with a toolbar, Fragment, RecyclerView, master-detail, loading overlay — and each image can be reproduced from the request stored next to it.

The boundary: real resources, explicit state

Activity XML          — real
Fragment XML          — real
item layout           — real
drawable              — real

Fragment runtime      — not run
DI                    — not run
navigation            — not run
network               — not run
data                  — set explicitly

That is the main design decision: the renderer uses the app's real UI resources, but takes runtime state from a deterministic request. Otherwise it becomes one more way to run the app, only harder than an emulator.

Activity + Fragment as one render target

A new render_target tool supports one target kind, activity_fragment. It inflates the Activity XML, finds the container, inflates the Fragment XML separately and inserts it. The production Fragment class never starts.

{
  "target": {
    "kind": "activity_fragment",
    "activityLayout": "activity_main",
    "containerId": "fragmentContainer",
    "fragmentLayout": "fragment_library"
  },
  "widthPx": 1920,
  "heightPx": 1200,
  "densityDpi": 240,
  "orientation": "landscape"
}

The toolbar title and menu icons come from XML (app:title, app:menu); no Activity code ran. The details on the right are an <include>, filled from the request.

I'm not emulating the Fragment lifecycle. I need its visual result from real resources, because the agent changes XML and has to see what ends up on screen.

Deterministic RecyclerView rows

An empty RecyclerView says little about the real UI, and running the production adapter would pull real data back in. So list data became part of the request: the real itemLayout, the orientation, the rows, and a fixture per row. The renderer creates a temporary adapter and inflates the real item XML for each row.

One row from the request above, the selected book:

{
  "@id/title": { "text": "Designing Data-Intensive Applications" },
  "@id/cover": { "image": { "type": "drawable_resource", "value": "@drawable/cover_green" } },
  "@id/statusBadge": { "text": "On loan", "backgroundDrawable": "@drawable/bg_badge_on_loan", "textColor": "#8A4B08" },
  "@id/root": { "selected": true, "backgroundDrawable": "@drawable/bg_book_row_selected" }
}

The UI structure is real; the data is test data and fully controlled. The renderer doesn't guess values from tools:*. If the agent wants three rows, it describes three rows.

Frozen spinners for loading overlays

A loading overlay above Activity + Fragment is just another XML layout with its own fixture. The catch is the indeterminate ProgressBar: it animates, so two screenshots in a row can differ. For automated visual checks that's needless nondeterminism, so the renderer freezes it into a static ring before drawing.

This doesn't prove the animation works. It proves the indicator exists, sits in the right place and has the expected geometry, which is the level of realism this task needs.

Render on the real device's area

For the work screen I also pinned down the real tablet profile: 1280×800 screen, 1280×728 app area (72 px at the bottom taken by system navigation), densityDpi 240, fontScale 1.0, ru-RU, day mode, landscape. For a screenshot that's a detail; for comparing bounds it isn't. The agent has to measure in the same area the real screen has.

A render you can't replay isn't an experiment

At some point I opened a saved render and realized its PNG and View Tree were there, but the call that produced them wasn't: which tool, which arguments, which project root, module, variant and Gradle test task. A reproducible renderer with a non-reproducible run history.

Every sidecar run now also saves request.json (the normalized request) and replay.json (the recipe). For the overlay screen above, shortened:

{
  "format": "android-ui-renderer-mcp/replay/v1",
  "tool": "render_target",
  "arguments": {
    "target": { "kind": "activity_fragment", "activityLayout": "activity_main", "containerId": "fragmentContainer", "fragmentLayout": "fragment_library" },
    "widthPx": 1920, "heightPx": 1200, "densityDpi": 240, "orientation": "landscape",
    "overlays": [{ "layout": "view_loading_overlay", "fixture": { "@id/loadingRoot": { "visibility": "visible" } } }]
  },
  "project": { "root": "sample", "module": ":app", "variant": "debug", "testTask": ":app:testDebugUnitTest" }
}

A render session is now a small experiment you can repeat on the same project revision and renderer version.

What the open demo caught that the work project didn't

I built the demo later, only to have images I could publish. It found real issues.

The renderer silently required JUnit. The first demo render failed:

error: package org.junit does not exist

The probe is a JUnit 4 test, but the init script added only Robolectric. The work project had JUnit in its test dependencies, like any project from the default Android Studio template, so this never showed up. Now JUnit 4.13.2 is added for the render run only if the project doesn't declare it; a project on JUnit 4.12 stays on 4.12, checked against the test classpath.

A night-mode contrast bug in the demo itself. An outlined button was almost invisible because the theme's primary color matched the dark toolbar. The nightMode: true render showed it; reading the XML didn't.

Byte-identical re-renders. Re-running all seven demo scenarios on the same machine produced PNGs identical to the saved ones. With replay.json, a replay gives the same image, not a similar one.

The View Tree sees what the PNG hides. A long title at fontScale: 1.3:

"textLayout": { "textSizePx": 40.0, "maxLines": 1, "lineCount": 1, "ellipsisCount": 81, "truncated": true }

The bounds didn't change and the image looks fine, but 81 characters became an ellipsis. Also, 16sp at fontScale: 1.3 is 40 px, not 41.6: since Android 14, large text scales non-linearly.

Who did what

I have a detailed worklog for this iteration.

Me: picked the real screen as a testing ground and made the work app read-only; asked for RecyclerView support; supplied a mockup as the source of test data and the real tablet profile; stopped the agent before the overlay/dialog changes and asked for analysis first; chose a separate render_target over overloading render_layout; noticed that renders couldn't be replayed; checked the composed render with the overlay myself before allowing the commit. For the demo, I defined the screens and asked for JUnit to be added only when missing.

The coding agent: studied the real screen's XML and the renderer's limits, proposed the deterministic RecyclerView adapter, implemented list and drawable-state support, the composed target, overlays and the replay recipe, ran checks on an isolated copy of the work project without changing it, and wrote the demo app, its render requests and the JUnit fix.

I didn't type most of the code. I decided which part of reality the tool should model and what it must not do.

Limits

Only activity_fragment: one container, one fragment layout. Master-detail in the demo is a single fragment layout, not two fragments.
RecyclerView gets only explicit local rows. Pagination, async loading and real data sources are not modeled.
A frozen spinner checks presence and geometry, not animation.
Robolectric is not a device.

Takeaway

Each step of this project came down to one question: which part of the real app must stay real, and which can be replaced with a deterministic model? My current answer: resources and geometry stay real; data and runtime state are explicit and controlled; and every render leaves enough behind to be repeated.

The renderer and the demo are open source: hram/android-ui-renderer-mcp. The full case study is on my site: https://hram.github.io/en/articles/android-ui-renderer-composed-screens/

I Asked AI to Improve My Resume. It Started Asking Me for Numbers Instead.

Evgeny Khramov — Tue, 29 Sep 2026 20:23:35 +0000

The usual AI resume flow looks like this:

old CV + job posting → LLM → improved CV

It has a basic flaw. My old CV was already a heavily trimmed version of my professional history. If I didn't think something was important and didn't write it down for ten years, the model doesn't know about it either. It can only rephrase what's already there.

I hit this while preparing for a job search. Over the last six months the way I develop software changed a lot: more and more of the mechanical work (reading a codebase, writing code, fixing, refactoring, part of the analysis) goes to AI agents. Formally I'm still a developer and tech lead, but "Android Tech Lead" describes less and less of what I actually do. So the real question wasn't how to phrase my resume. It was what job should I even be looking for next?

So I flipped the flow:

facts and context first → then AI → and only then a resume

The result is Career Portal, a private knowledge base about my own professional life. The resume turned out to be the last step.

Store the context the fact was true in

The portal keeps a profile, jobs, projects, skills and notes, and context is split by level:

Profile: who I am and what I want.
Job: what role I held during that period.
Project: what I did there, with what stack, in what role, with what result.

This looks excessive until you describe several years at one company. At one employer I might have an Android project where I own the mobile app and the team, a Kotlin/Ktor BFF where I'm a backend developer and architect, and elsewhere KMP, internal tooling, CI/CD or platform work. Dump all of that into one "Work experience" field and the model mixes contexts: technology from one project lands next to an achievement from another, and a Tech Lead role spreads onto work where I was a regular developer.

The principle: it's not enough to save a fact; you need to save the context in which it was true.

There's also a private free-form "About me" field. Things like "I don't want this role anymore" or "I managed people here but don't remember the exact team size" aren't resume material yet, but they are context for the AI later. And I don't want every intermediate edit to a public CV to read as "he's job hunting again."

The most useful AI output wasn't text

After filling in the profile you can run a review. I expected the usual advice: trim, reorder, make wording stronger. Instead the agent started asking questions.

I wrote that I managed Android teams. It asked: exactly how many people? I wrote about working fully remote. It asked whether I'd consider hybrid in St. Petersburg. I listed several career directions. It asked which is a current goal and which is just an option.

At the job level it gets more uncomfortable, in a good way:

The job review (UI in Russian). Left: questions and weak spots, such as "you wrote 'sped up development several times', is there a number?" and "the Team field is empty". Right: recommendations and strengths, such as the crash-free 60% → 99.8% metric.

"Significantly sped up development" → by how much? Did the release cycle go from six weeks to two? One release a month to four?
"Reduced incident response time" → from what value to what value?
"Moved development from a contractor to in-house" → team size, project scale, and what changed in timelines, cost or speed?

At the project level, one of my facts already had a clear before → after: crash-free rate went from roughly 60% to 99.8%. There was almost nothing to improve. Right next to it sat "significantly sped up development", which is clear to me because I remember the context and nearly empty to anyone reading the resume for the first time.

I always assumed metrics were mainly a manager's territory. It turned out I need them just as much to explain my own work: team size, devices in production, number of stores, releases, cycle time, error rate, operation volume. Not everything is money, but "I improved the process" and "before → after" are very different claims.

The most useful thing the AI did wasn't writing about me. It asked about the things I didn't think to write down.

Then: what can this experience even be called?

My problem wasn't phrasing Head of Mobile nicely. I wasn't sure I should be looking for Head of Mobile at all. I didn't want to pick a title and stretch a biography over it; I wanted to collect what I actually did first and see which roles follow.

The "Suggest a role" feature looks at the profile, experience, projects, stack and results, and proposes positioning options with reasons:

Role suggestions (UI in Russian). Each role gets a fit label, what to emphasize, and why it fits, citing facts from the profile.

My options included Head of Mobile, Mobile Engineering Manager, and later Lead Android Architect, Mobile Platform Lead and a few others. The AI doesn't decide who I should be. It proposes a hypothesis with arguments from my own history; I accept, edit or ignore it.

A saved role becomes a separate view of the same fact base. These aren't three versions of me, just different selections of real facts:

Head of Mobile: team management, hiring, moving development in-house, engineering standards, release processes.
Lead Android Architect: Android/Kotlin, architectural decisions, stability, modernization, hands-on work.
Mobile Platform Lead: CI/CD, platform mechanisms, feature toggles, KMP, internal infrastructure.

With one fact base and a model that isn't allowed to invent achievements, this is choosing which part of a real history is relevant, not bending a biography to a job posting.

Resume generation comes last, and publishing stays manual

After choosing a role, the portal can help search for postings in that direction and assemble a resume for the role, or narrower, for a specific posting. I deliberately avoided building it around "Am I an 82% match?". The question I want answered is: what from my actual experience needs to be shown for this resume to answer this posting's requirements? The posting becomes context for selecting facts, not a verdict on the candidate.

The result is saved as a separate resume, in the UI and as files, and the last step is manual: I decide what gets published. For career data I don't want an agent that invents a role, writes a document and sends it out with no human in between.

It isn't a programmer-only problem

Later I made the portal multi-user and loaded my wife's resume. She's an accountant. The same pattern repeated:

How many legal entities were you handling?
How many invoices did you issue per month on average?
How many material write-off transactions?
What was the monthly volume?

The mechanism has nothing to do with Android or Kotlin. A person writes "I worked on X"; the AI answers "what was the scale of X, and what backs that up?"; the person goes back to their real history and fills it in.

Stack and authorship

FastAPI, Jinja2 and SQLite; no heavy SPA.
The database holds a profile, jobs with nested projects, skills, education, notes, roles, generated resumes and job-posting data.
PDF/DOCX import: text is parsed, a preview is built, and data lands in the database only after confirmation. Replacing an already filled profile needs separate confirmation.
AI providers: Claude CLI, Codex CLI, and an OpenAI-compatible provider. Job board integration came after the first MVP.

The project kept its genesis trail. The master plan spelled out the roles: Claude in chat is the architect, Claude Code is the executor, I'm the owner. An agent wrote every line of the portal's code. I didn't write a single line, and I didn't read one either. My part was the task, the roles, the specs, and the decisions about what the product should be.

The honest result: almost nobody writes to me

I'm using the portal for a real job search. The resume is much more detailed and evidence-backed, I found plenty of gaps in my own history, added metrics, and looked at roles differently.

But there are almost no calls or messages, and I don't know why. It could be the market, my positioning, the resume itself, or I'm optimizing the wrong part of the process. One uncomfortable hypothesis: iterating on a resume with AI for a long time can land you in a local maximum, where the document gets more logical to you and the model without working better in actual hiring. I don't have data to state that as a fact.

So I don't claim the portal solved my job search. It solved a different problem: my professional history is stored separately from its publications, claims were turned into evidence, I saw several possible roles, and I can build different resumes from one fact base. Whether they work is up to the market.

Takeaway

A resume is a temporary snapshot of a career, not its storage. What matters comes earlier: facts, context, projects, real roles, scale, numbers, preferences and constraints.

If that base is weak, AI rewrites weak material nicely. If it's good, AI can find a gap, ask an uncomfortable question, suggest an unexpected positioning, and assemble different documents from the same history. What I don't hand over: deciding who I should be, inventing achievements, deciding whether to apply, and publishing the final version.

I wanted AI to write about me better. First I needed to know and prove my own professional history much better myself.

The full case study, with more screenshots of the portal, is on my site: https://hram.github.io/en/articles/career-portal/

My AI Running Coach Didn't Need a Better Prompt. It Needed My Training History.

Evgeny Khramov — Tue, 29 Sep 2026 04:42:00 +0000

After every run I used to open the Mi Fitness app, take a few screenshots, and upload them to ChatGPT for analysis. On paper, that was a personal coach: the watch collects the data, I show it to AI, AI tells me what to do next.

In practice it fell apart quickly, and not because of the prompt.

A single workout doesn't fit on one screenshot: summary, charts, heart rate zones and other metrics all live on separate screens. Charts were the worst: a human can stitch several screens into one picture, but for the chat I was rebuilding the context from fragments every time.

The bigger problem: one workout means almost nothing without the previous ones. A heart rate of 168 is just a number. It is a different story if at roughly the same distance it was 158, then 164, 167, 168, 170 and 172. Useful advice needs a trend, and through screenshots I was bringing AI a small fragment of what the watch app already knew.

So the problem wasn't finding a better prompt. I needed a real channel between the watch data and the model.

What the model gets now

This is a shortened fragment of a real coach prompt that the portal assembles after a run:

=== RUN ===
Distance: 3.216 km
Heart rate: 168 bpm
Pace: 6:04/km
Cadence: 162 spm
Load: 127
Recovery: 57 h
Heart rate zones: ... extreme 96%

=== RECENT RUNS ===
09/14: 3.271 km, HR 172, load 142
09/12: 3.307 km, HR 170, load 139
09/10: 3.216 km, HR 168, load 127
...

=== RESPONSE ===
1. Assessment of the run.
2. Risks given the current state.
3. One specific recommendation for the next workout.

The real request contains more: the current run, the history of recent workouts, and stored context about my state. I can edit the template itself from the portal's UI.

That is the whole difference from screenshots. Before, I showed AI a picture of the data. Now the code gathers the facts and builds the context, I set the rules and the response format, and the model interprets the context.

The data layer: running-portal

running-portal syncs my running workouts from Mi Fitness, stores the history, and loads detailed data for a specific run. For me it is an ordinary training log. For the model it is a persistent source of context.

Mi Fitness
    ↓
sync
    ↓
running-portal
    ├── run history
    ├── detailed metrics
    ├── charts
    ├── state / how I feel
    └── monthly goal
            ↓
        AI coach

I did not reverse-engineer the private Mi Fitness API. The sync module is based on Mi-Fitness-Sync by kevinkwee (MIT License), which already implemented Xiaomi authorization, fetching workouts, and parsing detailed Mi Fitness data. A coding agent wrote running-portal and integrated that code; credit for the protocol work goes to the author of Mi-Fitness-Sync.

The integration is not pleasant: a private API and internal data formats, including separate files with detailed value series. That is one reason I treat the portal as a personal tool, not the basis for a public service.

The workout card shows me the same things that go to the model in structured form: heart rate, pace, cadence, stride length, load, recovery, heart rate zone distribution, and detailed time series.

To me, charts. To the model, raw numbers.

What the coach does with it

The analysis shows up on the same workout card.

Assessment → risks → one specific next session.

In this example the coach looks beyond average heart rate: most of the run happened in a high heart rate zone, it compares that with previous runs, and it suggests not increasing the load. I set a rigid response structure on purpose. I don't need sports motivation; I need an assessment, the risks, and the next workout.

This is where I stopped thinking of the prompt as magic text. The usefulness came from the context.

Guardrails in code, explanation from the LLM

The portal also answers a shorter daily question: run today, run easy, or rest?

At the time of this screenshot, less than the estimated recovery time had passed since the last run.

Here I don't hand the decision fully to the model. The prompt has explicit rules: for example, if the estimated recovery time after the previous workout hasn't passed yet, that is a signal in favor of rest. High heart rate, load, and saved notes about my state are factored in separately. The portal fills in the facts automatically:

last run
+ how much time has passed
+ last 7 runs
+ load
+ recovery
+ saved context

Then the model writes a short explanation. Part of the guardrails is explicit, and the LLM is used where several factors need to be connected and explained in plain language.

Why long-term context mattered

While getting back into regular running, I had problems with my feet, and later my knee bothered me for a long time. This is not a medical success story: AI didn't cure anything and didn't replace a doctor.

It was useful as a check on my own tendency to increase load too fast. When pain showed up in the context, the coach lowered the recommended load, suggested a pause, and advised seeing a doctor. After I bought new 361 KAIROS 2 shoes, the shoe change went into the context too, as one more factor against sharply increasing volume. With the knee, the portal kept the note in context and the model kept factoring it into later recommendations.

A one-off chat easily forgets what happened two weeks ago. The portal doesn't.

Arithmetic where arithmetic is enough

Later the task changed from "don't force it" to "what volume should I aim for next month?". At the start of the month, AI analyzes previous runs and proposes three goal options: conservative, recommended, and ambitious. I choose.

The model proposes scenarios and explains the recommended one; the final decision is mine.

Once a goal is accepted, AI is barely needed. Plain portal code counts kilometers run, number of workouts, remaining distance, and whether the month is on track. Where arithmetic is enough, there should be arithmetic; the LLM shows up where history needs to be interpreted.

Who wrote the portal

running-portal is 100% implemented by coding agents from my specs, except for the Mi Fitness integration foundation mentioned above. It wasn't generated once from one big prompt. The loop was:

use the portal
      ↓
see what's missing
      ↓
formulate the task for the coding agent
      ↓
get the change
      ↓
use the portal again

The repository keeps 11 prompt artifacts from different stages: sync, frontend, the AI coach, charts, analytics, monthly goals and other improvements. I can't reconstruct every agent session behind them anymore, so I don't treat the number of files as a precise development log.

Limitations

A personal portal for a single user.
Depends on Mi Fitness's private mechanisms, which can change.
Simple FastAPI and SQLite architecture; some background work runs inside the app process.
Not a product I'm ready to hand to thousands of users.
The AI coach is not a medical system. I treat its recommendations as feedback about training load, not diagnosis or treatment.

Takeaway

When I started sending screenshots to ChatGPT, I thought the task was learning to ask the right way. A good question turned out to be the smallest part of the system.

The watch already collected the data, and the LLM could already reason about it. What was missing was a layer that stores the training history, surfaces the right details, adds up-to-date context, and hands it to the model in a predictable form. Close to a year after getting back into running, every workout lands in the portal, and AI works with my running history instead of a few pictures I show it after each run.

The source is on GitHub: hram/running-portal. Suggestions and bug reports are welcome. The full case study, with more screenshots, is on my site: https://hram.github.io/en/articles/running-portal/

DEV Community: Evgeny Khramov

STL to BREP: A FreeCAD Tool for AI Agents

A valid solid, and still faceted

What was checked, and what was not

Where I need your help

I Extended FreeCAD MCP After 1.5 Hours of Assembling Through Chat. Then the Agents Built It Alone

The task and the first attempt

Why "script executed" isn't enough

What the fork does

Two agents, no coordinates from me

What the checks missed

Limits of the tool and of my claims

Try it

Don't write the prompt. Get interviewed

My Coding Agent Kept Asking Which Branch to Use. Now It Asks an MCP That Reads Merged MRs

Branches don't tell you the stage

The agent side: an MCP that answers "where do I start?"

Where the algorithm came from: a portal instead of a Confluence table

Two implementations, no shared library

Where it can be wrong

What I would reuse

Versioned Branch Names Let GitLab CI Enforce My Release Process Instead of Me

The starting point: buttons you have to babysit

The check that replaced my review comments

Protected branches

The branch name selects the build and the environment

One merge triggers the routine

The version has to reach the user

What I did not hand over to automation

What I would reuse

GitFlow as cement between planning and development

The state of a project at any moment

The rules

Why this is not classic Git Flow

Scenario: 1.24.0 is in testing, 1.25.0 is already in development

Hotfixes

cherry-pick and revert: the numbers, and what the model costs

Takeaway

My OCR Pipeline Asked for 44 GB of RAM to Read Three Invoice Columns. The Fix Wasn't a Better Model.

The first version: give the whole page to PaddleOCR

The image size was a symptom

Aligning by the sheet edge was worse than not aligning at all

A one-pixel error on the working copy clips a digit on the original

The biggest accuracy gain was a crop, not a model

Constrain the decoder by what the field can contain

Perfect characters, a row that never existed

Speed: a dictionary beat a heavier model

What the agent did and what I did

Where this stands

A Coding Agent Added Jetpack Compose Support to My Android Renderer MCP. I Wouldn't Have Started This Task Myself.

I rejected the agent's first proposal

What render_compose does

The first PNG worked. The tool's contract still didn't.

Then a second failure, unrelated to Compose itself

Timeline: under two hours from constraint to working demo

What the agent did, and what I did

Limits, stated plainly

The actual result for me isn't Compose support

My Coding Agent Built a Gas Station Monitor

The problem

MVP: a few curl calls, a problem description, a template

It worked, and answered the wrong question

Why one status field isn't enough

From snapshots to a deterministic decision

Decision first, evidence after

The hardest part: teaching it to stay quiet

Who did what

A thin personal layer over mass-market data

My Coding Agent Could Render One Android Layout. A Real Screen Needed Activity, Fragment, RecyclerView and Overlays.

The boundary: real resources, explicit state

Activity + Fragment as one render target

Deterministic RecyclerView rows

Frozen spinners for loading overlays

Render on the real device's area

A render you can't replay isn't an experiment

What the open demo caught that the work project didn't

Who did what

Limits

Takeaway

I Asked AI to Improve My Resume. It Started Asking Me for Numbers Instead.

What `render_compose` does

MVP: a few `curl` calls, a problem description, a template

Why one `status` field isn't enough