Orca Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require lets-make-dev/orca
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       MakeDev\Orca\OrcaServiceProvider::class,
   ],
   

2. Publish Config

   php artisan vendor:publish --provider="MakeDev\Orca\OrcaServiceProvider" --tag="orca-config"
   

   Configure config/orca.php (API key, widget visibility, etc.).

3. First Use Case

   • Visit any Laravel page (e.g., /admin/users). The Orca widget (floating UI) appears in the corner.
   • Click the widget to auto-capture the current context (route, Livewire component, DB query logs, etc.).
   • Paste the generated prompt into Claude Code (or use the built-in terminal pop-out for macOS).

Implementation Patterns

Core Workflows

1. Context-Aware Prompting

   • Livewire Integration: Automatically injects component class/method names into prompts.

     // Livewire component
     public function mount() {
         // Orca will capture this class + method context
     }
     

   • Route Awareness: Includes the full route name (e.g., admin.users.index) in prompts.

     Route::get('/admin/users', [UserController::class, 'index']);
     

2. Safety Features

   • Plan-Then-Execute: Orca generates a "plan" (SQL, API calls) before execution. Review it in the widget before running.
   • Screenshot Capture: On demand, take a screenshot of the current view and attach it to prompts.

3. Terminal Integration (macOS)

   • Click the "Pop Out" button to spawn a local terminal with:
     • Pre-loaded Laravel environment variables.
     • Current route/controller context.
     • Direct access to artisan, php, and project files.

4. Custom Context Providers Extend MakeDev\Orca\Contracts\ContextProvider to inject app-specific data:

   use MakeDev\Orca\Contracts\ContextProvider;
   
   class AppContextProvider implements ContextProvider {
       public function getContext(): array {
           return [
               'app_version' => '1.0.0',
               'user_prefs' => auth()->user()->preferences,
           ];
       }
   }
   

   Register in config/orca.php:

   'context_providers' => [
       \App\Providers\AppContextProvider::class,
   ],
   

Gotchas and Tips

Pitfalls

1. API Key Management

   • The ORCA_CLAUDE_API_KEY must be set in .env or config/orca.php. Hardcoding keys in config is discouraged.
   • Tip: Use Laravel’s environment variables or a secrets manager.

2. Livewire Component Visibility

   • Orca only captures mounted Livewire components. Ensure your component’s mount() method runs before interacting with the widget.
   • Debugging: Check dd($this->getContext()) in your Livewire component to verify captured data.

3. Performance Overhead

   • Context capture adds ~50–100ms per page load. Disable in production:

     'enabled' => env('APP_ENV') !== 'production',
     

4. Terminal Pop-Out Limitations

   • macOS-only feature. Linux/Windows users rely on Claude Code CLI.
   • Workaround: Use php artisan tinker or VS Code’s integrated terminal for cross-platform access.

Debugging

• Log Context Data Enable debug mode in config/orca.php:

  'debug' => true,
  

  Check storage/logs/orca.log for captured context before prompting.

• Widget Not Showing? Verify:

  // config/orca.php
  'visibility' => [
      'routes' => ['admin.*'], // Only show on admin routes
      'excluded_routes' => ['admin.secrets'],
  ],
  

Extension Points

1. Custom Prompt Templates Override the default prompt structure via a view:

   // resources/views/vendor/orca/prompt.blade.php
   <div class="orca-prompt">
       @include('orca::partials.header')
       <p>Custom context: {{ $context['app_version'] }}</p>
       @include('orca::partials.footer')
   </div>
   

2. Event Listeners Listen for context capture events:

   use MakeDev\Orca\Events\ContextCaptured;
   
   ContextCaptured::listen(function (ContextCaptured $event) {
       \Log::info('Orca captured:', $event->context);
   });
   

3. Screenshot Customization Modify the screenshot capture logic by publishing the view:

   php artisan vendor:publish --tag="orca-views"
   

   Edit resources/views/vendor/orca/screenshot.blade.php to adjust capture area or annotations.