browser-debugger-cli: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Agent-Friendly Discovery (START HERE)

bdg is self-documenting - use these FIRST:

bdg --help --json                       # All commands, flags, exit codes
bdg cdp --list                          # All CDP domains
bdg cdp Network --list                  # Methods in a domain
bdg cdp Network.getCookies --describe   # Full method schema
bdg cdp --search cookie                 # Search methods

Key Principle: Discover capabilities programmatically before implementation.

---

Essential Patterns

CommandRunner (src/commands/shared/CommandRunner.ts)

All commands use this wrapper for consistent error handling and JSON/human output:

await runCommand(
  async () => {
    const response = await ipcFunction(params);
    return response.status === 'error'
      ? { success: false, error: response.error }
      : { success: true, data: response.data };
  },
  options,
  formatFunction
);

Error Handling

Convention: process.exit and console.error belong at entrypoints only (src/index.ts, src/cli.ts, CommandRunner, signal handlers, daemon bootstrap). Below that layer, choose one of two structured styles:

• Throw CommandError — from deep helpers when the caller can't reasonably recover. CommandRunner catches and formats.
• Return { success, error?, exitCode?, errorContext? } — from composable operations whose callers branch on failure (e.g., CLI command action handlers, FetchResult).

Never mix: a helper shouldn't log-and-exit when its surrounding function already returns a structured shape.

import { CommandError } from '@/errors/index.js';
import { EXIT_CODES } from '@/utils/exitCodes.js';

throw new CommandError(
  'Session not found',
  { suggestion: 'Start a session with: bdg <url>' },
  EXIT_CODES.RESOURCE_NOT_FOUND
);

Message Centralization (src/ui/messages/)

All user-facing strings must use centralized functions - no inline strings.