Lookout

Lookout is a small PM2 control room for local repos. It reads your existing ecosystem.config.*, shows running processes and package scripts in a focused dashboard, and gives you quick actions for status, logs, restart, start, and stop.

The npm package is lookout-hq; the installed command is lookout.

Install

npm install -g lookout-hq

Or run it without a global install:

npx lookout-hq serve --port 8790

Requirements

• Node.js 20 or newer
• PM2 available globally or in your repo's node_modules/.bin
• An ecosystem.config.cjs, ecosystem.config.js, or ecosystem.config.mjs file in the repo you want to manage

Quick Start

From a repo that has a PM2 ecosystem file:

lookout start
lookout status
lookout serve --port 8790

Then open:

http://127.0.0.1:8790

Commands

lookout serve --port 8790
lookout start [task...]
lookout stop [task...]
lookout restart [task...]
lookout status
lookout logs [task...]
lookout doctor

start, stop, restart, and logs are PM2-backed commands. If task names are provided, Lookout targets only those PM2 apps. Without task names, it uses the repo ecosystem file or all PM2 apps where that matches PM2 behavior.

Dashboard

The dashboard is served by the CLI and includes:

• repo-first process overview
• PM2 process table with state, PID, CPU, memory, uptime, and restarts
• package script discovery from local package.json files
• linked PM2 process actions
• modal log viewer
• light and dark mode

Linking Scripts To Processes

Lookout can connect package scripts to PM2 apps when you add LOOKOUT_PACKAGE and LOOKOUT_SCRIPT to the app's PM2 environment.

module.exports = {
  apps: [
    {
      name: "web",
      cwd: "apps/web",
      script: "pnpm",
      args: "dev",
      env: {
        LOOKOUT_PACKAGE: "web",
        LOOKOUT_SCRIPT: "dev",
      },
    },
  ],
};

This lets the dashboard show which package script owns a process and which scripts are unmanaged.

Development

Inside this repo:

pnpm --filter lookout-hq dev
pnpm --filter lookout-hq package:local

The package is built with Vite+:

• vp build builds the React dashboard into ui/dist
• vp pack bundles the Node CLI into dist/cli.mjs
• vp pm pack creates a local npm tarball

Notes

Lookout intentionally uses PM2 and the ecosystem file as the source of truth. It does not maintain a second process config format.