Onboarding: remy/nodemon

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/remy/nodemon shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across all four use cases

• Last commit 6d ago
• 5 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 94% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live remy/nodemon repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/remy/nodemon.

What it runs against: a local clone of remy/nodemon — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in remy/nodemon | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 36 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>remy/nodemon</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of remy/nodemon. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/remy/nodemon.git
#   cd nodemon
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of remy/nodemon and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "remy/nodemon(\\.git)?\\b" \\
  && ok "origin remote is remy/nodemon" \\
  || miss "origin remote is not remy/nodemon (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "lib/nodemon.js" \\
  && ok "lib/nodemon.js" \\
  || miss "missing critical file: lib/nodemon.js"
test -f "lib/monitor/index.js" \\
  && ok "lib/monitor/index.js" \\
  || miss "missing critical file: lib/monitor/index.js"
test -f "lib/config/index.js" \\
  && ok "lib/config/index.js" \\
  || miss "missing critical file: lib/config/index.js"
test -f "bin/nodemon.js" \\
  && ok "bin/nodemon.js" \\
  || miss "missing critical file: bin/nodemon.js"
test -f "lib/cli/parse.js" \\
  && ok "lib/cli/parse.js" \\
  || miss "missing critical file: lib/cli/parse.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 36 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~6d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/remy/nodemon"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

nodemon is a CLI tool that automatically restarts a Node.js application whenever files in the working directory change, eliminating manual restart cycles during development. It wraps the standard node command and passes all arguments transparently to your script, while monitoring the filesystem via chokidar and using pstree for process tree management. Core capability: zero-config file watching with intelligent process lifecycle management for Node.js servers and CLIs. Modular CLI structure: bin/nodemon.js is entry point, routes to lib/cli/index.js (main CLI handler) → lib/cli/parse.js (argument parsing). Config system lives in lib/config/ (load.js handles nodemon.json and package.json, command.js and exec.js build the spawn command). Watch/restart loop is decoupled from CLI—lib/nodemon is the core programmatic API. No external web server or UI; doc/cli/ contains help text templates.

Who it's for

Node.js developers (backend, full-stack, DevOps) working on servers, APIs, and CLIs who want to skip manual restart commands during active development. Used by teams building Express servers, Next.js backends, and other Node applications where tight feedback loops matter.

Maturity & risk

Highly mature and production-ready: widely adopted (see npm badge in README), uses semantic versioning with automated release pipeline (.releaserc, GitHub Actions workflows), has comprehensive test suite (test/**/*.test.js with 30-second timeouts), and active CI/CD (node.js.yml, release.yml workflows). Single maintainer (Remy Sharp) but well-established (years old, stable API, solid documentation).

Low risk for a development tool. Dependency tree is lean (chokidar, debug, minimatch, pstree.remy, semver, touch, undefsafe) with no heavy transitive dependencies. Key risk: single maintainer (Remy Sharp), so adoption roadblocks depend on one person's availability. Platform-specific concerns: includes windows-kill.exe binary and Dockerfile for portability, but Windows subprocess handling is complex. No obvious breaking changes visible in version string (0.0.0-development is semantic-release placeholder).

Active areas of work

Active maintenance visible in GitHub Actions workflows (node.js.yml runs on commits, release.yml handles semantic versioning). Project uses commitlint (commitlint.config.js) and husky for enforced conventional commits, suggesting active governance. TypeScript type definitions (index.d.ts) indicate effort to maintain type safety for programmatic users. No breaking changes or major rewrites apparent; incremental improvements are mode.

Get running

git clone https://github.com/remy/nodemon.git
cd nodemon
npm install
npm test

Then to use locally: npx nodemon ./your-app.js. To install globally: npm install -g nodemon (or use yarn global add nodemon).

Daily commands:

# Local development
npm run lint          # ESLint validation
npm run spec          # Full test suite (runs each test file sequentially)
npm run coverage      # Istanbul coverage report

# For end users
nodemon ./app.js      # Watch and restart app.js
nodemon --help        # Show CLI options

Dev server: there is no dev server; nodemon is a CLI tool. Run your own Node.js app via nodemon.

Map of the codebase

• lib/nodemon.js — Main entry point that orchestrates the entire nodemon lifecycle and exports the public API
• lib/monitor/index.js — Core monitor loop that watches files, detects changes, and triggers application restarts
• lib/config/index.js — Configuration loading and merging—every session depends on understanding how settings are resolved
• bin/nodemon.js — CLI entry point that parses arguments and initializes nodemon from the command line
• lib/cli/parse.js — Command-line argument parser that interprets user inputs into configuration objects
• lib/spawn.js — Child process spawning and lifecycle management—critical for restarting the target application
• lib/monitor/watch.js — File system watcher integration that detects file changes and triggers restart logic

