🏰 Nightwatch

"The night is dark and full of bugs."

An AI observability sidecar for local development. Prefix any service command with nightwatch post -- and an AI watches its logs in real time — it flags errors, N+1 queries, and slow requests as they happen, keeps a searchable archive of every session, and answers questions with full context. No changes to your app. No cloud requirement. No database.

npm install -g @hari-7501/nightwatch
cd your-project
nightwatch post -- npm start        # that's it — dashboard opens automatically

Quickstart (30 seconds)

1. Install — pick whichever fits:

npm install -g @hari-7501/nightwatch       # global: the `nightwatch` command everywhere
npx @hari-7501/nightwatch tower            # zero-install trial, nothing saved globally
npm i -D @hari-7501/nightwatch             # per-project: use via `npx nightwatch ...`

2. Run your service through it — from your project folder, prefix your normal start command:

nightwatch post -- npm run dev                      # Node
nightwatch post -- python -m uvicorn main:app       # Python
nightwatch post -- rails server                     # Ruby
nightwatch post -- go run main.go                   # Go
nightwatch post -- ./mvnw spring-boot:run           # Java
nightwatch post -- <anything that prints>           # everything else

Your service runs exactly as normal. The dashboard starts itself in the background at http://localhost:4000 — one terminal is enough.

3. First run only: you'll be asked for an OpenRouter API key (free tier available; the key is tested before it's saved). No key? Just press Enter — everything except the AI still works (capture, dashboard, archive, search).

Don't have a service handy? Watch it catch real trouble in 30 seconds:

nightwatch demo

What you get

| | | |---|---| | Ravens Log | Live, color-coded stream of everything your service prints — plus every .log file in the project, captured automatically and interleaved by time, and browser errors from frontend apps via the Beacon. Filter by text, errors, or source. | | Scrolls | AI watchman reports — errors diagnosed, N+1 queries spotted, slow requests flagged, failed API calls (4xx/5xx — your Postman tests) debugged from the response body, each rated Severity: N/10 on a severity timeline. Critical ones fire a desktop notification. AI can be woken or muted per service, independent of the global toggle. | | Counsel | Chat with an AI that was watching the whole time — no copy-pasting logs. Saw your requests through the Gate? Ask for a runnable curl to reproduce any of them. Works on archived sessions too; quoted log lines click through to the live log. | | The Crypt | Every session archived and searchable (⌘K in the dashboard, nightwatch seek in the terminal). The watchman remembers: "this error appeared in 4 past sessions." | | Settings & Metrics | Everything configurable from the dashboard's ⋮ menu — applied live, saved to one config file. Global Metrics shows usage charts and an AI summary of your day. |

Backend, frontend, anything

Anything that prints to a terminal can stand a post — backend, frontend dev server, worker, CLI, cron script. For frontend apps the terminal only shows build output, so Nightwatch adds the Beacon: a tiny script that forwards browser console errors, unhandled promise rejections, and failed network calls into the same session.

nightwatch post --name my-app -- npm run dev    # capture the dev server (build errors, HMR, crashes)
nightwatch gate --target 5173 --name my-app     # then browse via http://localhost:8888

The Gate injects the Beacon into every HTML page it proxies (WebSockets pass through, so HMR keeps working) — browser errors land in the Ravens Log as [browser:error] lines and the watchman reads them like any other error. No proxy? nightwatch beacon prints a one-line <script> tag to drop into your dev HTML instead.

Philosophy

1. Zero prerequisites. Node 18+ is the only requirement — no database, no Docker, no accounts. Works on macOS, Linux, and Windows.
2. One-time setup. One install command, one API-key prompt (validated, then never asked again). Skippable entirely.
3. Conventional defaults. Everything works out of the box; everything is overridable via nightwatch orders --set key=value.
4. Easy updates. nightwatch update brings you to the latest version; a quiet once-a-day notice tells you when one exists. Your config and archives survive every upgrade.
5. Zero coupling. Your app never knows Nightwatch exists. Remove the prefix and nothing changes.
6. Trust by default. Secret redaction is one toggle away in Settings (JWTs, keys, passwords, cards blanked before disk). The dashboard binds to localhost only. Token spend is always visible, cappable, and you can point it at a local model so nothing leaves your machine.

