hydra

Every worktree gets a running stack. Only the services it changed actually start.

hydra is a small wrapper around process-compose. Your main checkout runs the full stack, once. In every other git worktree, hydra starts the services that branch touched, on their own ports, and points them at main's copy of everything else.

Needs git and process-compose. Built and used on macOS.


What that looks like with agents at work

Rows are checkouts and columns are services. A lit cell is a process running in that checkout. A dot means the checkout uses main's copy.

Not a recording. The cells follow the rules hydra applies, and the log lines are the ones hydra-watch prints.


What you add to process-compose.yaml

hydra reads x-hydra keys from the file you already have. process-compose ignores keys it doesn't know, so the file keeps working for anyone who runs it without hydra.

process-compose.yaml+the lines you add
version: "0.5"

x-hydra:
  base_ref: main
  slot_stride: 200

base_ref is the branch a worktree is compared with.

slot_stride is how far apart worktrees sit. The first one listens on every port + 200, the second on + 400.

processes:
  db:
    command: docker compose up postgres
    x-hydra:
      shared: true

shared means there is only ever main's copy. Use it for databases, Docker and tunnels.

A process with no x-hydra block is treated the same way.

  api:
    command: go run ./services/api
    x-hydra:
      port: 8080
      port_env: API_PORT
      paths: ["services/api/**", "!**/*_test.go"]

paths are the files that mean "this branch changed the api". A leading ! excludes.

port is where main's copy listens. A worktree's copy is told its own port through port_env.

  web:
    command: pnpm --filter web dev
    depends_on:
      api: { condition: process_started }
    x-hydra:
      port: 3000
      paths: ["apps/web/**"]
      upstreams:
        API_URL: api

upstreams maps an environment variable to the service it points at.

In a worktree, API_URL is that worktree's api if it runs there, and main's otherwise.

Every option, with defaults, is in the docs.


How it decides

A service runs in a worktree when a file that differs from where the branch left main matches its paths. Committed, staged, unstaged and new files count. Git-ignored files don't.

$ git diff --name-only $(git merge-base HEAD main origin/main)
$ git ls-files --others --exclude-standard

With that list, hydra in a worktree:

  1. Picks the services whose paths match.
  2. Takes a slot for the worktree, which decides its ports.
  3. Writes .process-compose/hydra.yaml: those services only, with their ports and upstreams set.
  4. Starts process-compose on it, on a socket of its own. hydra down in a worktree can't stop main's stack.

hydra runs no services itself and proxies nothing. It writes a normal process-compose file and sets environment variables.


When things change

The generated file has one extra process, hydra-watch. Every 2 seconds it asks git the same question again. A service can move in two directions, and that is all the watcher does:

Services that point at it are restarted with the new address. Further edits to a service that already runs here are left to its own reload, like next dev or air.

It asks git instead of watching the file system because only git knows whether a file differs from main. A revert has to stop the service, and node_modules must not start one. It reads git without taking the index lock, so it stays out of the way of an agent's commits.

Stacked branches work too: each branch is compared with its parent, and each service runs from the worktree of the branch that changed it. How a stack is found.


Ask the planner

hydra plan prints what a checkout would run, and why. Tick the files a branch changed.

The api's paths exclude **/*_test.go, and db is shared. The config behind this is in the quick start.