DocSee Popup — Raycast-Style Docker HUD

The actual problem: six projects, constant juggling

At any point during active freelance work I'm running between four and eight Docker Compose projects simultaneously. Each has its own services — API, worker, maybe a queue — plus shared infrastructure that multiple projects reference: one postgres instance, one redis instance that several projects write to. The default workflow is docker compose up -d to start a project, docker compose down when switching contexts, repeated across terminal tabs throughout the day. Everyone uses this workflow. I used it long enough to get genuinely frustrated with it.

The friction lives at two levels. First, the recall problem: after a few days away from a project, I'm scanning docker ps output trying to correlate container name prefixes back to their compose project. The names are not always intuitive and there are a lot of them. Second, the shared infrastructure problem: running docker compose down on one project tears down the postgres instance, which silently breaks another project I'm still using. There is no built-in safety net in Docker Compose for shared services. The second failure happened to me enough times that I started treating it as a workflow tax I was simply accepting.

I wanted a Raycast-style popup: press a hotkey from anywhere, type a project name, toggle its stack up or down, close. But building that correctly meant solving the shared infrastructure problem first — which is where frecency ranking and reference counting come in.

Frecency ranking and infra ref-counting

Frecency combines frequency and recency — the same algorithm Firefox uses for bookmark ranking. A project you used constantly three months ago but haven't touched since should rank below something you started yesterday. I calculate a recency score with exponential decay over time and combine it with a frequency score tracking toggle events. The ranked list appears instantly at hotkey invoke, without typing, which is what makes the popup genuinely faster than navigating to a terminal and running docker compose up -d. Most of the time the right project is in the top three results.

The ref-counting is what I'm more satisfied with technically. Each shared infrastructure service — postgres, redis, any service flagged as shared in the config layer — maintains a reference count of active compose stacks that depend on it. When you toggle a project down, the system checks the count: does any other active project still depend on this postgres instance? If yes, it tears down only the project-specific services and leaves the shared service running. Postgres goes down only when its reference count reaches zero. This is reference-counted memory management applied to container lifecycle, and once you see the analogy, the implementation is straightforward. The design came directly from the second time I knocked out postgres mid-session.

The service dependency graph — which services each project depends on, which are shared — is declared in a config layer on top of the standard docker-compose.yml. The popup reads it. The background daemon enforces it.

Unix socket IPC and the hotkey response requirement

A global hotkey popup has one non-negotiable quality attribute: it must appear without perceptible latency. If there's any delay between pressing ⌥ Space and the panel opening, the tool feels unreliable. The Docker API call that populates the container list cannot be on the critical path of that animation.

The architecture is a persistent background daemon — a Rust process that stays running — which holds an up-to-date snapshot of Docker state and listens on a Unix socket. When the popup window opens, it requests state over the socket instead of calling the Docker API directly. The daemon pushes live updates as containers change, so the popup's first render is always current. The UI layer owns presentation and user intent. The daemon owns Docker state. The socket is the interface between them.

This split added complexity: 2,973 lines of Rust on the daemon side, 3,093 TypeScript on the frontend. It was the right call. The Framer Motion entrance animation runs while the socket response is already in-flight; in practice the state arrives before the animation completes. Responsiveness was the primary quality requirement and the architecture serves it directly.

6,066 lines total. The honest caveat: the popup is an MVP. What I would build next is a project-level health score that persists across sessions — not just whether containers are running right now, but historical crash frequency, so the popup can surface "this stack has been unstable this week" as ambient information before you toggle it on.