Download the PHP package eslam-reda-div/filament-copilot without Composer

Filament Copilot

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
  • Message Feedback
  • 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).
• Message Feedback — Thumbs up/down on assistant replies, surfaced back to admins as a thumbs-down count and a "has negative rating" filter on the conversations table.
• 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.
• 121 Tests — Comprehensive test suite covering models, services, tools, Livewire components, views, 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.3 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

Step 2 — Run the Install Command

The interactive installer will guide you through all setup steps:

This command will:

1. Publish the configuration file to config/filament-copilot.php
2. Publish CSS/JS assets via Filament's asset pipeline (php artisan filament:assets)
3. Publish and run database migrations, including Laravel AI conversation 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:

CSS/JS assets are handled automatically by Filament's own asset pipeline — there is no separate publish step. Filament Copilot registers its assets via FilamentAsset::register(), and running php artisan filament:assets copies them into your application's public/ directory. This command is already run for you by the installer, and Filament recommends adding it to your composer.json's post-autoload-dump scripts (alongside filament:upgrade) so assets stay in sync automatically whenever the package is updated.

Then add the following to your .env file:

Upgrading from <= v1.2.x? Asset publishing via vendor:publish --tag=filament-copilot-assets has been removed — assets are now served entirely through Filament's asset pipeline. You can safely delete the now-unused public/vendor/filament-copilot/ directory, and remove any php artisan vendor:publish --tag=filament-copilot-assets step from your deploy scripts.

Configuration

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

AI Provider & Model

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

Rate Limiting

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

Token Budget

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

Audit Logging

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

Agent Memory

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

Management Dashboard

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

Message Feedback

Adds a thumbs up / thumbs down control under every assistant reply in the chat. One click rates the reply, clicking the lit thumb again clears it, and the rating is stored on copilot_messages.rating (positive, negative, or null).

Ratings are only accepted for assistant messages in the signed-in participant's own conversations, scoped by panel and tenant like every other conversation lookup in the package.

Admins get the feedback back in the management dashboard's Conversations resource:

• a Thumbs Down badge column, shown only for the conversations that actually collected one, and
• a Has Negative Rating filter for jumping straight to the conversations that went wrong.

Set enabled to false to hide the buttons and stop accepting ratings. Ratings already recorded are kept and still reported in the management UI.

Quick Actions

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

System Prompt

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

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:

Full Configuration via Plugin API

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

Making Resources Copilot-Enabled

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

Making Pages Copilot-Enabled

Implement the CopilotPage interface on any Filament page:

Making Widgets Copilot-Enabled

Implement the CopilotWidget interface on any Filament widget:

Creating Copilot Tools

Using the Generator Command

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

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:

Folder Structure

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

Resource tools:

Page tools:

Widget tools:

Registering Tools

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

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:

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

How It Works

Architecture

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, native persisted conversation history, 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.

Human Tool Approval

Tools implementing Laravel AI's Approvable contract are paused before execution. The chat displays the pending tool, arguments, and approval reason, and resumes the same conversation after the user approves or rejects the request. Before using this feature, publish and run Laravel AI's conversation migrations:

Use InteractsWithApprovals on tools that need approval. The package stores the Laravel AI conversation identifier in its conversation metadata so approval flows remain resumable across requests.

Events

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

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:

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, including the thumbs-down count and the "has negative rating" filter from Message Feedback
• 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:

Or via the plugin:

Authorization

Control who can access the copilot:

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:

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

Views

Publish the Blade views to customize the UI:

Publishing Stubs

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

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

Testing

The package includes 121 tests with 254 assertions covering:

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

Run the tests:

Supported AI Providers

Configure via .env:

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:

3. Make your changes and write tests if applicable

4. Run the test suite to make sure nothing is broken:

5. Commit your changes with a clear message:

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

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.