ubermind

Manage multiple overmind instances across projects. Each project keeps its own Procfile and runs its own overmind daemon. ubermind orchestrates them all from anywhere.

Install

# shell script (prebuilt binary)
curl -fsSL https://raw.githubusercontent.com/mrgnw/ubermind/main/install.sh | sh

# gah (github asset helper)
gah install mrgnw/ubermind

# cargo
cargo install ubermind       # from source
cargo binstall ubermind      # prebuilt binary

overmind (and tmux) will be installed automatically if missing.

Quick start

1. Initialize ubermind

ubermind init

This creates a projects config at ~/.config/ubermind/projects.

2. Create a Procfile in your project

Each project you want to manage needs a Procfile in its root directory. A Procfile lists the processes to run — one per line, in name: command format:

# ~/dev/myapp/Procfile
web: npm run dev
api: python server.py
worker: ruby worker.rb

This is the standard Procfile format used by overmind, foreman, and others. Each line becomes a named process that ubermind (via overmind) will manage.

3. Register your project with ubermind

ubermind add myapp ~/dev/myapp

This tells ubermind "there's a project called myapp at ~/dev/myapp that has a Procfile."

4. Start it

ubermind start myapp    # start one project
ubermind start          # or start everything

How it fits together

ubermind has two layers of config:

Projects file (~/.config/ubermind/projects) — maps project names to directories:

myapp: ~/dev/myapp
api: ~/dev/api-server
frontend: ~/dev/frontend

Commands file (~/.config/ubermind/commands) — optional, defines standalone commands in Procfile format:

# Each line is a standalone command that runs as its own overmind instance
tunnel: ssh -N -L 5432:localhost:5432 prod-server
sync: watchman-wait . --max-events 0 -p '*.json' | xargs ./sync.sh

Each project directory has its own Procfile that defines what processes to run:

# ~/dev/myapp/Procfile
web: npm run dev
db: docker compose up postgres

# ~/dev/api-server/Procfile
server: cargo run
worker: cargo run --bin worker

# ~/dev/frontend/Procfile
dev: pnpm dev

When you run ubermind start myapp, ubermind looks up myapp → ~/dev/myapp, then starts overmind in that directory using its Procfile. Each project gets its own isolated overmind instance — one project crashing won't affect the others.

Standalone commands from the commands file are auto-expanded into generated Procfiles under ~/.config/ubermind/_commands/ so overmind can manage them the same way.

Usage

ubermind init                # create projects config file
ubermind add <name> <dir>    # register a project directory

ubermind status              # show all projects
ubermind start [name]        # start project(s)
ubermind stop [name]         # stop project(s)
ubermind reload [name]       # restart project(s) (picks up Procfile changes)
ubermind kill [name]         # kill process(es) in project(s)
ubermind restart [name]      # restart process(es) in project(s)
ubermind echo [name]         # view logs from project(s)
ubermind connect [name]      # connect to a process in a project
ubermind serve [-p PORT]     # start web UI server (default port: 13369)

Pass any overmind command to a specific project:

ubermind status myapp        # overmind status within myapp
ubermind echo myapp          # view myapp's logs
ubermind myapp connect web   # attach to myapp's web process
ubermind connect web myapp   # same thing, project name last

Omit the name to target all projects:

ubermind start               # start all projects
ubermind stop                # stop all projects
ubermind echo                # view logs from all projects

Config

The projects file lives at ~/.config/ubermind/projects (respects $XDG_CONFIG_HOME).

You can edit it directly or use ubermind add:

# name: directory
myapp: ~/dev/myapp
api: ~/dev/api-server
frontend: ~/dev/frontend

Optionally, define standalone commands in ~/.config/ubermind/commands:

# These run as individual overmind instances without a project directory
tunnel: ssh -N -L 5432:localhost:5432 prod-server
sync: watchman-wait . --max-events 0 -p '*.json' | xargs ./sync.sh

See tmux cheatsheet for navigating connected sessions (scrolling, copying error text, etc).

How it works

Each project directory gets its own independent overmind instance with its own .overmind.sock. ubermind knows where each project lives and dispatches commands to the right overmind in the right directory.

Standalone commands are auto-expanded into generated Procfiles under ~/.config/ubermind/_commands/ (an internal directory that you shouldn't edit directly).

• start/stop/reload are ubermind-level commands that manage the overmind daemon lifecycle (daemonized start, graceful quit, socket cleanup).
• Everything else is passed through directly to the project's overmind.

License

MIT

Extended Features

See extended_features/README.md for features added on top of standard overmind functionality.