Copilot

• Table of Contents
• Screenshots
• Features
• Compatibility
• Requirements
• Installation
  • Step 1 — Install via Composer
  • Step 2 — Run the Install Command
  • Step 3 — Manual Installation (Alternative)
• Configuration
  • AI Provider & Model
  • Rate Limiting
  • Token Budget
  • Audit Logging
  • Agent Memory
  • Management Dashboard
  • Quick Actions
  • System Prompt
  • Global Tools
• Panel Registration
  • Basic Registration
  • Full Configuration via Plugin API
• Making Resources Copilot-Enabled
• Making Pages Copilot-Enabled
• Making Widgets Copilot-Enabled
• Creating Copilot Tools
  • Using the Generator Command
  • Tool Templates
  • Writing a Custom Tool
  • Folder Structure
  • Registering Tools
• Built-in Tools
• User Model Setup
• How It Works
  • Architecture
  • Streaming
  • Agent & Context Building
  • Tool Execution Flow
• Events
• Models & Database
  • Enums
• Management Dashboard
• Customization
  • Custom System Prompt
  • Authorization
  • Translations
  • Views
  • Publishing Stubs
• Testing
• Supported AI Providers
• Contributing
  • How to Contribute
  • Reporting Issues
  • Development Setup
• Security
• Credits
• License

An AI-powered copilot plugin for FilamentPHP v5. Give your admin panel a built-in AI assistant that understands your resources, pages, and widgets — powered by the official Laravel AI SDK.

Filament Copilot integrates directly into your Filament panels with a chat interface, real-time SSE streaming, tool execution, conversation history, agent memory, audit logging, rate limiting, token budget tracking, and a full management dashboard.

#Table of Contents

• Screenshots
• Features
• Compatibility
• Requirements
• Installation
  • Step 1 — Install via Composer
  • Step 2 — Run the Install Command
  • Step 3 — Manual Installation (Alternative)
• Configuration
  • AI Provider & Model
  • Rate Limiting
  • Token Budget
  • Audit Logging
  • Agent Memory
  • Management Dashboard
  • Quick Actions
  • System Prompt
  • Global Tools
• Panel Registration
  • Basic Registration
  • Full Configuration via Plugin API
• Making Resources Copilot-Enabled
• Making Pages Copilot-Enabled
• Making Widgets Copilot-Enabled
• Creating Copilot Tools
  • Using the Generator Command
  • Tool Templates
  • Writing a Custom Tool
  • Folder Structure
  • Registering Tools
• Built-in Tools
• User Model Setup
• How It Works
  • Architecture
  • Streaming
  • Agent & Context Building
  • Tool Execution Flow
• Events
• Models & Database
• Management Dashboard
• Customization
  • Custom System Prompt
  • Authorization
  • Translations
  • Views
  • Publishing Stubs
• Testing
• Supported AI Providers
• Contributing
• Security
• Credits
• License

#Screenshots

#Features

• AI Chat Interface — A beautiful, real-time chat modal built with Livewire, injected directly into your Filament panels.
• Real-Time SSE Streaming — Responses stream token-by-token via Server-Sent Events for an instant, interactive experience.
• Context-Aware Agent — The AI agent automatically discovers your copilot-enabled resources, pages, and widgets and builds context from them.
• Tool Execution — The agent can call tools you define to list, search, create, edit, delete, and restore records — or perform any custom action.
• 9 Tool Templates — Generate tools instantly with the make:copilot-tool artisan command (list, view, search, create, edit, delete, force-delete, restore, custom).
• Conversation History — Full conversation persistence with a sidebar for browsing, loading, and deleting past conversations.
• Agent Memory — The AI remembers facts across conversations using a per-user key-value memory store (Remember & Recall tools).
• Audit Logging — Comprehensive audit trail tracking messages, tool calls, record access, and navigation events.
• Rate Limiting — Per-user hourly/daily message and token rate limits with automatic blocking and unblocking.
• Token Budget Tracking — Daily and monthly token budget tracking with configurable warning thresholds.
• Management Dashboard — Optional admin dashboard with stats overview, token usage charts, top users table, and full Filament resources for conversations, audit logs, and rate limits.
• Quick Actions — Define canned prompt shortcuts that appear in the chat for one-click common queries.
• 8 Supported AI Providers — OpenAI, Anthropic, Google Gemini, Groq, xAI, DeepSeek, Mistral, and Ollama (local models).
• Keyboard Shortcut — Open the copilot with Ctrl+Shift+K from anywhere in your panel.
• Authorization Aware — Respects Filament's authorization policies out of the box.
• Fully Translatable — All UI strings are translatable with a complete English language file (100+ keys).
• Publishable Assets, Config, Views, Stubs — Customize everything to fit your needs.
• 81 Tests — Comprehensive test suite covering models, services, tools, Livewire components, discovery, enums, config, plugin, and streaming.