Components & responsibilities

• CLI (bin/nodemon.js + lib/cli/) (Node.js Process, minimist-style parsing) — Parse command-line arguments, display help, and invoke the monitor
  • Failure mode: Fails to parse args → error message; cannot start monitor
• Configuration (lib/config/) (File I/O, JSON parsing) — Load, merge, and resolve all config sources (CLI, nodemon.json, package.json, defaults)
  • Failure mode: Missing or malformed config → defaults apply or explicit error
• Monitor (lib/monitor/index.js) (EventEmitter, process signals) — Orchestrate the watch→detect→restart loop; manage lifecycle and event emission
  • Failure mode: Monitor crashes → entire nodemon exits; watch stops
• Watch (lib/monitor/watch.js) (chokidar, fs.watch, path globbing) — Detect file system changes using chokidar or native watch
  • Failure mode: Watch fails → changes not detected; restarts won't trigger
• Spawn (lib/spawn.js) (Child process, process signals) — Create and manage target application child process; forward signals and stdio
  • Failure mode: Spawn fails → app won't start; cannot handle signals cleanly
• Rules (lib/rules/) (Glob patterns, minimatch-style matching) — Parse and match file patterns against ignore/watch rules
  • Failure mode: Rule mismatch → unwanted files watched or necessary files ignored

How to make changes

Add a new CLI option

1. Define the option in the parser grammar (lib/cli/parse.js)
2. Add the option to defaults if it has a default value (lib/config/defaults.js)
3. Implement option handling in the monitor or config layer (lib/monitor/index.js)
4. Add tests for the new option (test/cli/parse.test.js)

Add a new file-matching rule type

1. Extend the rule parser to recognize the new rule syntax (lib/rules/parse.js)
2. Implement matching logic in the match module (lib/monitor/match.js)
3. Test rule matching against sample files (test/config/load.test.js)

Add a new event hook or lifecycle event

1. Emit the event from the appropriate monitor or spawn handler (lib/monitor/index.js)
2. Document the event in the event bus documentation (doc/events.md)
3. Add test for the event emission (test/events/complete.test.js)

Add support for a new restart condition or trigger

1. Add the trigger detection logic to the watch module (lib/monitor/watch.js)
2. Integrate with the restart logic in run.js (lib/monitor/run.js)
3. Add configuration options if user control is needed (lib/config/defaults.js)

Why these technologies

• EventEmitter (Node.js built-in) — Decouples monitor, watch, and spawn components; allows plugins to hook lifecycle events
• chokidar (file watcher fallback) — Provides cross-platform, efficient file watching with proper debouncing and ignore patterns
• Minimist-style argument parsing — Lightweight, low-dependency CLI parsing suitable for a development tool
• Child process (Node.js spawn/fork) — Enables clean process isolation and signal management for restarting target applications

Trade-offs already made

• No built-in TypeScript support; relies on external ts-node or tsc wrapper

  • Why: Keeps nodemon lightweight and language-agnostic; users can wrap with the tool they prefer
  • Consequence: Users must configure ts-node separately; slightly more setup friction but maximum flexibility

• Synchronous file-system operations in config loading

  • Why: Config must be resolved before any async work starts; keeps initialization logic simple
  • Consequence: Config load blocks startup but only happens once; acceptable for development workflow

• Debouncing restarts using a fixed delay rather than event aggregation

  • Why: Simple to understand and predictable; avoids complex state machines
  • Consequence: Slightly slower restart on rapid file changes, but more reliable and easier to debug

