Session context and filtering

Use SessionContext and SessionListFilter in Laravel Copilot SDK to inspect and filter sessions by workspace and Git metadata.

Session context and filtering

Since GitHub Copilot SDK v0.1.24, sessions include context with working directory and Git metadata. You can also filter session lists by this context.

SessionContext

SessionContext stores working directory and Git repository information from when a session was created.

Properties

• cwd (string): Absolute path of the working directory
• gitRoot (?string): Git repository root directory (null outside a Git repository)
• repository (?string): GitHub repository in owner/repo format (for example invokable/laravel-copilot-sdk)
• branch (?string): Current Git branch name

Example

use Revolution\Copilot\Facades\Copilot;

// Get session list
$sessions = Copilot::client()->listSessions();

foreach ($sessions as $metadata) {
    echo "Session: {$metadata->sessionId}\n";

    if ($metadata->context !== null) {
        echo "  Working directory: {$metadata->context->cwd}\n";

        if ($metadata->context->repository !== null) {
            echo "  Repository: {$metadata->context->repository}\n";
            echo "  Branch: {$metadata->context->branch}\n";
        }
    }
}

SessionListFilter

Use SessionListFilter to fetch only sessions from a specific working directory or repository.

Properties

• cwd (?string): Exact-match filter by working directory
• gitRoot (?string): Filter by Git root directory
• repository (?string): Filter by repository in owner/repo format
• branch (?string): Filter by branch name

Examples

Pass filters as an array

use Revolution\Copilot\Facades\Copilot;

// Get only sessions for a specific repository
$sessions = Copilot::client()->listSessions([
    'repository' => 'invokable/laravel-copilot-sdk',
]);

// Get sessions on a specific branch
$sessions = Copilot::client()->listSessions([
    'repository' => 'owner/repo',
    'branch' => 'feature/new-feature',
]);

// Get sessions for a specific working directory
$sessions = Copilot::client()->listSessions([
    'cwd' => '/home/user/projects/my-app',
]);

Use the SessionListFilter class

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionListFilter;

$filter = new SessionListFilter(
    repository: 'owner/repo',
    branch: 'main',
);

$sessions = Copilot::client()->listSessions($filter);

session.context_changed event

When the working directory changes during a session, a session.context_changed event is emitted.

Event type

use Revolution\Copilot\Enums\SessionEventType;

SessionEventType::SESSION_CONTEXT_CHANGED; // 'session.context_changed'

Event data

The event data includes updated context details:

use Revolution\Copilot\Facades\Copilot;

Copilot::start(function ($session) {
    $session->on(function ($event) {
        if ($event->type === 'session.context_changed') {
            $data = $event->data;

            echo "Working directory changed\n";
            echo "  cwd: {$data['cwd']}\n";
            echo "  repository: {$data['repository']}\n";
            echo "  branch: {$data['branch']}\n";
        }
    });

    $response = $session->sendAndWait(
        prompt: 'Change to a different directory and list files',
    );
});

SessionMetadata

SessionMetadata now includes a context property.

New property

• context (?SessionContext): Working directory and Git metadata for the session

Example

use Revolution\Copilot\Facades\Copilot;

$sessions = Copilot::client()->listSessions();

foreach ($sessions as $metadata) {
    echo "Session ID: {$metadata->sessionId}\n";
    echo "Start time: {$metadata->startTime}\n";

    // context is optional, so null-check it
    if ($metadata->context !== null) {
        echo "Context:\n";
        echo "  Working directory: {$metadata->context->cwd}\n";

        if ($metadata->context->repository !== null) {
            echo "  Repository: {$metadata->context->repository}\n";
        }

        if ($metadata->context->branch !== null) {
            echo "  Branch: {$metadata->context->branch}\n";
        }
    }

    echo "\n";
}

Practical examples

Get sessions for a specific project

use Revolution\Copilot\Facades\Copilot;

// Get only sessions in the Laravel Copilot SDK project
$sessions = Copilot::client()->listSessions([
    'repository' => 'invokable/laravel-copilot-sdk',
]);

// Show active sessions
foreach ($sessions as $metadata) {
    echo "{$metadata->sessionId}: {$metadata->summary}\n";
    echo "  Branch: {$metadata->context->branch}\n";
}

Manage sessions on feature branches

use Revolution\Copilot\Facades\Copilot;

$sessions = Copilot::client()->listSessions();

$featureSessions = array_filter($sessions, function ($metadata) {
    return $metadata->context !== null
        && str_starts_with($metadata->context->branch ?? '', 'feature/');
});

// Group sessions by feature branch
$byBranch = [];
foreach ($featureSessions as $metadata) {
    $branch = $metadata->context->branch;
    $byBranch[$branch][] = $metadata;
}

foreach ($byBranch as $branch => $sessions) {
    echo "{$branch}: " . count($sessions) . " sessions\n";
}

Organize sessions by working directory

use Revolution\Copilot\Facades\Copilot;

$sessions = Copilot::client()->listSessions();

// Group by working directory
$byCwd = [];
foreach ($sessions as $metadata) {
    if ($metadata->context !== null) {
        $cwd = $metadata->context->cwd;
        $byCwd[$cwd][] = $metadata;
    }
}

// Show count per directory
foreach ($byCwd as $cwd => $sessions) {
    echo "{$cwd}: " . count($sessions) . " sessions\n";
}

Notes

• context includes Git fields (gitRoot, repository, branch) only if the session was created inside a Git repository.
• The context field is available with Copilot CLI v0.0.409 or later. Older versions return null.
• Filtering is exact match only. Partial match and wildcards are not supported.
• All SessionListFilter fields are optional. If you pass no filters, all sessions are returned.

For the latest updates, see the GitHub repository.