Instruckt for Laravel

instruckt provides a visual feedback loop between users and AI agents:

1. Initialization: The Vite plugin or Blade component initializes the annotation UI.
2. Annotation: Users click elements to leave feedback and optionally capture screenshots.
3. Clipboard: Annotations are automatically copied as structured markdown for easy pasting into AI agents.
4. Persistence: Annotations are stored via API in storage/app/_instruckt/ (JSON for data, PNG for screenshots).
5. AI Interaction: AI agents use MCP tools to read pending annotations and can call instruckt.resolve to mark them as fixed, which removes the marker from the browser.

When an annotation is provided, the server automatically resolves component names to source file paths. The framework object within an annotation provides metadata to help you navigate directly to the code:

• source_file: The relative path to the component file (e.g., app/Livewire/Dashboard.php). Use this to open the file directly instead of searching.
• source_line: The starting line number of the class.
• render_line: For Livewire components, the line number of the render() method where the view is returned.
• class_name: The fully-qualified PHP class name (e.g., App\Livewire\Dashboard).

To remove a visual feedback marker from a user's browser, you must call instruckt.resolve with the specific annotation ID.

Best Practices:

• Always resolve after fixing: If you do not call this, the marker remains visible in the user's browser.
• Direct Resolution: You can use the ID found directly in the user's pasted markdown to call instruckt.resolve immediately. You only need to call instruckt.get_all_pending if you need to check for screenshots or list all active markers.

If you prefer not to use Vite/JS configuration, you can use the Blade component in your layout before the </body> tag.

Note: The component is gated by config('instruckt.enabled'), which defaults to true only when APP_ENV=local. Visual configuration (colors, keys) for the Blade component is handled via component attributes.

<x-instruckt-toolbar
    theme="dark"
    position="bottom-left"
    :adapters="['livewire', 'vue']"
    :colors="['default' => '#6366f1', 'screenshot' => '#22c55e', 'dismissed' => '#71717a']"
    :keys="['annotate' => 'a', 'freeze' => 'f']"
/>

Install the package as a development dependency and run the installation command to automate setup. The installation command publishes the configuration, installs the necessary npm package, adds the Vite plugin, injects the virtual module into your JS entry point, and configures MCP for detected AI agents.

Requirements:

• PHP 8.2+
• Laravel 11 or 12
• laravel/mcp (optional, for MCP tool integration)

composer require joshcirre/instruckt-laravel --dev

php artisan instruckt:install

If the automatic installation does not detect your agent, you can manually add the instruckt MCP server to your agent's configuration file (e.g., .mcp.json for Claude Code).

{
  "mcpServers": {
    "instruckt": {
      "command": "php",
      "args": ["artisan", "mcp:start", "instruckt"]
    }
  }
}

The default way to use instruckt is via the Vite plugin. This plugin only runs during vite serve (apply: 'serve'), ensuring it is completely absent from production builds.

When using the Vite plugin, visual configuration (colors, keys, position, theme) must be defined here rather than in the PHP config file.

import laravel from 'laravel-vite-plugin'
import instruckt from 'instruckt/vite'

export default defineConfig({
  plugins: [
    laravel({ input: ['resources/js/app.js'] }),
    instruckt({
      server: false,
      endpoint: '/instruckt',
      adapters: ['livewire', 'blade'],
      mcp: true,
    }),
  ],
})

To remove instruckt, use the instruckt:uninstall command. This reverses the installation process, including removing Vite/JS artifacts, config files, Blade components, MCP entries, and stored data in storage/app/_instruckt/.

After running the artisan command, remove the package via Composer.

php artisan instruckt:uninstall

# Then remove the package
composer remove joshcirre/instruckt-laravel --dev

All routes are registered under the configured prefix (default: /instruckt):

| Method | Route | Description |
|--------|-------|-------------|
| GET | `/instruckt/annotations` | List all annotations |
| POST | `/instruckt/annotations` | Create annotation |
| PATCH | `/instruckt/annotations/{id}` | Update annotation |

The package registers the following tools for your AI agent to interact with annotations:

| Tool | Description |
|------|-------------|
| `instruckt.get_all_pending` | Get all pending annotations |
| `instruckt.get_screenshot` | Get the screenshot image for an annotation |
| `instruckt.resolve` | Mark an annotation as resolved (removes marker from browser) |