First Steps With Zügel

Alexander von Zitzewitz Leave a comment

Setup in 5 Minutes

Zügel consists of a small launcher jar, which you download once from www.hello2morrow.com, and one entry in your agent’s MCP configuration that tells the agent how to start it. With Claude Code or Codex, a plugin takes care of both. There are three ways to set it up, and you can combine the last two:

  • Plugin for Claude Code or Codex: one command installs Zügel for your user, the launcher included. The quickest way if you use one of the two.
  • Project-based: the entry and the launcher live in the repository. Recommended for teams: commit both, and everyone who clones the project gets Zügel without any setup of their own.
  • User-based: the entry lives in your personal agent configuration. Recommended if you work across many repositories: set it up once, and Zügel is available in every session, whichever repository you are in.

Claude Code and Codex plugin

Install the plugin from your shell:

claude plugin install zugel --marketplace hello2morrow/zugel

When you enable it, Claude Code asks for your license: a license file or an activation code. Leave both empty to start a 30-day evaluation. When you have a subscription, just give the agent its activation code: Zügel activates it at once and keeps using it. You can also enter it in /config, which keeps the code out of the conversation. The plugin binds Zügel to the project you start Claude Code in, and it needs Java 21 or newer, like the other setups. Its home is the public repository github.com/hello2morrow/zugel, whose README lists everything the plugin runs, downloads and sends.

In Codex, the same repository is a plugin marketplace:

codex plugin marketplace add hello2morrow/zugel
codex plugin add zugel@hello2morrow

Codex has no plugin settings, so Zügel starts with the 30-day evaluation. When it ends, give the agent your activation code or the path of your license file; Codex asks you to approve before Zügel replaces the license. The plugin also brings a skill that tells Codex when to use Zügel, because Codex does not pass an MCP server’s own instructions to the model. Two things to know. In the first Codex session after installing, and in the first after a new Zügel version appears, the launcher is still downloading Zügel when the agent begins, so that one session has no Zügel; the next one has. And Codex gives every tool call 60 seconds, which a plugin cannot change: the first scan of a large project can take longer, and Codex then reports a timeout. Ask again a minute later; once Zügel has scanned a project, it loads it from its cache in seconds.

The two setups that follow work with every MCP-capable agent, Claude Code and Codex included.

Project-based setup

Put the launcher into a directory named .mcp at the root of your project, and create the agent’s configuration file next to it. For Claude Code that is .mcp.json:

{
  "mcpServers": {
    "zugel": {
      "command": "java",
      "args": [
        "-jar",
        ".mcp/zugel-launcher.jar",
        "<your-activation-code-or-license-file>",
        "--project_root", "."
      ]
    }
  }
}
Read More

Meet Zügel – An MCP Server Giving Your AI Coding Agent An Architectural Conscience

Alexander von Zitzewitz Leave a comment

How Zügel keeps agent-written code inside your intended architecture — and helps you dig out of the debt you already have.

This article covers the version 26.6.1 (released on Sep 30th 2026) of Zügel. This is a living document that gets updated every time new features are added or features are changed.

AI coding agents have changed the economics of writing code. They have not changed the economics of structure. An agent will happily add the fifteenth dependency from your persistence layer back into your UI, import an internal class from a subsystem that was never meant to expose it, or close a dependency cycle that fuses two modules into one inseparable blob — all while the tests stay green. Architecture erosion used to happen at human speed. Now it happens at machine speed. Zügel – the German word for rein – is designed to stop that from happening. It puts you back in control and directs the coding agent to write architecturally and structurally sound code.

The traditional answer — periodic architecture reviews, static-analysis gates in CI — catches the damage after it is written. That is too late for agent workflows: by the time CI complains, the agent has already built three features on top of the illegal dependency.

