- What does joshcirre/instruckt-laravel actually do?
- It is the Laravel backend for Instruckt, a visual feedback tool for AI coding agents. It provides an annotation API endpoint, JSON file storage, MCP tools, and a Blade toolbar component. Developers annotate elements in the browser, annotations become structured markdown, and agents can also read them through MCP.
- How do I install instruckt-laravel in a Laravel app?
- Run composer require joshcirre/instruckt-laravel --dev, then run php artisan instruckt:install. The install command publishes the config, installs the npm package, adds the Instruckt Vite plugin, and injects the virtual import into your JS entry point. It also configures MCP for any detected AI agents such as Claude Code, Cursor, Codex, OpenCode, and GitHub Copilot.
- Which Laravel and PHP versions are supported?
- The package requires PHP 8.2 or higher and Laravel 11 or 12. Vite 5 or newer is expected for the default plugin-based setup, which matches Laravel 11 and 12 defaults. Apps still on Laravel Mix or older build tooling would need to migrate before using the Vite integration.
- Do I need laravel/mcp to use this package?
- No, laravel/mcp is optional. Without it you still get the annotation API, JSON storage, and the browser toolbar for copying annotations as markdown. Installing laravel/mcp enables the MCP tools so agents can list and read annotations directly. Version 0.4.30 accepts laravel/mcp ^1.0, so it can coexist with current Laravel AI tooling.
- Will instruckt ship anything to production builds?
- No. The Vite plugin only applies during vite serve, so the toolbar is completely absent from production builds and ships zero bytes. The Blade component alternative is gated behind config('instruckt.enabled'), which defaults to true only when APP_ENV is local. Keeping it as a dev dependency further ensures it stays out of production.
- How are annotations stored and can I use a database instead?
- By default annotations are written to JSON files, and the storage location is configurable. That is fine for local development but has scalability limits for larger or shared environments. You can extend the package to use Eloquent or another backend, though that requires manual setup.
- Does it work with Livewire, Vue, Inertia, or Alpine?
- The built-in adapters cover Livewire and Blade, and the toolbar accepts a custom adapters array so you can target other setups. Inertia and Alpine.js users may need a custom adapter to map annotations to the right component or element context. The frontend is decoupled from the backend API, so adding an adapter does not require rewriting core logic.
- How do I test or verify the MCP integration works?
- After running instruckt:install, check the generated MCP configuration for your agent and confirm the instruckt tools are registered. Then create an annotation in the browser and ask your agent to list annotations to verify the round trip. Keep in mind that tool schema alignment with your specific agent is the remaining runtime risk, not the Composer constraint.
- Is it safe to install alongside laravel/ai 1.x and laravel/mcp 1.0?
- Yes. As of version 0.4.30 the package accepts laravel/mcp ^1.0, removing the previous hard version pin that forced apps onto an older MCP line. Review your lockfile before upgrading to confirm no other package still pins MCP to 0.x. Note that pinning to ^1.0 moves the baseline forward, so verify your app is not still on MCP 0.x.
- How do I uninstall instruckt-laravel cleanly?
- Run php artisan instruckt:uninstall, which reverts the installer changes such as the Vite plugin entry, the virtual import, and the agent MCP configuration. Then remove the package with composer remove joshcirre/instruckt-laravel --dev and delete the published config if you no longer need it. Because it is a dev dependency, production deployments are unaffected either way.