#Compatibility

Note: This package is built for Filament v5 and Livewire 3.5+ (as bundled with Filament v5). It leverages the official Laravel AI SDK (laravel/ai) for all AI operations.

#Requirements

• PHP 8.2 or higher
• Laravel 11 or 12
• Filament v5
• A supported AI provider API key (or Ollama for local models)
• Node.js (only if you need to rebuild the CSS assets)

#Installation

#Step 1 — Install via Composer

composer require eslam-reda-div/filament-copilot

#Step 2 — Run the Install Command

The interactive installer will guide you through all setup steps:

php artisan filament-copilot:install

This command will:

1. Publish the configuration file to config/filament-copilot.php
2. Publish CSS/JS assets to public/vendor/filament-copilot/
3. Publish and run database migrations (7 tables)
4. Publish the Laravel AI SDK config (config/ai.php)
5. Configure your AI provider (OpenAI, Anthropic, Gemini, etc.)
6. Select your AI model from popular options or enter a custom one
7. Set up your API key in the .env file
8. Display a summary of all configured settings

#Step 3 — Manual Installation (Alternative)

If you prefer to set things up manually:

# Publish configuration
php artisan vendor:publish --tag=filament-copilot-config

# Publish assets
php artisan vendor:publish --tag=filament-copilot-assets

# Publish migrations
php artisan vendor:publish --tag=filament-copilot-migrations

# Run migrations
php artisan migrate

# Publish Laravel AI SDK config
php artisan vendor:publish --tag=ai-config

Then add the following to your .env file:

COPILOT_PROVIDER=openai
COPILOT_MODEL=gpt-4o
OPENAI_API_KEY=your-api-key-here

#Configuration

The configuration file is published to config/filament-copilot.php. Here is a breakdown of every option:

#AI Provider & Model

'provider' => env('COPILOT_PROVIDER', 'openai'),
'model'    => env('COPILOT_MODEL'),

Set via your .env file. See Supported AI Providers for the full list.

#Rate Limiting

'rate_limits' => [
    'enabled'               => false,
    'max_messages_per_hour'  => 60,
    'max_messages_per_day'   => 500,
    'max_tokens_per_hour'    => 100000,
    'max_tokens_per_day'     => 1000000,
],

Per-user rate limiting with automatic blocking. Control messages and tokens per hour and per day.

#Token Budget

'token_budget' => [
    'enabled'             => false,
    'warn_at_percentage'  => 80,
    'daily_budget'        => null,
    'monthly_budget'      => null,
],

Track your AI spending with daily/monthly token budgets and configurable warning thresholds.

#Audit Logging

'audit' => [
    'enabled'            => true,
    'log_messages'       => true,
    'log_tool_calls'     => true,
    'log_record_access'  => true,
    'log_navigation'     => false,
],

Comprehensive audit trail. Enable or disable logging granularly per action type.

#Agent Memory

'memory' => [
    'enabled'              => true,
    'max_memories_per_user' => 100,
],

The AI agent can remember facts across conversations. Memories are scoped per-user, per-panel, and per-tenant.

