Chrome DevTools for coding agents
/**
* @license
* Copyright 2025 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
import zlib from 'node:zlib';
import type {ParsedArguments} from '../config/mcp-options.js';
import {zod, DevTools} from '../third_party/index.js';
import {
parseRawTraceBuffer,
traceResultIsSuccess,
type InsightName,
type TraceResult,
} from '../processors/PerformanceTrace.js';
import {logger} from '../utils/logger.js';
import {NetworkOverridesFormatter} from '../formatters/NetworkOverridesFormatter.js';
import {ToolCategory} from './categories.js';
import {
definePageTool,
type Context,
type Response,
type ContextPage,
type PageToolFactory,
} from './ToolDefinition.js';
const filePathSchema = zod
.string()
.optional()
.describe(
'The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).',
);
export const startTrace: PageToolFactory = definePageTool(() => ({
name: 'performance_start_trace',
description: `Start a performance trace on the target webpage. Use to find frontend performance issues, Core Web Vitals (LCP, INP, CLS), and improve page load speed.`,
annotations: {
category: ToolCategory.PERFORMANCE,
readOnlyHint: false,
},
schema: {
reload: zod
.boolean()
.default(true)
.describe(
'Determines if, once tracing has started, the target page should be automatically reloaded. Navigate the page to the right URL using the navigate_page tool BEFORE starting the trace if reload or autoStop is set to true.',
),
autoStop: zod
.boolean()
.default(true)
.describe(
'Determines if the trace recording should be automatically stopped.',
),
ignoreCache: zod
.boolean()
.optional()
.describe(
'Whether to bypass the HTTP cache when reloading the page, to measure a cold page load. Only applies if reload is true. Active network mocks always disable the page HTTP cache.',
),
filePath: filePathSchema,
},
blockedByDialog: true,
concurrency: 'exclusive',
verifyFilesSchema: {
filePath: true,
},
handler: async (request, response, context) => {
if (context.isRunningPerformanceTrace()) {
response.appendResponseLine(
'Error: a performance trace is already running. Use performance_stop_trace to stop it. Only one trace can be running at any given time.',
);
return;
}
const page = request.page;
const networkOverrides = page.listNetworkMocks();
const {warning} = new NetworkOverridesFormatter(networkOverrides).toJSON();
if (warning) {
response.appendResponseLine(warning);
}
page.setIsRunningPerformanceTrace(true);
const pageUrlForTracing = page.pptrPage.url();
try {
if (request.params.reload) {
// Before starting the recording, navigate to about:blank to clear out any state.
// We use `load` because `networkidle0` is known to be flaky for about:blank in Puppeteer.
await page.pptrPage.goto('about:blank', {
waitUntil: 'load',
});
}
const categories = [
'-*',
...DevTools.TracingDefaultCategories,
// These categories are optional in DevTools, but enabled by default in the DevTools UI, so we enable them here too.
...DevTools.TracingOptionalCategories.JsSampling,
...DevTools.TracingOptionalCategories.Screenshot,
];
await page.pptrPage.tracing.start({
categories,
bufferSize: 1200 * 1000,
});
if (request.params.reload) {
const ignoreCache =
request.params.ignoreCache === true && networkOverrides.length === 0;
if (ignoreCache) {
// Disable the HTTP cache so that the main document and all
// subresources are fetched from the network, like a hard reload.
await page.pptrPage.setCacheEnabled(false);
}
try {
await page.pptrPage.goto(pageUrlForTracing, {
waitUntil: ['load'],
});
} finally {
if (ignoreCache) {
await page.pptrPage.setCacheEnabled(true);
}
}
}
if (request.params.autoStop) {
await new Promise(resolve => setTimeout(resolve, 5_000));
await stopTracingAndAppendOutput(
page,
response,
context,
request.params.filePath,
);
} else {
response.appendResponseLine(
`The performance trace is being recorded. Use performance_stop_trace to stop it.`,
);
}
} catch (error) {
// If a setup step (navigation, tracing.start) throws before
// stopTracingAndAppendOutput runs, the running flag would otherwise stay
// stuck `true` for the rest of the session, blocking all future traces.
// Unwind here: stop tracing if it was started and clear the flag. When
// autoStop already ran stopTracingAndAppendOutput the flag is already
// false and this is a no-op.
if (context.isRunningPerformanceTrace()) {
try {
await page.pptrPage.tracing.stop();
} catch {
// Tracing may not have started yet; ignore.
}
page.setIsRunningPerformanceTrace(false);
}
throw error;
}
},
}));
export const stopTrace: PageToolFactory = definePageTool(
(args: ParsedArguments) => ({
name: 'performance_stop_trace',
description:
'Stop the active performance trace recording on the target webpage.',
annotations: {
category: ToolCategory.PERFORMANCE,
readOnlyHint: false,
},
schema: {
filePath: filePathSchema,
},
blockedByDialog: true,
concurrency: 'exclusive',
verifyFilesSchema: {
filePath: true,
},
handler: async (request, response, context) => {
if (!context.isRunningPerformanceTrace()) {
response.appendResponseLine(
'Error: no active performance trace recording to stop.',
);
return;
}
const page = request.page;
if (!page.isRunningPerformanceTrace()) {
const tracedPage = context
.getPages()
.find(p => p.isRunningPerformanceTrace());
const pageHint = tracedPage ? ` on page ${tracedPage.id}` : '';
const actionHint = tracedPage
? args.pageIdRouting
? `Pass pageId: ${tracedPage.id} to performance_stop_trace to stop it.`
: `Select page ${tracedPage.id} with select_page first, then call performance_stop_trace.`
: 'Select the page that started the trace and try again.';
response.appendResponseLine(
`Error: the active performance trace is running${pageHint}, not on page ${page.id}. ${actionHint}`,
);
return;
}
const {warning} = new NetworkOverridesFormatter(
page.listNetworkMocks(),
).toJSON();
if (warning) {
response.appendResponseLine(warning);
}
await stopTracingAndAppendOutput(
page,
response,
context,
request.params.filePath,
);
},
}),
);
export const analyzeInsight: PageToolFactory = definePageTool(() => ({
name: 'performance_analyze_insight',
description:
'Provides more detailed information on a specific Performance Insight of an insight set that was highlighted in the results of a trace recording.',
annotations: {
category: ToolCategory.PERFORMANCE,
readOnlyHint: true,
},
schema: {
insightSetId: zod
.string()
.describe(
'The id for the specific insight set. Only use the ids given in the "Available insight sets" list.',
),
insightName: zod
.string()
.describe(
'The name of the Insight you want more information on. For example: "DocumentLatency" or "LCPBreakdown"',
),
},
blockedByDialog: false,
concurrency: 'exclusive',
verifyFilesSchema: {},
handler: async (request, response, context) => {
const lastRecording = context.recordedTraces().at(-1);
if (!lastRecording) {
response.appendResponseLine(
'No recorded traces found. Record a performance trace so you have Insights to analyze.',
);
return;
}
response.attachTraceInsight(
lastRecording,
request.params.insightSetId,
request.params.insightName as InsightName,
);
},
}));
async function stopTracingAndAppendOutput(
page: ContextPage,
response: Response,
context: Context,
filePath?: string,
): Promise<void> {
try {
const traceEventsBuffer = await page.pptrPage.tracing.stop();
if (filePath && traceEventsBuffer) {
let dataToWrite: Uint8Array = traceEventsBuffer;
if (filePath.endsWith('.gz')) {
dataToWrite = await new Promise((resolve, reject) => {
zlib.gzip(traceEventsBuffer, (error, result) => {
if (error) {
reject(error);
} else {
resolve(result);
}
});
});
}
const file = await context.saveFile(
dataToWrite,
filePath,
filePath.endsWith('.gz') ? '.gz' : '.json',
);
response.appendResponseLine(
`The raw trace data was saved to ${file.filename}.`,
);
}
const result = await parseRawTraceBuffer(traceEventsBuffer, {
cpuThrottling: page.cpuThrottlingRate,
networkThrottling: page.networkConditions ?? undefined,
});
response.appendResponseLine('The performance trace has been stopped.');
if (traceResultIsSuccess(result)) {
if (context.isCruxEnabled()) {
await populateCruxData(result);
}
context.storeTraceRecording(result);
response.attachTraceSummary(result);
} else {
throw new Error(
`There was an unexpected error parsing the trace: ${result.error}`,
);
}
} finally {
page.setIsRunningPerformanceTrace(false);
}
}
/** We tell CrUXManager to fetch data so it's available when DevTools.PerformanceTraceFormatter is invoked */
async function populateCruxData(result: TraceResult): Promise<void> {
logger?.('populateCruxData called');
const cruxManager = DevTools.CrUXManager.CrUXManager.instance();
// go/jtfbx. Yes, we're aware this API key is public. ;)
cruxManager.setEndpointForTesting(
'https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=AIzaSyBn5gimNjhiEyA_euicSKko6IlD3HdgUfk',
);
const cruxSetting =
DevTools.Common.Settings.Settings.instance().createSetting('field-data', {
enabled: true,
});
cruxSetting.set({enabled: true});
// Gather URLs to fetch CrUX data for
const urls = [...(result.parsedTrace.insights?.values() ?? [])].map(c =>
c.url.toString(),
);
urls.push(result.parsedTrace.data.Meta.mainFrameURL);
const urlSet = new Set(urls);
if (urlSet.size === 0) {
logger?.('No URLs found for CrUX data');
return;
}
logger?.(
`Fetching CrUX data for ${urlSet.size} URLs: ${Array.from(urlSet).join(', ')}`,
);
const cruxData = await Promise.all(
Array.from(urlSet).map(async url => {
const data = await cruxManager.getFieldDataForPage(url);
logger?.(`CrUX data for ${url}: ${data ? 'found' : 'not found'}`);
return data;
}),
);
result.parsedTrace.metadata.cruxFieldData = cruxData;
}