hexwright

Design graph for hexagonal-architecture codebases. Extracts the type graph from source, checks ports-and-adapters boundaries, and renders exactly what a branch changed — structurally, not as a text diff.

(hex here is the hexagon, not hexadecimal.)

Why

A coding agent produces structure faster than anyone can review it, and the review is where the risk now sits. A text diff answers which lines moved. It does not answer did a controller start reaching into another context's aggregate — which is the question that decides whether the change was right.

That question is structural, so hexwright answers it structurally, in both directions:

• A human confirms in seconds, by looking. The delta renders as one picture: what the branch added, what it modified, and every relation it introduced. Not a claim about the code — a fact drawn from it. Cheap enough to attach to every PR, and cheap enough to attach to a design, before any logic exists, because the graph reads declarations from the working tree rather than commits.
• The agent checks itself first. Boundary verdicts are computed over the whole graph, so they are not something an agent can grep for and therefore not something it can skip by accident. Three MCP tools let it ask what it changed, what that reaches, and whether it broke a rule — before it asks you to look.

The human stays in the loop; what changes is that the loop costs a glance rather than a careful reading, and that most breaks are caught before it starts.

Runs as a sidecar: it never writes to the target repository.

npx hexwright extract --repo ~/work/my-service --base main --out .design
npx hexwright check   --repo ~/work/my-service --base main --scope delta  # CI gate
npx hexwright render  --repo ~/work/my-service --base main --image delta.png

Usage guides

Walkthroughs by scenario, rather than a list of flags.

	guide	for when you are
1	The agent's loop	wiring the graph into a coding agent — design confirmed before any logic is written, boundaries checked before the PR
2	Reviewing a branch	looking at finished work, by hand or as a CI gate
3	Exploring the architecture	trying to understand a system you did not write
4	Everything else	after the command that fits a one-off question

Render

An image for the PR — what this branch changed, in one picture.

hexwright render --repo ~/work/my-service --base main --image delta.png

  view    what this branch added and changed
  drew    10 types · 18 relations · 0 violations
  wrote   delta.svg  (17 KB)
  wrote   delta.png  (802×614)

The default draws only what changed — nothing pre-existing. That is not a loss of information: every relation the branch introduced has both ends inside the changed set, so narrowing keeps all of them while dropping the dependencies the modified types already had. On the branch above that is 10 types instead of 61, and the image fits a PR comment at full size instead of being scaled down until the labels are unreadable.

Use --view impact when the question is who is affected rather than what was built — it adds everything that depends on a changed type (30 types, 7 domains on the same branch).

Added types get a solid orange outline, modified ones a violet dash, new relations orange. Everything unchanged stays as dimmed context. Red is reserved for boundary violations — domain hues never enter the red or orange band, so a red line always means a breach.

The delta is laid out organically: each domain is a dense block ordered Entity → Service → UseCase → Port → DTO, and the blocks are placed by how much they actually couple. A change spanning several contexts therefore draws itself as a hub with the domains that touch it around it.

--view	what it draws
delta (default)	only the added and modified types, and the relations between them
impact	the above plus everything that depends on a changed type
core	Entity · Service · UseCase · Port · Event — the whole shape
all	everything, adapters and DTOs included
domain:<name>	one bounded context and what it touches

There is no browser involved — the coordinates are a pure function, so the SVG is written directly and CI needs no headless Chrome. The same graph always draws the same file, which is what makes two branches comparable.

--image x.png also writes x.svg. PNG needs the optional @resvg/resvg-js; without it the SVG is still written and the command says so. GitHub does not render SVG in comments, so attach the PNG there and keep the SVG as the artifact.

Layout follows the view — organic for delta and domain:, hex for core and all (concentric rings, read as a shape). --layout organic|grid|hex overrides; grid lists domains left to right, ignoring coupling.

MCP

Serve the graph to a coding agent over stdio:

hexwright mcp --repo ~/work/my-service --base main

{ "mcpServers": { "hexwright": {
    "command": "npx",
    "args": ["-y", "hexwright", "mcp", "--repo", "/abs/path", "--base", "main"] } } }

Three read-only tools. Anything an agent can get by reading a file is not one of them — it already has Read and Grep, and they are usually faster. What is left is what files cannot answer.

tool	what only the graph knows
check_violations(scope)	a verdict over the whole graph. scope: "delta" = only what this branch introduced
get_delta()	the structural diff against the base, per changed type
dependencies(name, direction, hops)	which methods a consumer actually calls, and which a port declares that nobody does

Each description says when to reach for the tool, not only what it returns — that is most of why this is an MCP server rather than a CLI the agent has to be taught. What a description cannot carry is a sequence, or an instruction to stop and wait for a human; the agent loop covers that.

dependencies is the one that pays off:

MediaPolicyPort [Port] media
depended on by (2):
  ← MediaObjectEventService  uses: maxPhotoSizeBytes, photoQuality, … (13)
  ← UploadService            uses: maxPhotoSizeBytes, maxVideoDurationSec,
                                   maxVideoSizeBytes, photoAllowedFormats,
                                   videoAllowedFormats

declares 17, never called (4):
  hqPhotoMaxLongSidePx(): Int
  ...

Four dead methods and two consumers overlapping in five of seventeen — an interface asking to be split. The port file shows declarations, not callers, so reading it does not tell you this.

Assumptions

Single-module Gradle project, Kotlin, Spring Boot, with a domain-first (package-by-feature) hexagonal layout.

