Add --debug flag for verbose server logging

[jbingham17]

Summary

• Adds a --debug CLI flag to the server that enables timestamped debug logging
• Logs incoming requests, CPU/memory collection, and process fetching when enabled
• Adds server:debug and start:debug npm scripts for convenience

Usage

bun run server:debug     # Server only with debug logging
bun run start:debug      # Full app with debug logging
bun run server/index.ts --debug  # Direct usage

Test plan

• Run bun run server and verify no debug output appears
• Run bun run server:debug and verify debug logs with timestamps appear on each request
• Hit /api/metrics and confirm request + metrics collection logs appear

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added debug mode that provides detailed logging of server operations, including CPU usage collection, process retrieval, system metrics gathering, and HTTP request details, for enhanced visibility during development and troubleshooting.

• Chores

  • Introduced new npm scripts to simplify activating debug mode alongside standard development workflows.

[coderabbitai]

📝 Walkthrough

Walkthrough

A debug mode feature is added via a new --debug command-line flag in the server with conditional logging at key data-collection points. Two npm scripts (server:debug and start:debug) are introduced to facilitate running the server in debug mode.

Changes

Cohort / File(s)	Summary
Debug Mode Workflow package.json	Added server:debug and start:debug npm scripts to enable concurrent debugging alongside development.
Debug Logging Implementation server/index.ts	Added --debug CLI flag parsing, global DEBUG flag, debug banner on startup, and conditional debug logs at CPU collection, process retrieval, system metrics collection, and request handling points.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add --debug flag for verbose server logging' directly and accurately summarizes the main change: adding a debug flag for logging purposes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Min-Level	✅ Passed	Debug flag implementation is secure by default (requires explicit --debug argument) and logs only non-sensitive HTTP method/path and process metrics.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch add-debug-flag

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

server/index.ts (1)

17-19: Use the debug helper for the startup banner.

Line 18 is the only debug log that skips the timestamped format. Sending it through debug() keeps the output consistent with the rest of the flag behavior.

Suggested diff

-if (DEBUG) {
-  console.log("🐛 Debug mode enabled");
-}
+debug("Debug mode enabled");

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@server/index.ts` around lines 17 - 19, Replace the console.log call that
prints the startup banner when DEBUG is true with the debug() helper to keep
timestamped/consistent logging; locate the DEBUG check in server/index.ts and
change the usage of console.log("🐛 Debug mode enabled") so it calls debug("🐛
Debug mode enabled") instead, preserving the existing conditional and message
content.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@server/index.ts`:
- Around line 17-19: Replace the console.log call that prints the startup banner
when DEBUG is true with the debug() helper to keep timestamped/consistent
logging; locate the DEBUG check in server/index.ts and change the usage of
console.log("🐛 Debug mode enabled") so it calls debug("🐛 Debug mode enabled")
instead, preserving the existing conditional and message content.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 73d5708e-e38d-4f5a-8661-2cd97c6cf71b

📥 Commits

Reviewing files that changed from the base of the PR and between 0e7262e and 71b8c2f.

📒 Files selected for processing (2)

• package.json
• server/index.ts

📜 Review details

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2026-02-18T05:07:00.671Z

Learnt from: jbingham17
Repo: coderabbit-demo/btop PR: 8
File: src/types.ts:32-32
Timestamp: 2026-02-18T05:07:00.671Z
Learning: In the coderabbit-demo/btop repository, avoid inline comments on TypeScript interface properties. Ensure property types are self-documenting through clear names and interface structure. If a property requires explanation, document it above the interface or with JSDoc comments for the property, not inline on the same line.

Applied to files:

• server/index.ts

🔇 Additional comments (2)

package.json (1)

9-11: LGTM.

These scripts expose the debug path cleanly without changing the default server / start behavior.

server/index.ts (1)

65-65: Good debug signal placement.

These hooks give useful breadcrumbs around request handling and the expensive metrics/process collection path while staying fully gated behind DEBUG.

Also applies to: 110-110, 147-147, 249-249, 285-285