Six terminals, six cds
One per subproject — plus the one you forgot to restart after pulling.
zero-config dev-loop conductor
hop scans your repo for runnable Node, Docker, Python and Go projects and runs the scripts you pick — side by side, with readable prefixed output, ports that never collide, and dependencies that actually wait their turn.
npm install -g hop-run
$ hop ┌ hop · 3 projects detected │ ◆ Select scripts to run │ ◻ api │ │ ◼ dev (node src/server.js --port 8080) │ └ ◻ test │ ◻ database │ │ ◼ up (docker compose up) │ └ ◻ down │ ◻ web · 2 changed │ │ ◼ dev (next dev) │ └ ◻ build │ ↑/↓ to navigate • Space: select • Enter: confirm └ api dev node src/server.js --port 8080 database up docker compose up web dev next dev [hop] ⚠ port 8080 was blocked · redirecting [api] to port 8081 [hop] waiting for database :5432 before starting api [database] db-1 | database system is ready to accept connections [hop] ✔ database :5432 is up · 1.4s · starting api [api] server listening on :8081 [web] ▲ Next.js ready on http://localhost:3000
It just keeps running — one Ctrl+C stops every process tree in the selection.
the ritual we keep rewriting
cdsOne per subproject — plus the one you forgot to restart after pulling.
The second app dies with EADDRINUSE — or worse, quietly talks to the wrong service.
The API boots before Postgres is ready and greets you with ECONNREFUSED.
hop is the thin layer that makes that loop boring again — discovery, arbitration, one terminal.
01 — what hop does
Point hop at a folder. It fingerprints what's inside, offers the scripts it found, and runs the ones you pick — no manifest, no plugin, no workspace migration.
The current folder and 3 levels below, skipping node_modules, .git,
dist, venv and dot-directories. Several fingerprints in one folder merge
into a single project; name collisions get namespaced (build vs
docker:build).
package.json → dev, build, test … Dockerfile → build docker-compose.yml → up, down requirements.txt → install main.py → run go.mod → run, test
Projects with uncommitted changes come pre-selected, marked · 2 changed. In practice
hop + Enter runs what you were just working on. Space toggles a
whole project row, Ctrl+C backs out without starting anything.
│ ◻ web · 2 changed │ │ ◼ dev (next dev) │ └ ◻ build
hop reads the port a project wants, walks upward when it's taken, rewrites the --port
flag and injects the new PORT. Ports are reserved per run, so two projects that both
want 3000 never fight. Docker targets are never rewritten — their compose host ports are reserved
instead.
[hop] ⚠ port 8080 was blocked · redirecting [api] to port 8081 [api] server bound 127.0.0.1:8081
When a project clearly talks to a sibling — a localhost:5432 in .env, a
proxy config, a URL in the script — hop holds it back until the port accepts connections. Spinner
on a TTY, a 30 s breaker that warns and moves on, --no-wait to skip it all.
[hop] waiting for database :5432 before starting api [hop] ✔ database :5432 is up · 1.4s · starting api
Every line gets an aligned, colored [folder] tag, and children keep their own colors
even though hop pipes them. Ctrl+C stops everything: process-group kill on
POSIX, taskkill /T /F on Windows, with a hard-kill backstop after 5 s. Exit codes
are honest: 0, 1, 130.
[database] db-1 | ready to accept connections [api] server listening on :8081 [web] ▲ ready in 1.2s
Run one script across every project, route it through the real package manager (hooks and npm env included, detected from the nearest lockfile), or just look at what hop found before running anything.
hop dev # every "dev" script in the tree hop dev --npm # through the real package manager hop --list # what was detected, what would run hop dev --no-wait # skip dependency handshakes
02 — the startup rules
--port 3000 in the script command — rewritten if it has to movePORT in the environmentPORT= in the project's .env, .env.local or .env.development
Taken? hop walks upward, reserves the result for the run, and hands the child the new number through
PORT — real environment variables beat .env in every mainstream framework,
so injecting it is enough to move an app that reads a file.
Ports that are hard-coded somewhere hop can't see (config files, -p short flags) are
left alone rather than guessed at.
.env that matches a port a selected sibling exposeslocalhost:… URL inside the script command itself"hop": { "waitFor": … }The gate is a plain TCP check with an animated spinner until the port accepts connections. Timeout at 30 s warns and starts anyway — a handshake is advice, never a hard failure.
{
"hop": {
"waitFor": [
5432,
"localhost:6379",
"http://127.0.0.1:8080/health"
]
}
}
03 — where hop sits
There are excellent tools at every layer of a repository — and none of them answer the small question you have forty times a day: “start everything I'm working on, without fighting about ports.” That's the layer hop occupies.
hop drives the layer below it — including Docker — and otherwise stays out of the way. It writes no files, keeps no state and never touches your build.
| Neighbour | Great at | How hop differs |
|---|---|---|
| concurrently · npm-run-all | Running a command list you write yourself inside one package.json. |
Same dev-time layer, different input: hop discovers the projects and their scripts instead of you listing commands — and adds the picker, git pre-selection, port arbitration and readiness gates. |
| Turborepo · Nx · moon | Task graphs, content-hash caching, remote cache and CI acceleration for a workspace you instrument. | A different layer: they optimise tasks in a workspace you opt into; hop conducts the dev loop in any folder, heterogeneous projects included, with nothing to adopt. They compose well — turbo for builds and CI, hop to bring the stack up. |
| Docker Compose · Kubernetes | Declarative container orchestration, networks, volumes, production parity. |
Complementary: hop runs docker compose up as one participant, reserves the host
ports compose publishes, and keeps native projects beside it. If everything you run is a
container, compose alone is enough.
|
| foreman · overmind · hivemind | One Procfile declares process types; output is multiplexed (overmind adds tmux-backed controls). |
hop derives the process set from the folder layout rather than a Procfile, and adds the picker, port rewriting and TCP gates. If you already maintain a Procfile you like, those tools are the leaner choice. |
| PM2 · systemd | Production supervision: restarts, clustering, boot persistence, log rotation. | Deliberately dev-time only. hop starts the processes for a session and stops them together; it never supervises, restarts or daemonises anything. |
| VS Code compound launches | Editor-bound multi-launch with debuggers attached to every process. | Terminal-first and editor-agnostic. hop earns its keep on readiness gates, port conflicts and a single Ctrl+C — not on debug sessions. |
| tmuxinator · mprocs · run-pty | Declarative terminals with one pane per command, and pretty multiplexing. | No panes to arrange: interleaved, tagged lines and a selection you can filter. Nothing to declare — and it is the run itself, not a terminal layout around it. |
| make · just · task | Explicit, repeatable recipes you write once and version with the repo. | Discovery over declaration. Keep your recipes for the parts that deserve them; hop covers the common case — “just start this folder” — with nothing to write. |
hop + Enter, not a setup ritualconcurrently is smaller04 — in the interest of trust
A tool's place in the ecosystem is also defined by what it refuses to do. hop is small on purpose.
npm init) may not get a TTY on stdin.
--port, $PORT and
PORT= in .env* are swapped — anything hard-coded elsewhere is left alone.
hop.waitFor.
ports: list
form; exotic mappings are not interpreted.
05 — get started
Install once, use everywhere
npm install -g hop-run
Or run it without installing
npx hop-run
Requires Node.js 22.12 or newer. No accounts, no telemetry, no files written to your repo.
Any repository with runnable subprojects — or a plain directory of experiments.
hop
Pick scripts in the picker (changed projects are pre-selected), or go straight to
hop dev to run every dev script it found. hop --list shows
the inventory first.
One signal stops every process tree in the selection, on Windows, macOS and Linux alike.