#Management Dashboard

'management' => [
    'enabled' => false,
    'guard'   => null,
],

Enable the built-in management UI to view conversations, audit logs, rate limits, token usage charts, and top users — all within your Filament panel.

#Quick Actions

'quick_actions' => [
    // 'Summarize this page' => 'Summarize what this page is about.',
    // 'List all users'      => 'List all users in the system.',
],

Define one-click prompt shortcuts that appear in the chat interface.

#System Prompt

'system_prompt' => null,

Override the default system prompt with your own. The agent uses a carefully crafted default prompt that includes context discovery, tool usage guidelines, and response formatting rules.

#Global Tools

'global_tools' => [
    // \App\CopilotTools\MyGlobalTool::class,
],

Register tool classes that should be available on every page across the panel, regardless of which resource, page, or widget the user is on.

#Panel Registration

#Basic Registration

Register the plugin in your Filament panel provider:

use EslamRedaDiv\FilamentCopilot\FilamentCopilotPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugin(FilamentCopilotPlugin::make());
}

#Full Configuration via Plugin API

The plugin offers a fluent API for inline configuration that overrides the config file values:

use EslamRedaDiv\FilamentCopilot\FilamentCopilotPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(
            FilamentCopilotPlugin::make()
                ->provider('anthropic')
                ->model('claude-sonnet-4')
                ->systemPrompt('You are a helpful admin assistant.')
                ->globalTools([
                    \App\CopilotTools\SearchEverythingTool::class,
                ])
                ->quickActions([
                    'Show stats'   => 'Show me a summary of today\'s statistics.',
                    'Recent users' => 'List the 10 most recently created users.',
                ])
                ->managementEnabled()
                ->managementGuard('admin')
                ->rateLimitEnabled()
                ->tokenBudgetEnabled()
                ->dailyTokenBudget(50000)
                ->monthlyTokenBudget(1000000)
                ->memoryEnabled()
                ->maxMemoriesPerUser(200)
                ->respectAuthorization()
                ->authorizeUsing(fn ($user) => $user->is_admin)
        );
}

#Making Resources Copilot-Enabled

Implement the CopilotResource interface on any Filament resource to make it discoverable by the AI agent:

use EslamRedaDiv\FilamentCopilot\Contracts\CopilotResource;

class UserResource extends Resource implements CopilotResource
{
    // ... your existing resource code ...

    public static function copilotResourceDescription(): ?string
    {
        return 'Manages user accounts including names, emails, roles, and permissions.';
    }

    public static function copilotTools(): array
    {
        return [
            new \App\Filament\Resources\UserResource\CopilotTools\ListUsersTool(),
            new \App\Filament\Resources\UserResource\CopilotTools\SearchUsersTool(),
            new \App\Filament\Resources\UserResource\CopilotTools\CreateUserTool(),
            new \App\Filament\Resources\UserResource\CopilotTools\ViewUserTool(),
            new \App\Filament\Resources\UserResource\CopilotTools\EditUserTool(),
            new \App\Filament\Resources\UserResource\CopilotTools\DeleteUserTool(),
        ];
    }
}

#Making Pages Copilot-Enabled

Implement the CopilotPage interface on any Filament page:

use EslamRedaDiv\FilamentCopilot\Contracts\CopilotPage;

class Dashboard extends Page implements CopilotPage
{
    // ... your existing page code ...

    public static function copilotPageDescription(): ?string
    {
        return 'The main dashboard showing key metrics and recent activity.';
    }

    public static function copilotTools(): array
    {
        return [
            new \App\Filament\Pages\CopilotTools\Dashboard\DashboardStatsTool(),
        ];
    }
}

#Making Widgets Copilot-Enabled

Implement the CopilotWidget interface on any Filament widget:

use EslamRedaDiv\FilamentCopilot\Contracts\CopilotWidget;

class RevenueChart extends Widget implements CopilotWidget
{
    // ... your existing widget code ...