The source root is found by Gradle convention — build.gradle(.kts) up to two levels deep, then <module>/src/main/kotlin. A monorepo with several Kotlin modules stops with the list and asks you to pick one:

found 3 Gradle modules with Kotlin sources (client/androidApp, media-processor, server).
hexwright assumes a single module — pass --src to pick one.

--src takes either a module path (server) or a source root (server/src/main/kotlin). If settings.gradle declares subprojects, it warns and analyzes only the selected module.

Expected package layout — the domain is the segment right after the common package prefix, which is inferred automatically:

<base>.<domain>.domain.model        Entity · VO
<base>.<domain>.domain.event        Event
<base>.<domain>.application.port.inbound   UseCase · DTO
<base>.<domain>.application.port.out       Port · DTO
<base>.<domain>.application.service        Service
<base>.<domain>.adapter.web                inbound adapter
<base>.<domain>.adapter.out                outbound adapter
<base>.common                              Shared

What it produces

nodes 701  Adapter 230 · DTO 126 · UseCase 113 · Port 60 · VO 55 · Service 46 · Entity 25
edges 2211 DEPENDS_ON 2021 · IMPLEMENTS 188 · EXTENDS 2
domains 16

delta vs main
  added 6 nodes · 15 edges   modified 4 nodes   removed 0
    + MediaLabelQueryPort [Port] media
    ~ MediaService [Service] media

violations 7
  AdminAuthController → admin.AdminAccount   inbound adapter touches Entity

--out writes two files:

• graph.json — full graph including public contracts
• graph.tsv — one line per node/edge, sorted, prefix-stripped. Commit this and git diff shows structural change in readable form.

Principles

Only relations that exist in the source. No derived or inferred edges. A reference to UserId is not a reference to User — promoting it would fabricate facts and every metric built on top would be wrong.

Deterministic classification. Component roles come from path + language construct only. No human judgement, so results are reproducible and comparable across commits.

Signature-following. When a type is only held in a local variable, its name never appears in the source. The extractor reads the callee's signature to recover the reference, so service.save(x) resolves x through Repository.findById(): Record?.

Profiles — adapting it to your layout

Every convention lives in a profile, not in code. port/in versus port/inbound, infrastructure/ versus adapter/, a different package depth — all of that is a config change rather than a fork.

Start from the bundled one:

curl -O https://raw.githubusercontent.com/vonkernel/hexwright/main/profiles/hexagonal-kotlin.yml
npx hexwright extract --repo . --profile ./hexagonal-kotlin.yml

A profile has five parts, and they are read in this order.

Where the domain is. The domain is a package segment, found after stripping a common prefix. Leave base empty and the longest common prefix is inferred — which is right for a multi-domain codebase and wrong for a single-domain one, where it swallows the domain too. Set it explicitly then, or pass --base-package.

domain:
  from: package
  base: ""     # com.acme.service — empty means infer
  at: 0        # which segment after the prefix is the domain

Which layer a path is in. Fragments, matched top to bottom, first hit wins. Rename these and the whole tool follows:

layers:
  adapter: /infrastructure/     # instead of /adapter/
  application: /application/
  domain: /domain/
  common: /shared/

Subdivisions and adapter direction. sublayers is what separates an inbound port from an outbound one; adapterKinds is what lets an outbound adapter map aggregates while an inbound one may not.

sublayers:
  port/inbound: /application/port/in/    # instead of /port/inbound/
  port/out: /application/port/out/
  service: /application/service/
  model: /domain/model/

adapterKinds:
  out: /infrastructure/out/
  in: /infrastructure/rest/

What each type is. Ordered rules, first match wins. A rule may test the layer, the sublayer, the language construct (kinds), the structural kind (structs), or a name suffix:

components:
  - { nameEnds: Exception, as: Error }
  - { sublayer: model, kinds: [value class], as: VO }
  - { sublayer: model, as: Entity }
  - { sublayer: port/out, structs: [interface], as: Port }
  - { sublayer: port/out, as: DTO }
  - { as: DTO }                       # fallback

Order carries the meaning. port/out + interface is a Port; the same path without interface is a DTO, because that is what a class in a port package actually is.

What counts as a violation. Both rules are explicit, so a codebase with a different opinion can hold it:

rules:
  entityAccess:
    allow: [Service, Port, Entity]    # may touch an Entity, same domain only
    allowAdapterKinds: [out]          # outbound adapters map aggregates
    crossDomain: deny
  layering:
    - from: [application, domain]
      to: [adapter]
      message: layer back-reference

Check a new profile against the tool's own reading before trusting it — if the component counts look wrong, a path fragment is wrong:

nodes 701  Adapter 230 · DTO 126 · UseCase 113 · Port 60 · VO 55 · Service 46 · Entity 25
domains 16

Zero Ports or a domain count of 1 means the paths or the base package are not matching your layout yet.

Boundary rules

An Entity may be touched by, within the same domain: Service, Port, Entity, and outbound adapters (port implementations must map aggregates). Everything else is a violation:

• cross-domain Entity access — bounded context breach
• inbound adapter touching an Entity — controllers should speak DTOs
• a DTO or UseCase exposing an Entity — domain model leaked into a contract
• application/domain referencing adapter — layer back-reference

Status

Early. Kotlin extractor only; validated against one production codebase (701 nodes, 2211 edges) with output verified against a reference implementation.

MIT