Skills › Compound Engineering › ce-polish › dev-server-procfile.md

dev-server-procfile.md

59 lines · skills/ce-polish/references/dev-server-procfile.md at 3449230

Runs code

Most marks come from matching words in the file, so treat them as pointers.

1# Procfile / Overmind dev-server recipe (auto-detect fallback)

3Loaded when `detect-project-type.sh` returns `procfile` and the startup tuple still lacks a command. Rails apps with `bin/dev` take precedence over the bare Procfile path (see `dev-server-rails.md`).

Procfile / Overmind dev-server recipe (auto-detect fallback)

Loaded when detect-project-type.sh returns procfile and the startup tuple still lacks a command. Rails apps with bin/dev take precedence over the bare Procfile path (see dev-server-rails.md).

Raw lines 1 to 4

Runs code bin/dev :3

5## Signature

7- `Procfile` or `Procfile.dev` exists at the repo root

8- `bin/dev` is **not** present (if it is, use the Rails recipe)

Signature

Procfile or Procfile.dev exists at the repo root
bin/dev is not present (if it is, use the Rails recipe)

Raw lines 5 to 9

Runs code bin/dev :8

10## Start command

12Prefer `overmind` when available — it handles socket files, supports hot-restart per process, and is the community default for multi-process dev:

14```bash

15overmind start -f Procfile.dev

16```

18Fallback to `foreman` when `overmind` is not installed:

20```bash

21foreman start -f Procfile.dev

22```

24If both are missing, prompt the user for the start command rather than guessing.

Start command

Prefer overmind when available — it handles socket files, supports hot-restart per process, and is the community default for multi-process dev:

overmind start -f Procfile.dev

Fallback to foreman when overmind is not installed:

foreman start -f Procfile.dev

If both are missing, prompt the user for the start command rather than guessing.

Raw lines 10 to 25

26## Port

28Default: `3000`. Procfile-based projects list their processes in `Procfile.dev`, so the authoritative port comes from the `web:` line:

30```

31web: bundle exec puma -p 3000 -C config/puma.rb

32worker: bundle exec sidekiq

33```

35Parse the `web:` line for `-p <n>` or `--port <n>`. If neither is present, fall through to the cascade in `references/dev-server-detection.md`.

Port

Default: 3000. Procfile-based projects list their processes in Procfile.dev, so the authoritative port comes from the web: line:

web: bundle exec puma -p 3000 -C config/puma.rb
worker: bundle exec sidekiq

Parse the web: line for -p <n> or --port <n>. If neither is present, fall through to the cascade in references/dev-server-detection.md.

Raw lines 26 to 36

37## Stub generation

39```json

40{

41 "version": "0.2.0",

42 "configurations": [

43 {

44 "name": "Overmind dev",

45 "runtimeExecutable": "overmind",

46 "runtimeArgs": ["start", "-f", "Procfile.dev"],

47 "port": 3000

48 }

49 ]

50}

51```

53Substitute `foreman` if `overmind` is unavailable on the user's machine — the stub represents what the user will run, not a canonical recipe.

Stub generation

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Overmind dev",
      "runtimeExecutable": "overmind",
      "runtimeArgs": ["start", "-f", "Procfile.dev"],
      "port": 3000
    }
  ]
}

Substitute foreman if overmind is unavailable on the user's machine — the stub represents what the user will run, not a canonical recipe.

Raw lines 37 to 54

55## Common gotchas

57- **Socket files:** `overmind` writes a socket to `.overmind.sock` by default. If another instance or a stale socket prevents startup, report the log evidence and let the user decide whether to reuse that process or correct the start configuration. The `OVERMIND_SOCKET` env var can redirect the socket to a per-run path when the project already uses that convention.

58- **Procfile vs Procfile.dev:** production and development Procfiles often differ. Always prefer `Procfile.dev` for polish.

59- **Multiple web processes:** some Procfiles split web traffic across multiple processes (API + frontend). Polish can only open one URL — users with multi-web setups should author `.claude/launch.json` explicitly to select which process is "the dev server" for polish.

Common gotchas

Socket files: overmind writes a socket to .overmind.sock by default. If another instance or a stale socket prevents startup, report the log evidence and let the user decide whether to reuse that process or correct the start configuration. The OVERMIND_SOCKET env var can redirect the socket to a per-run path when the project already uses that convention.
Procfile vs Procfile.dev: production and development Procfiles often differ. Always prefer Procfile.dev for polish.
Multiple web processes: some Procfiles split web traffic across multiple processes (API + frontend). Polish can only open one URL — users with multi-web setups should author .claude/launch.json explicitly to select which process is "the dev server" for polish.

Raw lines 55 to 59