Procfile Manager

procfile-manager

Operate local multi-process development stacks defined in a Procfile. Automatically detects the Procfile, parses available processes, selects the best runner, and provides process lifecycle management and log inspection.

When to Use

• User asks to start, stop, restart, or kill local services
• User asks to check, tail, or inspect logs from a running process
• User asks to connect to or interact with a running process
• User wants to see what processes are defined in the Procfile
• User mentions Overmind, foreman, hivemind, or Procfile
• User asks to run the local dev stack or app stack
• A CLAUDE.md or AGENTS.md references a Procfile-based workflow

Workflow

1. Discover the Procfile

Search for a Procfile in the project root and any parent directories up to the git root:

Procfile
Procfile.dev
Procfile.local

If no Procfile is found, stop and tell the user. Do not invent processes.

2. Parse Processes

Read the Procfile and extract every process entry (lines matching name: command). Ignore comments and blank lines. Build a process map:

Report the discovered processes to the user before acting.

3. Select a Runner

Check which Procfile runners are installed, in preference order:

1. Overmind (overmind -v) — preferred; supports per-process control, log streaming, connect, restart
2. Hivemind (hivemind --version) — lightweight alternative; start-only, no per-process control
3. Foreman (foreman version) — Ruby-based; supports process selection via -m

Use the first available runner. If none are installed, recommend installing Overmind and stop.

4. Execute the Requested Operation

Route the user's intent to the appropriate runner command. All examples below use Overmind; adapt syntax if using an alternate runner.

Start the full stack:

overmind start -f Procfile

Start specific processes only:

overmind start -f Procfile -l temporal,worker,web

Restart a single process:

overmind restart web

Stop a single process:

overmind stop worker

Kill the entire stack:

overmind kill

Inspect logs for a process:

overmind echo worker

Connect to a process (interactive):

overmind connect web

5. Verify

After starting or restarting, confirm the process is running:

overmind ps

If a process fails to start, inspect its logs with overmind echo <name> before retrying.

Runner Command Reference

Constraints

• Never start a process by running its raw command from the Procfile directly. Always use the runner. The Procfile is the source of truth for how processes are configured; the runner is how they are operated.
• Never guess process names. Parse them from the actual Procfile.
• If the Procfile path is non-standard (e.g., Procfile.dev), pass it explicitly via -f.
• When starting a subset, only include processes the user asked for. Do not silently add extras.
• If a process is already running, do not start a duplicate. Use restart instead.
• If Overmind is available, always prefer it over foreman or hivemind for per-process operations.

Common Mistakes

• Running yarn dev or npm start when a Procfile target exists. The Procfile defines the canonical process configuration (env vars, flags, ports). Running the underlying script directly skips that configuration.
• Killing the whole stack to restart one process. Use overmind restart <name> instead of overmind kill followed by overmind start.
• Rerunning a script to see its output. Use overmind echo <name> to read logs from an already-running process instead of stopping and restarting it.
• Starting Overmind in the background. Overmind manages its own process tree. Do not & or nohup it — run it in a dedicated terminal or tmux pane.
• Forgetting to check overmind ps after start. A successful overmind start does not guarantee every process booted cleanly. Always verify.