hop

zero-config dev-loop conductor

One command for every project in the folder.

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
  • Node ≥ 22.12
  • MIT
  • 3 runtime deps
  • Windows · macOS · Linux
hop — zsh
$ 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

Starting a repo shouldn't be a chore

Six terminals, six cds

One per subproject — plus the one you forgot to restart after pulling.

Everything wants port 3000

The second app dies with EADDRINUSE — or worse, quietly talks to the wrong service.

Instant race conditions

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

Discovery, not configuration

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.

Scans the tree you already have

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

A picker that already knows git

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

Ports resolved before they collide

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

Dependencies that actually wait

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

Output you can still read

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

Escape hatches for real projects

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

Two problems, solved before the first line prints

Which port will it use?

  1. --port 3000 in the script command — rewritten if it has to move
  2. PORT in the environment
  3. PORT= 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.

What must be up first?

  • a service URL in .env that matches a port a selected sibling exposes
  • a bundler proxy config pointing at a local port
  • a localhost:… URL inside the script command itself
  • anything you declare in "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

Not a build system. Not an orchestrator. The layer in between.

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.

  1. Builds & CI Turborepo · Nx · moon · GitHub Actions
  2. Containers & production Docker Compose · Kubernetes · systemd · PM2
  3. Dev-loop conductors hop — discovery, port arbitration, readiness gates, one terminal
  4. Your projects Node · Docker · Python · Go — exactly as they are on disk

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.

How hop relates to tools in adjacent layers
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.

Reach for hop when…

  • one folder holds several runnable projects, in mixed ecosystems
  • you want to start working with hop + Enter, not a setup ritual
  • dev services need ports that don't collide and a boot order that doesn't race
  • you want one Ctrl+C to leave no orphans behind
  • you'd rather not add a config file to a repo you don't own yet

Reach for a neighbour when…

  • you need task graphs, caching or CI acceleration — that's Turbo/Nx/moon
  • everything you run is already a container — compose alone is fine
  • it's one package with two commands — concurrently is smaller
  • processes must survive the session — that's PM2 or systemd
  • a Procfile already describes your stack and overmind serves it well

04 — in the interest of trust

What hop intentionally is not

A tool's place in the ecosystem is also defined by what it refuses to do. hop is small on purpose.

  • No caching or task graph. hop starts processes; it doesn't hash inputs, watch files or rebuild anything. Build systems do that better.
  • Piped stdio. Output is piped to be tagged, so fully interactive children (a wizard like npm init) may not get a TTY on stdin.
  • Fingerprints only. No workspace-manager awareness (pnpm workspaces, turbo, nx), and symlinked directories are skipped to stay cycle-safe.
  • Conservative port edits. Only --port, $PORT and PORT= in .env* are swapped — anything hard-coded elsewhere is left alone.
  • Heuristic gating. A referenced port is only awaited when a selected sibling exposes it, unless you declare it in hop.waitFor.
  • Compose short syntax. Published ports are read from the ports: list form; exotic mappings are not interpreted.

05 — get started

Sixty seconds, no config

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.

  1. 1

    Open the folder

    Any repository with runnable subprojects — or a plain directory of experiments.

  2. 2

    Run 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.

  3. 3

    Work, then Ctrl+C

    One signal stops every process tree in the selection, on Windows, macOS and Linux alike.