Overmind for Development

Overmind is a tmux-based process manager. Key advantage over Foreman: daemon mode, individual process restart, and interactive debugging via overmind connect.

Requires tmux (installed automatically by brew install overmind on macOS).

Setup Checklist

1. Procfile.dev at project root — one service per line (name: command)
2. bin/dev — bash wrapper with subcommands (start, stop, restart, status, logs, help)
3. .overmind.env — socket path + recommended settings
4. tmp/.keep — tracked by git; .gitignore has /tmp/* + !/tmp/.keep

.overmind.env — Recommended Settings

OVERMIND_SOCKET=tmp/overmind.sock
OVERMIND_NO_PORT=1
OVERMIND_CAN_DIE=css

Setting	Why
OVERMIND_SOCKET=tmp/overmind.sock	Keeps project root clean, avoids macOS 104-char socket path limit
OVERMIND_NO_PORT=1	Prevents Overmind from injecting PORT=5000/5100/5200 which shadows explicit port vars in Procfile
OVERMIND_CAN_DIE=css	Tailwind watcher crash doesn't tear down the whole stack

Optional: OVERMIND_AUTO_RESTART=css to auto-restart watchers on crash.

Key Design Decisions

• Daemon by default for engine/library projects — bin/dev daemonizes so agents and developers can keep working. -f flag for foreground when debugging. For app projects, foreground by default may be better (crashes are immediately visible).
• Explicit -s "$SOCKET" on every overmind command — don't rely on .overmind.env alone. The socket flag works regardless of CWD, which matters for scripts that cd into subdirectories.
• Socket in tmp/ — keeps project root clean (Rails convention).
• Stale socket handling — bin/dev cleans up stale sockets before starting (prevents "already running" errors). bin/dev stop falls back to removing the socket if overmind quit fails.

bin/dev Commands

Command	What it does
bin/dev	Start daemonized (default)
bin/dev -f	Start in foreground
bin/dev stop	Stop running instance
bin/dev restart web	Restart a specific service
bin/dev status	Show process statuses and URLs
bin/dev logs	Tail all logs
bin/dev logs web	Tail logs from a specific service
bin/dev -- -l web,css	Pass flags directly to overmind

Procfile Patterns

# Standard Rails
web: bin/rails server -p ${PORT:-3000}
css: bin/rails tailwindcss:watch

# With explicit port vars (use with OVERMIND_NO_PORT=1)
web: cd lookbook && bin/rails server -p ${LOOKBOOK_PORT:-4001}
docs: cd docs && bin/bridgetown start -P ${DOCS_PORT:-4000}

# With workers
worker: bundle exec sidekiq

Agent Workflow

1. Check status: bin/dev status 2>/dev/null && echo "running" || echo "not running"
2. Start daemonized: bin/dev (never foreground — blocks terminal)
3. After lib/ changes: bin/dev restart web (app/ changes autoload)
4. Read logs: bin/dev logs web (single process) or bin/dev logs (all)
5. Leave running at session end — user runs bin/dev stop when done.

Useful Overmind Flags

Flag	Purpose
-D	Daemonize
-f FILE	Specify Procfile path
-s SOCKET	Specify socket path
-r PROCESS	Auto-restart on crash (-r all for everything)
-l PROCESS	Only start specific processes (-l web,css)
-N	Disable automatic PORT assignment (same as OVERMIND_NO_PORT=1)

Common Pitfalls

• Stale sockets — after crash/reboot, overmind start says "already running". Fix: rm tmp/overmind.sock (or let bin/dev handle it).
• Port shadows — without OVERMIND_NO_PORT=1, Overmind injects PORT=5000/5100/5200 per process, overriding explicit port vars.
• Socket path length — macOS limits Unix socket paths to 104 chars. tmp/overmind.sock (relative) avoids this. Never use $TMPDIR.
• Nested tmux — if inside tmux, overmind connect nests sessions. Detach with Ctrl-b Ctrl-b d (double prefix).