    public static function copilotWidgetDescription(): ?string
    {
        return 'Displays revenue data over the past 30 days as a line chart.';
    }

    public static function copilotTools(): array
    {
        return [
            new \App\Filament\Widgets\CopilotTools\RevenueChart\GetRevenueDataTool(),
        ];
    }
}

#Creating Copilot Tools

#Using the Generator Command

The make:copilot-tool artisan command provides an interactive 5-step wizard:

php artisan make:copilot-tool

Step 1 — Select the Filament panel
Step 2 — Choose the tool type (Resource / Page / Widget)
Step 3 — Select the target (lists only copilot-enabled resources/pages/widgets from the chosen panel)
Step 4 — Pick a template (9 options for resources, custom for pages/widgets)
Step 5 — Enter the tool class name (with a smart default using proper English pluralization)

The command generates the tool file in the correct folder and namespace, with a summary table showing all settings.

#Tool Templates

For resource tools, 9 templates are available:

For page and widget tools, only the custom template is available.

#Writing a Custom Tool

Every tool extends BaseTool and implements three methods:

<?php

declare(strict_types=1);

namespace App\Filament\Resources\UserResource\CopilotTools;

use App\Filament\Resources\UserResource;
use EslamRedaDiv\FilamentCopilot\Tools\BaseTool;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Tools\Request;
use Stringable;

class SearchUsersTool extends BaseTool
{
    /**
     * A description of what this tool does — shown to the AI agent.
     */
    public function description(): Stringable|string
    {
        return 'Search users by name or email.';
    }

    /**
     * The JSON Schema defining the tool's parameters.
     */
    public function schema(JsonSchema $schema): array
    {
        return [
            'query' => $schema->string()
                ->description('The search keyword (name or email)')
                ->required(),
            'limit' => $schema->integer()
                ->description('Maximum number of results to return')
                ->default(10),
        ];
    }

    /**
     * Execute the tool and return a string result to the AI agent.
     */
    public function handle(Request $request): Stringable|string
    {
        $model = UserResource::getModel();
        $query = (string) $request['query'];
        $limit = (int) ($request['limit'] ?? 10);

        $results = $model::query()
            ->where('name', 'like', "%{$query}%")
            ->orWhere('email', 'like', "%{$query}%")
            ->limit($limit)
            ->get(['id', 'name', 'email']);

        if ($results->isEmpty()) {
            return "No users found matching '{$query}'.";
        }

        return $results->map(fn ($user) =>
            "#{$user->id} — {$user->name} ({$user->email})"
        )->implode("\n");
    }
}

#Folder Structure

Tools are generated in a specific folder structure depending on the type:

Resource tools:

app/Filament/Resources/
└── UserResource/
    ├── UserResource.php
    └── CopilotTools/
        ├── ListUsersTool.php
        ├── SearchUsersTool.php
        ├── CreateUserTool.php
        └── ...

Page tools:

app/Filament/Pages/
├── Dashboard.php
└── CopilotTools/
    └── Dashboard/
        └── DashboardStatsTool.php

Widget tools:

app/Filament/Widgets/
├── RevenueChart.php
└── CopilotTools/
    └── RevenueChart/
        └── GetRevenueDataTool.php

#Registering Tools

After generating a tool, register it in the copilotTools() method of your resource, page, or widget:

public static function copilotTools(): array
{
    return [
        new \App\Filament\Resources\UserResource\CopilotTools\ListUsersTool(),
        new \App\Filament\Resources\UserResource\CopilotTools\SearchUsersTool(),
    ];
}

#Built-in Tools

The following tools are automatically available to the AI agent without any configuration:

The agent uses these tools to navigate your panel structure and execute operations dynamically.

#User Model Setup

To enable conversation history on your User model, add the HasCopilotChat trait:

use EslamRedaDiv\FilamentCopilot\Concerns\HasCopilotChat;

class User extends Authenticatable
{
    use HasCopilotChat;

    // ...
}

This adds a copilotConversations() polymorphic relationship to your user model.