Zügel moves the check to the moment that matters: before the agent writes the dependency. It is an MCP (Model Context Protocol) server that any MCP-capable agent — Claude Code, or anything else that speaks the protocol — connects to like any other tool provider. Under the hood it:

  • parses your sources itself (Java, Python and C# today with more languages coming soon),
  • maintains architecture rules based on a subset of Sonargraph’s architecture DSL (optional),
  • computes violations and dependency cycles from the resolved model,
  • tracks every change against baselines, so progress and regressions are visible per edit, and
  • answers precise dependency questions the agent would otherwise (badly) approximate with grep.

Zügel is a companion to Sonargraph, and can be used independently from it. Using it together with Sonargraph will still provide extra benefits like CI integration, dependency visualization and a powerful environment to design architecture rules based on the Sonargraph architecture DSL.

Read More

Major Changes to our C/C++ System Model

Alexander von Zitzewitz Leave a comment

When we added C/C++ to Sonargraph our work was heavily influenced by John Lakos famous book “Large Scale C++ Design”. In this book Mr. Lakos presented a solid system to define the architecture of C++ systems based on components. A component in the most simple case is the combination of a header file and a source file, e.g. User.h and User.cpp. The header declares all elements that can be used from outside of the component, while the source file contains the implementation of the functionality. This unites the header and the source file into a logical component, that is better suited for dependency analysis.

Read More

ArcTree Tutorial

Alexander von Zitzewitz Leave a comment

Free Trial and Licensing

ArcTree is a plugin for IntelliJ IDEA that visualizes code dependencies for Java and Kotlin projects in a unique and powerful way. It is a commercial product which needs a subscription to run after a free evaluation period. To test the plugin just download it from the JetBrains marketplace. When it is started the first time it will automatically acquire an evaluation license that allows you to test the plugin for free for a period of two weeks. If you cannot access the Internet from IntelliJ you will need a file-based evaluation license. To do so you must register on www.hello2morrow.com and click on the red “Try Now” button.

If you want to continue using it after that you can buy a subscription (under 100 USD per year) from our website www.hello2morrow.com. Otherwise just uninstall the plugin. The different license options are described in more detail later in this article.

Read More

How to Break a Big Ball of Mud?

Alexander von Zitzewitz Leave a comment

Many non-trivial systems end up as a big ball of mud, not because developers are lazy or reckless, but because it is very hard to avoid that outcome without proper tooling. For example, if your architecture rules are spread by word of mouth or some articles in your company wiki, there is no way of knowing if the code actually conforms to any of your architecture rules. If rules are broken, most of the times developers are not aware of that. That will lead to the erosion of architectural boundaries (if they ever existed) and more and more cyclic dependency groups. In the beginning the cyclic groups start small, but they grow like cancer in your codebase. I actually did some research on that by tracking some open source projects over time. That research confirmed my assumption – if you do not address the problem of ever growing cyclic dependency groups things will only get worse over time, in some cases much worse.

Read More

Spring Modulith & Sonargraph – Better Together

Alexander von Zitzewitz Leave a comment

We created Sonargraph with the vision in mind, that it would allow architects to formally specify an enforceable architectural model. Another goal was to provide exceptional dependency visualization capabilities, so that issues could be easily detected not only in a formal way, but also by just looking at a dependency graph. Sonargraph’s architecture DSL (domain specific language) solved the first problem, while our exploration view solved the second one in a very unique and scalable way. The DSL is quite powerful and easy to learn. For an introduction you could read “How to Organize your Code” on this very site.

But obviously we were not the only ones thinking about a way to formally define architectural rules. Spring Modulith turned out to be a very powerful and successful solution to define domain driven architectures for Spring-Boot applications. Spring Modulith follows a pretty simple hands-off approach that allows the checking of architectural boundaries with a minimum configuration approach.

Read More

Designing a Metric to Detect Big Balls of Mud

Alexander von Zitzewitz Leave a comment

Almost everyone who worked in software development for a while has come in contact with the dreaded big ball of mud (BBoM). If you are not familiar with the term, it describes software systems that have lost their architectural cohesion and suffer from extreme coupling and large cyclic dependency groups. That makes it much harder to do any changes on those systems, because everything is literally connected to everything else. Therefor it requires developers spending almost all their time trying to understand code before they can risk doing changes. And even then, the chance of regression bugs stay pretty high. If a system reaches this state, doing changes becomes so expensive, that rewriting the system from scratch might be cheaper than maintaining the old system. Unfortunately, very often it is not possible to rewrite the system, because the users can’t wait for years for a system replacement. This puts many development organization in a very uncomfortable place.

A big ball of mud visualized by Sonargraph

Read More

Changes to the Sonargraph Dashboard

Alexander von Zitzewitz Leave a comment

The Sonargraph dashboard was designed to give the user a quick overview about several important aspects of software quality. The most important aspects in our opinion are “Architecture” and “Structure”, which are displayed at the top of the dashboard. After some internal discussions we decided that we could improve the metrics in the “Structure” box. Those changes will be rolled out with Sonargraph version 15.2.0, which is expected to be released this week.

Read More