sessions Permission
6 min readsessions Permission
Overview
- Permission string:
"sessions" - Grants access to
chrome.sessionsAPI - Query and restore recently closed tabs/windows, access cross-device tabs
API Methods
chrome.sessions.getRecentlyClosed(filter?)
Gets a list of recently closed tabs/windows.
interface Filter {
maxResults?: number; // Default: 25, Maximum: 25
}
interface Session {
lastModified: number; // Timestamp in milliseconds
tab?: Tab; // Present if closed item was a tab
window?: Window; // Present if closed item was a window
}
// Returns array of Session objects
const sessions = await chrome.sessions.getRecentlyClosed({ maxResults: 10 });
chrome.sessions.restore(sessionId?)
Restores a closed tab or window.
// Omit sessionId to restore most recently closed item
const restored = await chrome.sessions.restore();
// Restore a specific session
const restored = await chrome.sessions.restore(sessionId);
// Returns the restored Session object
chrome.sessions.getDevices(filter?)
Gets tabs from other signed-in devices.
interface Filter {
maxResults?: number;
}
interface Device {
deviceName: string; // Name of the other device
sessions: Session[]; // Sessions from that device
}
// Returns array of Device objects
const devices = await chrome.sessions.getDevices({ maxResults: 10 });
Types
Session
{
lastModified: number; // Unix timestamp
tab?: chrome.tabs.Tab; // Tab object (either tab OR window, not both)
window?: chrome.windows.Window; // Window object
}
Device
{
deviceName: string; // e.g., "Mike's MacBook Pro"
sessions: Session[]; // Array of sessions from this device
}
Constants
chrome.sessions.MAX_SESSION_RESULTS— Maximum number of sessions returned (25)
Events
chrome.sessions.onChanged— Fires when the recently closed list changeschrome.sessions.onChanged.addListener(() => { console.log("Recently closed sessions changed"); });
Manifest Declaration
{
"permissions": ["sessions"]
}
Note: Also needs "tabs" permission to see tab URLs/titles.
Use Cases
Session Restore UI
Build a “recently closed” dropdown showing tabs the user can reopen:
async function getRecentlyClosedTabs() {
const sessions = await chrome.sessions.getRecentlyClosed();
return sessions
.filter(s => s.tab)
.map(s => ({
title: s.tab?.title,
url: s.tab?.url,
lastModified: s.lastModified
}));
}
“Undo Close Tab” Feature
Implement keyboard shortcut to restore the most recent tab:
// Restore most recently closed tab
async function undoCloseTab() {
const sessions = await chrome.sessions.getRecentlyClosed({ maxResults: 1 });
if (sessions.length > 0) {
await chrome.sessions.restore(sessions[0].tab?.sessionId);
}
}
Cross-Device Tab Access
Show tabs from other signed-in devices:
async function getCrossDeviceTabs() {
const devices = await chrome.sessions.getDevices();
const allTabs: Array<{ device: string; title: string; url: string }> = [];
for (const device of devices) {
for (const session of device.sessions) {
if (session.tab) {
allTabs.push({
device: device.deviceName,
title: session.tab.title || "Untitled",
url: session.tab.url || ""
});
}
}
}
return allTabs;
}
Store Session Snapshots with @theluckystrike/webext-storage
import { createStorage, defineSchema } from "@theluckystrike/webext-storage";
const schema = defineSchema({
sessionSnapshots: [] as Array<{
id: string;
tabs: Array<{ title: string; url: string }>;
savedAt: number;
}>
});
const storage = createStorage({ schema });
async function saveSessionSnapshot() {
const sessions = await chrome.sessions.getRecentlyClosed({ maxResults: 25 });
const snapshot = {
id: crypto.randomUUID(),
tabs: sessions
.filter(s => s.tab)
.map(s => ({ title: s.tab!.title || "", url: s.tab!.url || "" })),
savedAt: Date.now()
};
const snapshots = await storage.get("sessionSnapshots");
await storage.set("sessionSnapshots", [snapshot, ...snapshots].slice(0, 10));
}
Cross-references
- tabs — Required to access tab URLs/titles
- patterns/sessions-api — Session management patterns
- guides/tab-management — Tab management guide
Frequently Asked Questions
What can I do with the sessions API?
chrome.sessions allows your extension to query and restore recently closed tabs and windows, useful for session management extensions.
Can I sync sessions across devices?
Sessions API provides local session data only. For cross-device sync, you’d need to implement your own cloud storage. —
Part of the Chrome Extension Guide by theluckystrike. Built at zovo.one.