Firewatch Laravel Package

Getting Started

Firewatch v1.0.0 is the initial release, so there is no upgrade path or migration to worry about — but it also means the public surface (config keys, artisan command names, MCP tool names) has no stability history yet. Pin it ("claudiodekker/firewatch": "^1.0") rather than tracking dev-main, and re-read the README on each minor bump.

Minimal path to first value:

1. composer require claudiodekker/firewatch in a local environment. Laravel package discovery should register the service provider; check bootstrap/providers.php if you're on a non-standard skeleton.
2. Publish and review the config (php artisan vendor:publish --tag=... — the README lists the exact tag, which the release notes don't enumerate). Read the config file top to bottom before changing anything; the defaults define where the SQLite file lives.
3. Confirm the write path: make a request to your app, then confirm the SQLite file exists and has grown. If nothing is written, the problem is almost always Nightwatch capture, not Firewatch.
4. Wire the MCP server into your AI client (Claude Code, Cursor, or whatever you use) using the command the README specifies, then ask a trivial question — "what requests were recorded in the last 5 minutes?" — to prove the round trip before asking anything complex.

Where to look first: the README for the install/MCP wiring, then the published config file (it's the most honest documentation of what's captured and where it goes), then the CHANGELOG. The release notes are deliberately thin; the README is the canonical source for v1.0.0.

First real use case: you have a slow endpoint, you hit it once locally, and you ask your assistant "which queries did the last request to /orders run, and which were slowest?" instead of hand-rolling DB::listen or squinting at Telescope.

Implementation Patterns

Treat it as a local debugging sidecar, not observability. The mental model is: Nightwatch's sensors collect → Firewatch persists to a local SQLite file → an MCP-speaking agent queries it. That makes it a development and investigation tool. Don't attempt to run it as your production telemetry story; Nightwatch's own hosted offering is the thing for that.

The core loop is short and worth standardising across the team:

• Reproduce the behaviour (hit the endpoint, dispatch the job, run the failing test).
• Ask the agent a scoped question about that reproduction, not about "the app" generally.
• Act on the answer, change code, reproduce again.

This works because the dataset is small and local — the agent can actually read it. The pattern degrades badly once the file accumulates days of traffic (see Gotchas).

Good question shapes to build habits around, since they map onto what sensors typically capture:

• "Which query in the last /checkout request took the longest, and what was its stack trace?"
• "Were there N+1 patterns in the last request — same query shape repeated more than N times?"
• "Did any jobs fail or get retried in the last hour, and what were the exceptions?"
• "What was the cache hit/miss split for the last request?"
• "Compare the query count of the last two requests to /reports — what changed?"

Environment scoping. Enable it only in local (and maybe a dedicated debug env). If the config supports an enable flag, tie it to an env var so a stray APP_ENV doesn't light it up somewhere shared. Anything captured locally with real customer data copied down from production is a data-handling question, not a config question — decide it deliberately.

Don't commit the SQLite file. Add it (and its -wal/-shm siblings) to .gitignore alongside storage/*.key-style entries. If the path is configurable, point it at storage/ so Laravel's existing ignore rules cover it.

Pair it with your editor, not your CI. The value is in the interactive loop. The practical integration tip is to put a short paragraph in your project's agent instructions file (CLAUDE.md, .cursor/rules, etc.) telling the assistant that Firewatch MCP tools exist and roughly what they answer — otherwise the agent won't reach for them and you'll be back to pasting stack traces into chat.

Composability. It sits naturally beside Telescope/Horizon rather than replacing them: use the familiar UI for browsing, and Firewatch when you want the agent to synthesise across requests, queries, and jobs in one answer. If a question needs a human-readable timeline, the existing tools are better; if it needs "correlate these three things and tell me the likely cause," this is the tool.

Gotchas and Tips

The release notes are not the documentation. v1.0.0's notes are one paragraph plus links. Every specific — command names, config keys, MCP tool names, the database path — must come from the README at the pinned tag. Don't infer command names from other packages; verify before you put them in a runbook or a teammate's onboarding doc.

Nightwatch is a prerequisite, not a peer. Firewatch "captures what Nightwatch's sensors collect." If Nightwatch isn't installed and configured to record locally, Firewatch will faithfully store nothing. When someone reports "the agent sees no data," check the capture layer first: is Nightwatch writing anything at all in this environment?

SQLite grows monotonically and will eventually poison your agent's answers. There's no reason to assume automatic retention in a 1.0.0. Plan for it: delete the file periodically (it's disposable), or check whether the config exposes a retention/prune setting. A multi-hundred-MB database doesn't just slow queries — it pushes the agent toward shallow sampling and confidently wrong summaries. If you can't find a prune command, a rm in a local reset script is a legitimate answer.

WAL files and permissions. SQLite in WAL mode leaves -wal/-shm files next to the database. On Sail/Docker the path inside the container differs from the host path, so your MCP server (running on the host) may be pointed at a file the container never writes to. Same class of problem with Herd/Valet and symlinked storage directories. Verify with ls -la on the actual resolved path that the file is being modified on each request.

Sensitive payloads. Request bodies, headers, and bindings captured locally can include tokens, session cookies, and PII from seeded or copied-down data. Treat the SQLite file as a credential. Don't attach it to issues or paste its contents into shared channels.

Context budget is the real constraint. Raw sensor dumps are verbose. Agents handle "summarise these 40 queries" far better than "here are 4,000 rows." Design your prompts to ask for aggregates and rankings rather than full dumps, and expect to narrow by time window or route.

Debugging the MCP hop itself. If the client connects but tools return nothing, separate the layers: (a) does the file have data — query it with sqlite3 directly; (b) does the MCP server start and respond — run it standalone and watch stderr; (c) is the client configured with the right command, working directory, and absolute path to php. Most failures are (c), specifically relative paths and a different PHP binary than the one your app uses.

Extension points to watch. The config file is the sanctioned surface at 1.0.0. Anything beyond it — custom sensors, schema assumptions, reading the SQLite file directly from your own scripts — is unsupported and will break without a deprecation cycle, since there's no history to constrain the maintainer. If you build tooling on top, isolate it behind a thin adapter so a 1.x schema change is a one-file fix.

Upgrade posture. For a 1.0.0, read the CHANGELOG on every bump even for patch releases. With a single maintainer and a fresh package, small versions can carry behavioural changes to what's captured; that silently changes the answers your agent gives, which is worse than an outright error.