Skip to main content

Blog / Build in Public

I asked whether ArchByte still worked. Mostly it did, and that was the problem.

Abhimanyu Selvan8 min read

ArchByte reads a codebase with AI agents and draws its architecture as an interactive diagram: the services and apps it is made of, what talks to what, the databases and outside services underneath, and the main request flows. You install one binary, run archbyte run in a project, and a diagram opens in your browser.

I wrote two posts about it in February: one on building a playground after a reader said "install + account was a bit much", and a case study of a single open-source project. This post replaces both. Nine months later I wanted an honest answer to a plain question. If a stranger installed ArchByte today, would it work?

The short version

It worked, mostly. That turned out to be the problem. "Mostly works" hides things a new user hits in the first five minutes. I tested it the way a stranger would, on four real repositories, and found:

  • Old models. The defaults pointed at models that had been replaced, and Google is retiring Gemini 2.5 on 1 December.
  • A promised feature that did not exist. The docs said ArchByte works with Codex on your machine. It did not.
  • Ten silent minutes per scan. Six "review" agents ran one after another on every scan. On ArchByte's own code, the diagram was ready after 53 seconds and the command finished after 7.5 minutes.
  • Too much trust. ArchByte ran Claude Code with every permission switched on. The agents only need to read code, but they could have edited files or run commands.
  • Buttons that could not work. The Workflows panel called a command I had deleted in May.
  • Bugs at the edges. --dir wrote the diagram into the wrong folder, and asking for a scan from a coding agent over MCP broke the connection.
  • A blind spot. On a project made of small services in five languages, it missed almost every connection between them. More on that below.

The first six are fixed in 0.10.0; the blind spot is fixed in 0.10.3.

The best bug report came from ArchByte

One of those six review agents is a security auditor. When I let it run on ArchByte's own code, its top finding was: "Claude Code provider runs claude -p with --dangerously-skip-permissions on untrusted repo content." It was right. A malicious README in a repository you scan could have asked the agent to do something you did not want.

It also found that the HTML export did not escape the diagram data, and that the agents' file tools would follow a symlink to a .env file. Eleven findings in total (one was a note that the local server was fine); I fixed eight of them the same day.

So the review agents earned their place, just not on every scan. They now run only when you ask (archbyte run --deep), three at a time instead of one after another.

What ArchByte does now

curl -fsSL https://diabhey.com/tools/archbyte/i | bashcd my-projectarchbyte run

It uses what you already have. If Claude Code or Codex is installed and signed in, ArchByte uses it, so there is no API key to find. An Anthropic, OpenAI or Gemini key also works, and setup asks the provider which models your key can use, so next month's model shows up without an update. archbyte doctor tells you in five seconds whether it will work.

It only reads. Claude Code gets three read-only tools (and none at all for most calls), Codex runs in its read-only sandbox, and .env files and private keys are never read. archbyte run --debug prints exactly what was sent to the model.

It shows you the diagram. archbyte run now opens your browser. Long layers wrap onto several rows with connected components near each other, instead of one row of eleven boxes too small to read.

It is honest about cost and time. A normal scan is five model calls. The numbers from this week:

37s small website, 5 components
53s ArchByte itself, 14 components
75s microservices-demo, 11 services
3 min small website with --deep

Without any model, archbyte run --static still draws something, but the gap is large. On the same small website the static scan found one component where the agents found five, with eight connections and four request flows.

Eleven services, five languages

Google's microservices-demo is an online shop split into eleven small services written in Go, C#, Node.js, Python and Java. They talk to each other over gRPC and run on Kubernetes. Plenty of real systems look like this, and you can check a diagram of it against the picture in its README.

The first scan was humbling. ArchByte found all the services, then drew three connections, all of them to Google Cloud's tracing and profiling. Nothing between the services, no Redis behind the cart, no request flows. A diagram of eleven boxes that don't touch tells you nothing.

The reason is that in a project like this, imports show nothing. The Go checkout service never imports the C# cart service; it finds it through a setting, CART_SERVICE_ADDR=cartservice:7070, in a Kubernetes manifest. ArchByte only looked for manifests in folders with a few fixed names (this project uses kubernetes-manifests/), and even then kept only the resource names, not the settings.

Now ArchByte reads every YAML file that turns out to be a Kubernetes resource, keeps the service addresses in each service's settings (with any passwords stripped out) and gives them to the agents that map connections. When a service points at something that runs a database image, like REDIS_ADDR=redis-cart:6379 where redis-cart runs Redis, the database and the connection go in without the model having to guess.

The same scan afterwards, 75 seconds:

13 components
3 → 18 connections
6 request flows
2 databases: Redis, AlloyDB

The connections are the shop's real call graph: the frontend calls eight services, checkout calls six (cart, product catalog, currency, shipping, payment, email), recommendations call the product catalog, and the cart keeps its data in Redis. The flows include browsing the catalog and placing an order, which you can play step by step.

It is not perfect. The Gemini API and AlloyDB show up but are not connected to the shopping assistant that uses them, and the shared protos folder appears as a component of its own. The model also varies from run to run. On one run it filed the product catalog under databases until I added a check that a folder of code in your own project is never a database or an outside service. Those are the kinds of things to check before you trust a diagram, and to fix in a minute in archbyte.yaml.

The microservices-demo diagram from this scan. Click, drag and zoom; Flows plays a request.

What I cut

Workflows, an architecture chat that had been switched off in the UI but still ran on the server, an "open in VS Code" endpoint nothing called, a GitHub Action that installed a package I had deprecated, and an old landing page. None of it was used, and all of it was something a stranger could trip over.

Earlier this month I also removed accounts entirely. ArchByte is free, there is no sign-in, and nothing talks to a server of mine.

What it does not do

  • The diagram is a reading, not a proof. It comes from a model reading your code. It is usually right about the big pieces and sometimes wrong about a connection. Check it, and fix it in .archbyte/archbyte.yaml; your edits survive the next scan.
  • The review agents are a reviewer's notes. The security finding above was real. Others were reasonable but minor. Read them like comments on a pull request.
  • Big systems get busy. Past about thirty components the diagram is dense. Drag things, hide what you do not need, or export to Mermaid and trim.

Try it

The playground runs the same diagram in your browser on a sample project, no install needed. When you want your own code mapped, the user guide covers everything from install to MCP.

curl -fsSL https://diabhey.com/tools/archbyte/i | basharchbyte run

Keep reading

All posts