Commands

nightwatch post -- <cmd>        # watch a service (auto-starts the dashboard)
nightwatch demo                 # training yard — see the AI catch an N+1, a 500, a crash
nightwatch tower [--stop]       # start / stop the dashboard manually
nightwatch patrol --file x.log  # attach existing log files (nginx, db, workers)
nightwatch gate --target 3000   # network interceptor (req/res + failure bodies → logs, Beacon into HTML)
nightwatch beacon               # print the browser-capture snippet for frontend apps
nightwatch speak                # chat with the watchman from the terminal
nightwatch seek "<query>"       # search everything, active + archived
nightwatch status               # tower, posts, today's AI usage at a glance
nightwatch roster / scrolls     # list active / archived sessions
nightwatch dismiss              # stop watching a service
nightwatch orders               # view / change config from the terminal
nightwatch version              # current version + update check
nightwatch update               # update to the latest version

Search syntax (for seek and the dashboard's ⌘K): service:backend in:context|suggestions|chat severity:7 after:10:30 date:2026-06-10 "free text"

Configuration

Everything is editable in the dashboard — ⋮ menu → ⚙ Settings — and applies immediately, even to services already being watched. Settings are stored at ~/.devwatch/config.json (versioned, auto-migrated on upgrades), so the terminal works on the same data: nightwatch orders --set key=value.

| Key | Default | Description | |-----|---------|-------------| | model | anthropic/claude-sonnet-4-6 | Any model on OpenRouter (or your local endpoint) | | base_url | OpenRouter | Any OpenAI-compatible endpoint — Ollama, LM Studio | | sweep_interval | 60 | Seconds between scheduled AI sweeps (idle services cost nothing) | | severity_threshold | 6 | Only keep AI reports rated this or higher | | notify_threshold | 8 | Desktop notification at this severity and above | | dashboard_port | 4000 | Dashboard port (binds localhost only) | | archive_ttl_days | 30 | Archives older than this are pruned | | ai | true | Logs-only mode when false | | redact | false | Secret scrubbing — enable in ⚙ Settings | | track_services | true | Remember every service you run (powers Global Metrics) | | beacon_inject | true | Gate injects the browser Beacon into proxied HTML pages | | daily_token_cap | 0 | Pause AI (never logging) after this many tokens/day | | rules | [] | Your own triggers: [{"match":"payment failed","severity":9,"notify":true}] |

Fully local AI: nightwatch orders --set base_url=http://localhost:11434/v1 model=llama3.3 and no data ever leaves your machine.

Updating

nightwatch update        # or: npm install -g @hari-7501/nightwatch@latest

Nightwatch checks the registry quietly once a day and prints a one-line notice when a newer version exists — it never blocks, nags, or phones home with anything else. Config and archives are forward-compatible by design.

Deep documentation

The README is the quickstart; power users start here:

• docs/SPEC.md — master spec: architecture, full feature map, config reference, design principles, roadmap
• docs/specs/cli.md — every command in detail
• docs/specs/sessions.md — file formats, redaction, archive index (all plain files — grep them, script against them)
• docs/specs/engine.md — triggers, rules, cross-session memory, cost ledger
• docs/specs/dashboard.md — the HTTP API + UI reference
• docs/specs/search.md — query syntax and internals

Requirements

| Tool | Version | |------|---------| | Node.js | 18+ |

That's the whole list. If your Node is older, Nightwatch tells you plainly instead of stack-tracing.

Troubleshooting: port taken → nightwatch orders --set dashboard_port=4001 · key issues → nightwatch orders shows a masked view · all data lives in ~/.devwatch/ as plain text — when in doubt, look inside.

License

MIT

Built for developers who refuse to be surprised by their own code. And now their watch begins.