Non-goals (don't propose these)

• Does not manage application dependencies or modules; only restarts the process
• Does not provide clustering or load balancing; single process per nodemon instance
• Does not handle authentication, authorization, or secure environments
• Does not provide real-time code transformation; must be paired with external tools (Babel, TypeScript, etc.)
• Does not support Windows batch files natively; requires explicit executable specification

Traps & gotchas

Glob patterns: uses minimatch, not shell globbing—**/*.js behaves differently in CLI vs .nodemonignore; test both. Process trees: on Unix, nodemon uses pstree.remy to kill child processes; windows-kill.exe binary must be present for Windows—if missing, child processes may not die. Config precedence: .nodemonignore > package.json > nodemon.json > CLI flags; surprising order if you expect CLI-first. Exit codes: nodemon preserves exit code of the spawned process, but wraps errors with [nodemon] prefix—grep-based CI detection may break. SIGTERM handling: nodemon forwards SIGTERM to child but may not exit immediately; race condition possible in test suites with tight timeouts (note: tests use 30-second timeout in package.json scripts). CoffeeScript/legacy: repo includes coffee-script in devDependencies but newer versions drop it—be aware if modifying build tooling.

Architecture

Concepts to learn

• Process Tree Management — nodemon must kill not just the spawned node process but its entire subtree (child processes) when restarting; pstree.remy handles this, and understanding process trees is essential for debugging hung child processes
• File System Watching (via chokidar) — Core to nodemon's responsiveness; chokidar abstracts OS differences (inotify on Linux, FSEvents on macOS, ReadDirectoryChangesW on Windows) and must debounce rapid changes—understanding watch latency is critical for performance tuning
• Glob Pattern Matching (via minimatch) — nodemon's --watch, --ignore, and .nodemonignore use minimatch globs, not shell globbing; misunderstanding negation patterns (!) or ** recursion causes unexpected behavior
• Signal Handling (SIGTERM, SIGINT, SIGHUP) — nodemon must forward OS signals to child processes correctly and handle graceful shutdown; improper signal forwarding breaks cleanup in applications expecting SIGTERM
• Configuration Precedence & Cascading — nodemon resolves config from multiple sources (.nodemonignore, package.json, nodemon.json, CLI flags) with a defined order; misunderstanding precedence causes unexpected defaults or silent flag ignoring
• Semantic Versioning & Automated Release — nodemon uses semantic-release with commitlint (enforce conventional commits) to automate versioning—understanding this workflow is essential for contributing (breaking changes require BREAKING CHANGE: footer)

Related repos

• paulmillr/chokidar — The filesystem watcher library nodemon depends on; understanding chokidar's events and options is key to debugging watch behavior
• evanw/esbuild — Modern alternative for rapid iteration: esbuild with --watch can rebuild TypeScript/JSX, often used alongside nodemon in the same dev loop
• remy/nodemon.io — Official website and documentation source; separate repo for the nodemon.io homepage and CLI help templates
• node-dev/node-dev — Older competing tool with similar goals (auto-restart on file change); historical alternative showing design trade-offs in watch logic
• tj/supervisor — Predecessor supervisor tool; nodemon was written partly as a response to supervisor's limitations, historical context for design decisions

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for lib/config/load.js

The config loading logic is critical to nodemon's functionality but currently lacks dedicated unit tests. The test suite has test/**/*.test.js files but no specific tests for the configuration loading flow that handles nodemon.json, package.json config merging, and defaults application. This would improve reliability of configuration handling across different environments.

• [ ] Create test/config/load.test.js with test cases for nodemon.json parsing
• [ ] Add tests for package.json config extraction and merging with lib/config/defaults.js
• [ ] Add edge cases: missing config files, invalid JSON, conflicting configurations
• [ ] Test override precedence: CLI args > nodemon.json > package.json > defaults
• [ ] Run npm run coverage to ensure new tests are included in coverage reporting

Add GitHub Actions workflow for testing on Windows

The repo has .github/workflows/node.js.yml for general testing but nodemon has Windows-specific code (bin/windows-kill.exe, Windows signal handling in lib/monitor/signals.js). Currently there's no Windows-specific CI testing. Adding a Windows test matrix would catch platform-specific bugs early and ensure the Windows process termination logic works correctly.

• [ ] Create .github/workflows/windows-test.yml with windows-latest runner
• [ ] Configure Node.js matrix (matching node: '>=10' engine requirement)
• [ ] Run npm run lint and npm run spec with shell: pwsh for Windows
• [ ] Test Windows-specific paths: verify bin/windows-kill.exe functionality
• [ ] Add Windows to existing CI badge/status checks in README.md if applicable

Add TypeScript declaration tests for index.d.ts

The repo exports index.d.ts for TypeScript support, but there are no tests verifying the type definitions match the actual API. This can lead to type definition drift where the .d.ts file becomes out of sync with lib/nodemon.js and lib/index.js. Adding dtslint or similar tests would ensure type safety for TypeScript users.

• [ ] Create test/types/nodemon.test.ts with tsc type-checking tests
• [ ] Test exported interfaces: NodemonOptions, NodemonAPI from index.d.ts
• [ ] Verify method signatures match lib/nodemon.js exports (events, configure, etc.)
• [ ] Add 'typecheck' script to package.json to run tsc --noEmit on test/types
• [ ] Integrate typecheck into npm test script alongside lint and spec

Good first issues

• Add missing tests for lib/config/command.js: command.js builds the exec command but has no dedicated .test.js file; writing tests here would improve coverage and help someone understand config assembly
• Document --exec override behavior in doc/cli/options.txt: options.txt exists but is a stub; adding examples of --exec (e.g., --exec 'coffee' or --exec 'deno run') would clarify a powerful but under-documented feature
• Add integration test for .nodemonignore glob patterns in test/: Current tests may not cover edge cases like negation patterns (!) or ** wildcards; adding test/ignore.test.js would prevent regressions and document expected behavior

Top contributors

• @remy — 94 commits
• @claude — 3 commits
• @zAlweNy26 — 1 commits
• @ani3llyon — 1 commits
• @ChristophP — 1 commits

Recent commits

• fd5c113 — chore: website (remy)
• 1d0a639 — docs: standardize on 'i.e.' form (claude)
• 16acdae — docs: fix grammar mistakes in documentation (claude)
• 8abe43c — docs: fix spelling mistakes and typos in documentation (claude)
• 32533b5 — chore: website (remy)
• cbecce4 — chore: website (remy)
• 39a0b19 — chore: website (remy)
• 8608355 — chore: website (remy)
• 8c21cdc — chore: website (remy)
• 513f289 — chore: website (remy)

Security observations

The nodemon codebase has moderate security

• High · Outdated Ubuntu Base Image in Dockerfile — Dockerfile (line 8: FROM ubuntu:16.04). The Dockerfile uses Ubuntu 16.04, which reached end-of-life on April 30, 2021. This image no longer receives security updates and patches, exposing the container to known vulnerabilities. Fix: Update to a supported Ubuntu LTS version (e.g., 20.04 or 22.04) or use an official Node.js base image (e.g., node:18-alpine or node:20-bullseye).
• High · Insecure Node.js Version Installation — Dockerfile (lines 15-16) and package.json (engines field). The Dockerfile installs Node.js 10.x via NodeSource setup script. Node.js 10.x reached end-of-life on April 30, 2021, and no longer receives security updates. The package.json specifies engines: node >=10, which allows very old versions. Fix: Update Node.js setup to a supported LTS version (>=18.0.0 or >=20.0.0). Update package.json engines field to reflect minimum supported version: '>=18.0.0'.
• Medium · Outdated Development Dependencies — package.json (devDependencies). Several devDependencies are significantly outdated: mocha@2.5.3 (released 2015), coffee-script@1.7.1 (unmaintained), and async@1.4.2 (outdated). These may contain unpatched vulnerabilities and lack modern security features. Fix: Update to latest stable versions: mocha (latest), remove coffee-script if unused, upgrade async to current version. Run 'npm audit' and address findings.
• Medium · Potential Command Injection in npm Scripts — package.json (scripts.killall). The 'killall' script uses shell pipes and grep/awk without proper quoting: ps auxww | grep node | grep -v grep | awk '{ print $2 }' | xargs kill -9. This could be exploited if process names are manipulated. Fix: Replace with safer alternatives: 'pkill -f node' or use a proper Node.js process manager. Avoid xargs with kill commands; use 'pkill' or 'killall' with explicit process names.
• Medium · Insecure curl Usage in Dockerfile — Dockerfile (line 15). The Dockerfile uses curl to pipe directly to bash without verification: curl --silent --location https://deb.nodesource.com/setup_10.x | bash -. This is a known security anti-pattern vulnerable to MITM attacks. Fix: Use official Node.js Docker images instead, or download and verify the script hash before execution. Alternatively, manually install Node.js from verified sources.
• Low · Missing .npmrc Security Configuration — .npmrc. The .npmrc file exists but content is not provided. If it contains authentication tokens or credentials, it could pose a security risk if committed or exposed. Fix: Ensure .npmrc is in .gitignore and never contains hardcoded credentials. Use npm token authentication with environment variables in CI/CD pipelines.
• Low · Executable Binary in Repository — bin/windows-kill.exe. The file bin/windows-kill.exe is a compiled binary committed to the repository. This makes it difficult to audit and verify its contents. Fix: Consider removing the binary and either building it during installation or sourcing it from a trusted external package. If kept, document its purpose and provide source code.
• Low · Minimatch Dependency with Known Issues — package.json (dependencies: minimatch). The minimatch@10.2.1 dependency is a critical glob matching library. Ensure it's regularly updated as ReDoS (Regular Expression Denial of Service) vulnerabilities have been found in glob/minimatch libraries historically. Fix: Regularly run 'npm audit' and update minimatch promptly when security patches are released. Consider using 'npm ci' for deterministic installs.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.