Public alpha · Windows

Your USB tree, explained.

Every USB tool shows you the tree. Port Authority tells you why the drive is slow, which socket it should be in, and why your dock came up at half speed.

I built it because my new SSD was crawling. It was on the wrong port of the dock. Of course it was. Nothing on the machine would tell me that, so now something does.

Get the Windows alpha View on GitHub

Free, MIT. Nothing leaves your machine. It reads your ports and never touches them.

Port Authority showing a laptop, a CalDigit TS4 dock and its devices, with a finding: Corsair EX400U could be up to 4x faster on a different port.

Explains, not lists

Findings in plain language, each with a what to do. The spec-nerd details are one click away, not in your face.

Reads, never writes

It observes and measures. It never changes a device setting, and it never sends anything anywhere.

Never guesses

Where Windows cannot tell two situations apart, the app shows what it measured instead of the prettier answer.

API first

The window is a plain HTTP and WebSocket consumer of a local API. Build a better UI on it; I would love to see one.

The finding that started it

Same drive, same dock, a different hole.

The first thing the app ever found, on my own desk. I had plugged a 40 Gbps SSD into the one USB-C socket on the front of the dock, which is the 10 Gbps one. Moving it doubled the throughput. No new hardware, no driver, just the right socket.

Corsair EX400U could be up to 4x faster on a different port

Corsair EX400U supports 40 Gbps (USB4 / Thunderbolt), but it is plugged into the "USB-C Data" port on the front of the CalDigit TS4, which is a 10 Gbps port. Everything it does is capped by that port.

What to do: Move Corsair EX400U to one of the 2 "Thunderbolt 4" ports on the rear of the CalDigit TS4.

Verbatim from the app. The port names are the ones printed on the dock, because the knowledge base knows which internal hub port is which printed socket.

What it does

See it, understand it, fix it.

A diagram you can actually read, a list of things worth knowing, and a timeline of what changed.

A diagram with two readings

Physical draws the boxes on your desk: one computer, one dock, one cable. Logical draws what Windows sees: every controller, every hub, every device. They disagree on purpose.

Live throughput

Per-device transfer rates from Windows' own event tracing, drawn as moving dashes on the cables. A hub's uplink carries the sum of everything behind it, so you can watch a bottleneck fill up.

Findings in plain language

Severity, a one-line headline, the reasoning, and a concrete what-to-do. Click a device's flag to filter; the device a finding names pulses in the diagram.

What changed

Hotplug events as they happen: what arrived, what left, what came up slower than last time. The moment things broke is the clue everyone loses.

Docks as one box

To Windows a Thunderbolt dock is four or five hubs across two controllers plus a router in a different namespace. To you it is one dock. A knowledge base bridges the two, and you can teach it yours.

Colour that means something

Device classes each get a hue, link speeds run cool to hot, and link health is a separate ring, so "how fast" and "is it right" never share a signal. There is a legend, and never colour alone.

Community docks

Teach it your dock, once, for everyone.

A dock cannot tell Windows what it is. Only a person with the dock on their desk knows that those five hubs are one UGREEN adapter, or that hub port 3 is the socket printed "USB-C Data". So the knowledge base is a community project: a small public repository of docks and devices, separate from the app and MIT-licensed, so the data outlives any one program that reads it.

Unrecognised dock? The app asks, you name it and pick its sockets, and it draws as one box from then on.
Press Share with the community and a pre-filled GitHub issue opens. No account inside the app, no token, nothing sent behind your back.
A workflow validates the entry and opens a pull request; I review and merge.
Merged entries are published within minutes, and every copy of the app picks them up on its next start.
A submission carries hub ids, names and ports. Never serial numbers.

My own UGREEN adapter went in this week through that exact flow, without a hitch, so the pipe is real. The dock list is short today. That is where you come in.

usb-device-kb on GitHub

Set it up

Name the dock, pick which sockets are which.

One button, one pre-filled issue.

Checked

Validated by a workflow, reviewed by a human.

Everywhere

Published in minutes, fetched on next start.

A closer look

Real screens, real desk.

Captured from my own machine and dock. Serial numbers scrubbed, embarrassment left in.

Physical view: this computer, a CalDigit TS4 dock drawn as one box with its sockets, and the devices plugged into it. — Physical view. One computer, one dock, and the sockets down each edge.

Logical view: the host controller and every hub inside the dock drawn separately, as Windows reports them. — Logical view. The same dock as Windows sees it: a chain of hubs.

A finding: CalDigit TS4 is connected at 20 Gbps; it can do 40 Gbps. — The dock came up at half speed. Everything behind it shares that link.

Tree view: the controller, hubs and devices as an indented list with speed badges. — The tree, for when you want the list. Same colours, same collapse state.

The honest bits

What Windows won't tell us.

The app reports what the OS knows, and the OS does not always know. These are limits of the data rather than bugs, so they are worth recognising before filing one.

Chargers are invisible

A USB-PD brick is not a USB data device, so a socket with a charger in it reads as empty. Connector-level data is on the list.

Two chips, two boxes

A cheap hub with two chips inside can draw as two boxes. Only its firmware knows better, and cheap firmware rarely says. Recognised docks are folded; the rest is left as reported.

Windows only, for now

The Windows collector is the only one. The architecture is macOS-ready in the "write one provider" sense, which is a real sense, but it is a weekend project.

Author's note

I'm a software engineer with ~35 years in, eyeing off retirement. Port Authority is the second thing to come out of my weekends with Claude, after BRUV, and it exists for the most selfish reason there is: I wanted to know why my drive was slow, and every tool I tried answered a different question.

The rule I keep coming back to is that the app must never guess. A pretty diagram that merges two boxes that are not the same box is worse than an ugly one that tells the truth. So when the data runs out, the app says so, and asks you instead. That is what the community dock list is for.

It is an alpha. It has been thoroughly tested on one laptop and one dock, which is to say: your machine will find something mine could not. If it does, a scrubbed snapshot in an issue is the best present you can give me. If it's not for you, no worries.

— Harvey

Try it, if you like.

Public alpha, Windows for now. The installer isn't code-signed, so SmartScreen will grumble at you. (Boo hoo, Windows.)

Get the Windows alpha Star on GitHub

Free, MIT, no strings. No account, no telemetry, no paid tier.
Reads, never writes. It cannot change a device setting because it has no code that does.
Weekend-maintained. Issues are read and appreciated; there's no SLA and no roadmap promises.
The data is yours, and everyone's. Your own dock entries live in a folder on your disk; what you choose to share goes into an MIT repository anyone can use.