revolution / laravel-copilot-sdk

1.0.26 2026-10-23 22:26 UTC

Requires

• php: ^8.4
• illuminate/support: ^12.45||^13.0
• revolt/event-loop: ^1.0

Requires (Dev)

• laravel/ai: ^1.0
• laravel/pao: ^1.0
• laravel/pint: ^1.25
• mockery/mockery: ^1.6
• orchestra/testbench: ^10.6||^11.0
• pestphp/pest: ^5.0
• pestphp/pest-plugin-laravel: ^5.0
• revolution/laravel-boost-copilot-cli: ^2.0
• spatie/fork: ^1.2

Suggests

• open-telemetry/api: Required for automatic W3C Trace Context propagation between your app and the Copilot CLI

MIT

• kawax
• puklipo

• laravel
• copilot-cli
• copilot-sdk

Published on Packagist.org on 2026-10-24 00:45 UTC

README

This package is Laravel version of GitHub Copilot SDK, which allows you to interact with GitHub Copilot CLI programmatically from your Laravel applications.

Note

This is the Community SDK.

Requirements

• PHP >= 8.4
• Laravel >= 12.x
• Copilot CLI Latest version

Installation

The embedded SDK snapshot is current through the official Copilot CLI 1.0.101-0. The Laravel package ports capabilities selectively; advancing the snapshot does not imply complete protocol or feature parity.

Snapshot 1.0.101-0 removes the session-level enableGitHubCacheStore option from session creation and resume. The separate connect handshake continues to advertise supportedTaskKinds, with optional telemetry/client info and a connection token when configured; it does not negotiate a GitHub-cache setting. The legacy key is ignored in array configuration; remove it from typed SessionConfig and ResumeSessionConfig construction. GitHub-cache availability is not controlled through this SDK's session settings. This behavior is the same for stdio and TCP transports. Upstream also removed github-cache-store from its internal SessionCapability enum, so that value is no longer supported in the sessionCapabilities list used by session.options.update. This SDK has no matching SessionCapability enum or sessionCapabilities request field in its create/resume or post-create option updates. Its separate SessionCapabilities type represents CLI-reported UI elicitation/canvas support; it is not that session-option capability list.

The PHP callback is synchronous; unlike the Node.js SDK it does not currently receive a transport cancellation token. Stdio shutdown sends EOF first and waits briefly for the runtime to exit naturally before terminating it. If the stdio startup handshake times out, the exception includes recent process stderr output (up to 8 KiB). TCP mode only closes the client connection and never shuts down the external runtime. If the CLI rejects a JSON-RPC frame without a correlatable request ID, all currently pending requests fail with a sanitized JsonRpcException; the connection remains open.

composer require revolution/laravel-copilot-sdk

Optional

.env (Optional)

COPILOT_CLI_PATH=copilot

TCP Mode (Optional)

Instead of starting a new CLI process for each request, you can connect to an existing Copilot CLI server running in TCP mode. This is useful for:

• Laravel Forge/Cloud deployments with background process management
• Sharing a single CLI instance across multiple Laravel processes
• Better performance with persistent connections

Start the Copilot CLI server:

copilot --headless --port 12345

Configure your .env:

COPILOT_URL=tcp://127.0.0.1:12345

When COPILOT_URL is set, the SDK will connect to the existing server instead of starting a new CLI process.

Publish config (Optional)

php artisan vendor:publish --tag=copilot-config

Uninstall

composer remove revolution/laravel-copilot-sdk

Getting Started

Getting Started Guide

Usage

We provide a high-level API that uses a Laravel Facade on top of a layer that replicates the official SDK.

This should be sufficient for general use.

Artisan commands, controllers, jobs... the SDK can be used anywhere in Laravel where you can invoke the Copilot CLI.

Run single prompt

use Revolution\Copilot\Facades\Copilot;

$response = Copilot::run(prompt: 'Tell me something about Laravel.');
dump($response->content());

Multiple prompts in a single session

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;

$content = Copilot::start(function (CopilotSession $session) {
    dump('Starting Copilot session: '.$session->id());

    $response = $session->sendAndWait(prompt: 'Tell me something about PHP.');
    dump($response->content());

    $response = $session->sendAndWait(prompt: 'Tell me something about Laravel.');
    dump($response->content());

    return $response->content();
});

dump($content);

copilot() helper

Alternatively, you can use the copilot() helper function.

// Don't forget to import the function
use function Revolution\Copilot\copilot;

// If you specify a prompt as a string, it is the same as Copilot::run(). 
$response = copilot('Tell me something about Laravel.');

// If you pass a closure, it is the same as Copilot::start().
copilot(function (CopilotSession $session) {
    $response = $session->sendAndWait(prompt: 'Tell me something about PHP.');
});

// If you don't pass anything, it's the same as Facade.
dump(copilot()->client()->ping());

For more than simple use, use the Copilot Facade above.

Testing

Provide Laravel way testing support with Copilot::fake().

Copilot::fake()

Copilot::fake() is a mock for features used from the Copilot Facade. Other features are not mocked.

use Revolution\Copilot\Facades\Copilot;

Copilot::fake('2');

$response = Copilot::run(prompt: '1 + 1');

// Pest
expect($response->content())->toBe('2');
// PHPUnit
$this->assertEquals('2', $response->content());

When calling multiple times with Copilot::start()

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Contracts\CopilotSession;

Copilot::fake([
    '*' => Copilot::sequence()
            ->push(Copilot::response('2'))
            ->push(Copilot::response('4')),
]);

Copilot::start(function (CopilotSession $session) use (&$response1, &$response2) {
    $response1 = $session->sendAndWait(prompt: '1 + 1');
    $response2 = $session->sendAndWait(prompt: '2 + 2');
});

expect($response1->content())->toBe('2');

Assertions

Assert that a specific prompt was called.

Copilot::assertPrompt('1 + *');

Assert that a prompt was not called.

Copilot::assertNotPrompt('1 + *');

Assert the number of prompts called.

Copilot::assertPromptCount(3);

Assert that no prompts were called.

Copilot::assertNothingSent();

Prevent stray requests

Prevent all JSON-RPC requests. If called, an exception Revolution\Copilot\Exceptions\StrayRequestException is thrown.

Copilot::preventStrayRequests();

When you want to allow only some commands.

Copilot::preventStrayRequests(allow: ['ping']);

Stop prevention.

Copilot::preventStrayRequests(false);

Only JSON-RPC requests are prevented, so starting a client is not prevented.

Documentation

English

• Laravel Copilot SDK Documentation
• Getting Started Guide

Japanese

• docs/jp
• Laravel Copilot SDK Documentation

Our other packages

• laravel-boost-copilot-cli
• laravel-boost-phpstorm-copilot

License

MIT