exeque / laravel-monocle
Agent-focused request profiler for Laravel with an MCP server: timing spans, queries, cache, filesystem, AI agent calls and more.
Requires
- php: ^8.4
- illuminate/contracts: ^13.0
- illuminate/support: ^13.0
- laravel/agent-detector: ^2.0
- laravel/boost: ^2.10
- laravel/mcp: ^1.0
Requires (Dev)
- brianium/paratest: 7.26.0
- franbarbalopez/mirror: ^2.0
- inertiajs/inertia-laravel: ^3.5
- lab404/laravel-impersonate: ^1.7
- laravel/ai: ^1.0
- laravel/folio: ^1.2
- laravel/fortify: ^1.41
- laravel/octane: ^2.21
- laravel/pennant: ^1.26
- laravel/pint: ^1.21
- laravel/sanctum: ^4.3
- livewire/livewire: ^4.0
- nuwave/lighthouse: ^6.72
- orchestra/testbench: ^11.3
- pestphp/pest: ^5.0
- prism-php/prism: ^0.100
- rebing/graphql-laravel: ^10.1
- spatie/laravel-event-sourcing: ^7.15
- spatie/laravel-medialibrary: ^11.23
- spatie/laravel-responsecache: ^8.4
- stechstudio/filament-impersonate: ^5.0
- symfony/var-dumper: ^8.0
Suggests
- laravel/ai: Required to record agent, step and tool calls with the AiLens.
- livewire/livewire: Required to record component lifecycle with the LivewireLens.
- prism-php/prism: Required to record text, structured, stream, embeddings and other calls with the PrismLens.
Provides
None
Conflicts
None
Replaces
None
README
Monocle
Documentation: exeque.github.io/laravel-monocle
A request profiler for Laravel, built for AI coding agents. Monocle records what your application did while handling a request, a queued job or an artisan command - timing, middleware, database queries, cache, views, mail, HTTP calls, filesystem operations, AI agent calls and more - and lets an agent read it through an MCP server. The same data is available from artisan and in a web dashboard at /_monocle.
Install
composer require --dev exeque/laravel-monocle php artisan monocle:install
monocle:install asks what to record, where to store it and which MCP clients to configure, then writes config/monocle.php and registers the MCP server. Restart your MCP client afterwards.
Monocle records only outside production and only with APP_DEBUG=true, and never while your test suite runs unless you enable it.
What your agent can do
| Tool | Purpose |
|---|---|
monocle-list |
Recent captures with duration, status, per-section counts and how many errors and warnings |
monocle-show |
Where the time went, totals, errors (exceptions, failed calls and jobs) and warnings (slow queries, N+1, duplicates, slow middleware) |
monocle-rows |
Any section, filtered, sorted and paginated |
monocle-queries |
Queries grouped by shape, caller, table or transaction |
monocle-trace |
A request and every job it dispatched |
monocle-compare |
Two captures side by side - did the change help? |
monocle-clear |
Start from a clean slate |
monocle-lenses |
The sections this application records |
Every recorded response carries an X-Monocle-Id header, and every recorded row points to the file:line in your code that caused it.
From the terminal: monocle:list, monocle:show, monocle:rows, monocle:queries, monocle:trace, monocle:compare, monocle:clear. monocle:install sets Monocle up and monocle:editor links files to your editor.
Measure your own code
use Monocle; $span = Monocle::span('import photos')->start(['album' => $album->id]); // ... $span->stop(['count' => $count]); Monocle::measure('resize', fn () => $this->resize($file));
Learn more
- Installation
- For AI agents
- What gets recorded
- Dashboard
- Spans and metadata
- Writing a lens
- Third-party lenses
- Configuration
- Storage
- Artisan commands
Contributing
Read CONTRIBUTING.md before opening a pull request. Report security issues privately as described in SECURITY.md. Everyone taking part follows the Code of Conduct.
License
MIT