#How It Works

#Architecture

┌─────────────────────────────────────────────────────┐
│                   Filament Panel                     │
│                                                      │
│  ┌──────────┐  ┌───────────────┐  ┌──────────────┐ │
│  │  Copilot  │  │ Conversation  │  │   Copilot    │ │
│  │  Button   │──│   Sidebar     │  │   Chat       │ │
│  └──────────┘  └───────────────┘  └──────┬───────┘ │
│                                           │         │
│                                    SSE Stream       │
│                                           │         │
├───────────────────────────────────────────┼─────────┤
│                                           ▼         │
│  ┌────────────────────────────────────────────────┐ │
│  │              StreamController                   │ │
│  │  Auth → Rate Limit → Build Agent → Stream      │ │
│  └──────────────────────┬─────────────────────────┘ │
│                          │                           │
│  ┌───────────────────────▼───────────────────────┐  │
│  │              CopilotAgent                      │  │
│  │  Temperature: 0.3 | MaxTokens: 4096           │  │
│  │  Middleware: Audit + RateLimit                 │  │
│  └───────────────────────┬───────────────────────┘  │
│                          │                           │
│  ┌───────────┐  ┌───────▼────────┐  ┌───────────┐  │
│  │  Context   │  │  Tool Registry │  │ Conversa- │  │
│  │  Builder   │  │  (built-in +   │  │   tion    │  │
│  │            │  │   global +     │  │  Manager  │  │
│  │ • Resources│  │   per-target)  │  │           │  │
│  │ • Pages    │  └────────────────┘  └───────────┘  │
│  │ • Widgets  │                                      │
│  │ • Memory   │                                      │
│  └───────────┘                                       │
│                                                      │
│  ┌──────────────────────────────────────────────┐   │
│  │            Laravel AI SDK                     │   │
│  │   OpenAI | Anthropic | Gemini | Groq | ...   │   │
│  └──────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘

#Streaming

1. User sends a message from the chat modal.
2. A POST request is made to /copilot/stream.
3. The StreamController validates auth, checks rate limits, and creates/loads the conversation.
4. The CopilotAgent is built with tools, messages, and middleware.
5. The response streams back via Server-Sent Events (SSE) — text deltas, tool calls, and tool results are sent as they happen.
6. The Livewire component renders the streamed response in real-time.

#Agent & Context Building

The ContextBuilder assembles the system prompt from multiple sources:

1. Base system prompt — Crafted guidelines for the AI agent, including response formatting rules and tool usage instructions.
2. Resource discovery — All copilot-enabled resources, their descriptions, and available tools.
3. Page discovery — All copilot-enabled pages with descriptions and tools.
4. Widget discovery — All copilot-enabled widgets with descriptions and tools.
5. Agent memories — Previously stored key-value memories for the current user.
6. Custom prompt override — Your own system prompt (if configured).

#Tool Execution Flow

1. The AI agent decides to call a tool based on the conversation context.
2. The tool call event is streamed to the frontend.
3. RunToolTool resolves the target tool class and executes it with the provided arguments.
4. The tool result is streamed back to the AI agent, which incorporates it into its response.
5. All tool calls are logged in the copilot_tool_calls table with full status tracking.

#Events

Filament Copilot dispatches the following events that you can listen to:

// In your EventServiceProvider or event discovery
use EslamRedaDiv\FilamentCopilot\Events\CopilotToolExecuted;

class LogToolExecution
{
    public function handle(CopilotToolExecuted $event): void
    {
        logger()->info('Tool executed', [
            'tool'    => $event->toolCall->tool_class,
            'user_id' => $event->toolCall->conversation->participant_id,
        ]);
    }
}

#Models & Database

The package creates 7 database tables:

All models use ULIDs as primary keys and support polymorphic relationships for participant and tenant.

#Enums

#Management Dashboard

Enable the management dashboard to monitor copilot usage from within your Filament panel:

FilamentCopilotPlugin::make()
    ->managementEnabled()
    ->managementGuard('admin')  // optional: restrict to specific guard

This adds:

• Dashboard Page — With 3 widgets:
  • Stats Overview — 4 cards showing total conversations, messages, tool calls, and active users
  • Token Usage Chart — 30-day line chart of daily token consumption
  • Top Users Table — Sortable table of the most active copilot users
• Conversations Resource — Browse, view, and manage all copilot conversations
• Audit Logs Resource — Search and filter the complete audit trail
• Rate Limits Resource — Manage per-user rate limits and blocking

#Customization

#Custom System Prompt

Override the default system prompt via config or the plugin API:

// config/filament-copilot.php
'system_prompt' => 'You are a helpful assistant for our e-commerce admin panel. Focus on order management and customer support.',

Or via the plugin:

FilamentCopilotPlugin::make()
    ->systemPrompt('You are a helpful assistant for our e-commerce admin panel.')

#Authorization

Control who can access the copilot:

FilamentCopilotPlugin::make()
    ->authorizeUsing(fn ($user) => $user->hasRole('admin'))

The package also respects Filament's built-in authorization policies when respect_authorization is enabled (default: true).

#Translations

Publish the translation files to customize all UI strings:

php artisan vendor:publish --tag=filament-copilot-translations

The package ships with a complete English translation file containing 100+ keys.

#Views

Publish the Blade views to customize the UI:

php artisan vendor:publish --tag=filament-copilot-views

#Publishing Stubs

Publish the tool generator stubs to customize the generated tool templates:

php artisan vendor:publish --tag=filament-copilot-stubs

Stubs are published to stubs/filament-copilot/ in your project root.

#Testing

The package includes 81 tests with 159 assertions covering:

• Models & relationships
• Services (ConversationManager, ToolRegistry, RateLimitService, ExportService)
• Built-in tools
• Livewire components
• Discovery inspectors
• Enums
• Configuration
• Plugin registration
• Streaming

Run the tests:

cd packages/filament-copilot
php vendor/bin/pest

#Supported AI Providers

Configure via .env:

COPILOT_PROVIDER=openai
COPILOT_MODEL=gpt-4o
OPENAI_API_KEY=sk-...

#Contributing

We warmly welcome contributions from the Laravel and FilamentPHP open-source community! Whether it's a bug fix, a new feature, improved documentation, or just a typo fix — every contribution matters and is greatly appreciated.

#How to Contribute

1. Fork the repository
2. Create a branch for your feature or fix:

   git checkout -b feature/my-awesome-feature
   

3. Make your changes and write tests if applicable
4. Run the test suite to make sure nothing is broken:

   php vendor/bin/pest
   

5. Commit your changes with a clear message:

   git commit -m "Add: my awesome feature"
   

6. Push to your fork and open a Pull Request

#Reporting Issues

Found a bug? Have a question? Want to request a feature?

• Open an issue on the GitHub Issues page
• Describe the problem clearly, including steps to reproduce if it's a bug
• Include your PHP, Laravel, and Filament version numbers
• Attach screenshots or error logs if applicable

We review all issues and pull requests and try to respond as quickly as possible. Thank you to everyone who takes the time to help improve this package — you're what makes the open-source ecosystem great! ❤️

#Development Setup

# Clone the repository
git clone https://github.com/eslam-reda-div/filament-copilot.git
cd filament-copilot

# Install dependencies
composer install

# Run tests
php vendor/bin/pest

# Build assets (if modifying CSS)
npm install
npm run build

#Security

If you discover a security vulnerability, please report it responsibly. Send an email to the maintainer instead of opening a public issue. All security vulnerabilities will be promptly addressed.

#Credits

• Eslam Reda
• All Contributors

Built with:

• FilamentPHP — The elegant TALL stack admin panel framework
• Laravel AI SDK — The official Laravel AI package
• Spatie Laravel Package Tools — Package scaffolding utilities

#License

The MIT License (MIT). Please see LICENSE.md for more information.