A terminal-first process manager for running and maintaining multiple Node services from one place.
Note: Don't forget to replace this placeholder with a GIF or screenshot of your tool in action! (Place it in the
assetsfolder)
Prozessor is a lightweight terminal process manager. Instead of juggling multiple terminal tabs, it lets you manage all your project repositories from a single Live TUI Dashboard.
It handles cloning, branch tracking, log streaming, and process monitoring automatically.
- 🔄 Automated Git Ops: Auto-clones your project repos and periodically checks for branch updates.
- 📊 Live TUI Dashboard: Monitor all your services in one terminal window with multiplexed log streaming.
- 🛡️ Resilient: Whole-tree process shutdown, automatic port reclamation (pre-start, on
EADDRINUSE, and across sessions), crash retries, and cooldown periods keep your services healthy and ports clean. - 🪶 Lightweight: Plain Node.js (ESM), zero build steps, and no heavy dependencies.
Follow these steps to set up and run it on your machine.
Ensure you have the following installed on your system:
- Node.js:
v18+ - Git: Required for cloning and managing repositories.
Clone PROZESSOR to your local machine and install its dependencies:
git clone https://github.com/SiddDevZ/prozessor-cli.git
cd prozessor-cli
npm installYou need to tell it which projects to manage. We provide a safe template to start with. Run the following command to create your local config file:
cp projects.example.json projects.jsonOpen projects.json in your editor and define your repositories.
If your managed projects require .env files, you can store them securely in the envs/ directory.
- Create your env files (e.g.,
envs/.env.myproject). - Link them in your
projects.jsonby setting theenvSrcproperty for that project.
Start the process manager to bring up the dashboard and spawn your services:
npm startEach project entry in your projects.json supports the following:
| Property | Description | Default |
|---|---|---|
name |
Display key and local folder name (created under projects/) |
- |
repoUrl |
Git remote URL to clone from | - |
branch |
Branch to track and auto-update | - |
envSrc |
Env filename inside the envs/ folder (Optional) |
- |
subdir |
Project subdirectory where the Node service lives | backend |
entrypoint |
Node entry file to run | server.js |
command |
Shell command to run instead of node <entrypoint>, e.g. npm run dev. Spawned in its own process group, so shutdown still reaps the whole tree (Optional) |
- |
installCmd |
Install command run before start and after every update. Override it when the project needs its devDependencies (Optional) | npm install --production --silent |
resetOnUpdate |
On update, hard-reset to the tracked branch instead of stashing local changes. Use it for projects that rewrite their own tracked files at runtime. Gitignored paths (node_modules/, caches, browser profiles) are preserved (Optional) |
false |
port |
Port the service listens on. When set, Prozessor reclaims this port before (re)starting so a stale process can never block a fresh start (Optional) | auto-detected |
enabled |
Whether it should manage this project | true |
Global Application Settings:
pollInterval: How often to check for git updates.logBufferSize: Number of log lines to keep in memory.maxCrashRetries: How many times to restart a crashing process.autoUpdateCli: Automatically fetch and update the CLIcrashCooldownMins: Cooldown duration after exceeding max retries.
PROZESSOR watches projects.json while it runs (a directory watcher plus a 2 s mtime check as a fallback), so you can edit it in place or replace it with write-temp-then-rename. When the file changes, it is diffed against the running config by project name:
- New project (or
enabledflipped totrue): cloned, env copied,installCmdrun, then started. - Removed project: its whole process tree is stopped, it drops out of the dashboard and stops being polled. The cloned folder under
projects/is kept. enabled: false: stopped and no longer polled, but still listed.- Any other field changed (
branch,command,port,envSrc, ...): re-prepared with the new config, then restarted. - Unchanged projects are not touched.
Settings apply live too: pollInterval resets the git poll timer, logBufferSize resizes the buffers, and maxCrashRetries / crashCooldownMins are read on each crash. autoUpdateCli only takes effect on the next start.
A file that is empty, half written, not valid JSON, missing a projects array, or has a project without a name (or a duplicate name) is ignored with one warning in the PROZESSOR log, and nothing that is running changes. Fix the file and the next save is picked up. Changing repoUrl of an already cloned project re-points the existing checkout: the new URL's branch is fetched and the checkout is hard reset onto it (local changes in that folder are discarded, histories may be unrelated), then origin is updated and the project restarts. The same happens when a project is added or enabled and its kept folder points at a different repo. This only happens on a reload, never at startup. Edits made while PROZESSOR is still starting up are applied as soon as the initial start finishes. PROZESSOR's own saves (from the menu) are written atomically too.
Every log line PROZESSOR shows for a project is also appended to logs/<name>.log (plain text, ANSI codes stripped, one line per entry as <ISO time> OUT|ERR <text>). Each file rotates to logs/<name>.log.1 at about 2 MB, so a project never uses more than ~4 MB. PROZESSOR's own messages go to logs/PROZESSOR.log. Characters other than letters, digits, ., _ and - in a name become _ in the file name.
.prozessor-status.json in the root is rewritten atomically (temp file + rename) whenever a project's state changes, and re-checked every 5 s:
{
"updatedAt": "2026-10-12T10:00:00.000Z",
"pid": 4242,
"projects": {
"my-project": {
"enabled": true,
"status": "running",
"pid": 4301,
"port": 3000,
"restarts": 2,
"lastStart": "2026-10-12T09:58:41.120Z",
"lastExit": { "code": 1, "signal": null, "at": "2026-10-12T09:58:38.002Z" },
"commit": "a1b2c3d"
}
}
}pid(top level): the PROZESSOR process that wrote the file. If it is no longer alive, the file is stale.status:starting(cloning / installing before the first spawn),running,restarting(update or config change in progress),crashed(waiting 3 s to retry),cooldown(too many crashes, paused forcrashCooldownMins), orstopped.pid: the project's process (group leader) whilerunning, elsenull.port: configured or detected port, elsenull.restarts: spawns since PROZESSOR started, minus the first one (crash retries, updates and config restarts all count).lastStart/lastExit: ISO times,nulluntil it has happened.lastExit.code/lastExit.signalare what the process exited with.commit: short sha checked out when the process was last spawned,nullif unknown.
Only projects in the current projects.json are listed. Both logs/ and .prozessor-status.json are gitignored.
Navigate your services effortlessly using these built-in keyboard shortcuts:
| Key | Action |
|---|---|
m |
Open the management menu |
f |
Cycle through project log filters |
0 |
Clear active log filter |
1-9 |
Quick-filter to a specific project by index |
↑ / ↓ / PgUp / PgDn |
Scroll through the log history |
q / Ctrl+C |
Quit and gracefully shut down all services |
prozessor/
├── lib/
│ ├── config.js
│ ├── hot-reload.js
│ ├── status-file.js
│ ├── git-ops.js
│ ├── process-manager.js
│ ├── port-utils.js
│ ├── state-store.js
│ ├── log-store.js
│ ├── theme.js
│ ├── ui.js
│ └── flair.js
├── envs/
│ └── .env.example
├── projects/ # Managed repositories are cloned here
├── main.js # Application Entrypoint
├── projects.json # Your local configuration
├── .prozessor-state.json # Runtime state for cross-session cleanup (gitignored)
├── .prozessor-status.json # Live per-project status for other tools (gitignored)
├── logs/ # Persisted per-project logs (gitignored)
├── package.json
└── .gitignore
For a clean and secure public release, ensure you:
- Never commit real
.envfiles to github. - Never commit your populated
projects.json. - Never commit the cloned repositories under the
projects/directory.
(These paths are already ignored in .gitignore by default).
(Add your preferred license before publishing)
