Chromium Console Logger

Capture browser console logs and exceptions from any Chromium browser to local files. Perfect for debugging, LLM-assisted development, and analyzing client-side JavaScript.

A standalone CLI tool that connects to Chromium-based browsers (Chrome, Vivaldi, Brave, Edge) via the Chrome DevTools Protocol (CDP) to capture JavaScript console events and uncaught exceptions, streaming them to local NDJSON files with automatic reconnection and log rotation.

Why Use This?

🤖 Perfect for LLM-Assisted Development

When coding with AI assistants like Claude, ChatGPT, or Cursor, you no longer need to:

Take screenshots of browser console errors
Copy-paste log messages back and forth
Describe what you're seeing in the console

Instead, your AI coding assistant can directly read the console logs from the NDJSON file. This eliminates round trips and lets the AI see exactly what's happening in your browser in real-time.

Example workflow:

# Start capturing console logs
chromium-console-logger --tui

# In your AI chat:
"Check browser-console.ndjson - there's an error when I click the submit button"

The AI can now see the exact error, stack trace, and context without you having to manually relay the information.

🖥️ Interactive Terminal UI

Monitor your browser console in real-time with a beautiful terminal interface:

Live event stream - See console logs and errors as they happen
Tab filtering - Focus on specific browser tabs
Search & filter - Find specific log messages instantly
Keyboard navigation - Full keyboard control for efficient debugging
Pause/resume - Control the flow of events

Traditional Development Benefits

Debug production-like issues locally without browser DevTools open
Analyze console patterns across multiple tabs and sessions
Automatic reconnection when browser restarts
Machine-readable NDJSON format for easy parsing and analysis
Filter by log level, tab, or URL

Quick Start

# Install globally
npm install -g chromium-console-logger

# Launch Chrome with remote debugging
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Start capturing with interactive Terminal UI
chromium-console-logger --tui

That's it! All console logs and exceptions from your browser are now being captured to browser-console.ndjson and displayed in a beautiful interactive terminal interface.

Using with AI Coding Assistants

Once running, your AI assistant can read the log file directly:

# In your AI chat (Claude, ChatGPT, Cursor, etc.):
"Read browser-console.ndjson and help me debug the authentication error"

The AI sees the exact console output, stack traces, and timing - no screenshots or copy-pasting needed!

Use Cases

AI-Assisted Development

LLM Pair Programming: Let your AI assistant (Claude, ChatGPT, Cursor) read console logs directly
Faster Debugging: Eliminate screenshot/copy-paste round trips when working with AI
Context Sharing: Give your AI the full browser console context automatically

Traditional Development

Local Development: Capture logs from multiple tabs without keeping DevTools open
Bug Reproduction: Record console output during bug reproduction steps
Performance Analysis: Analyze console patterns and timing across sessions
Automated Testing: Capture browser logs during E2E test runs
Client Debugging: Monitor production-like scenarios locally

Features

Interactive Terminal UI

Real-time Monitoring: Beautiful terminal interface showing live console events
Syntax Highlighting: Color-coded log levels and event types
Search & Filter: Find specific messages instantly with built-in search
Tab Management: Monitor specific browser tabs or switch between them
Keyboard Controls: Full keyboard navigation (pause, clear, filter, search)
Live Statistics: See event counts and connection status at a glance

Core Capabilities

CDP Integration: Connects to any Chromium-based browser via Chrome DevTools Protocol
NDJSON Logging: Streams events to newline-delimited JSON files for easy parsing
AI-Friendly: Perfect for LLM-assisted development - no more screenshot sharing
Auto-Reconnection: Automatically reconnects when the browser restarts with exponential backoff
Event Capture: Captures all console methods (log, info, warn, error, debug, trace) and uncaught exceptions
Flexible Filtering: Filter events by type, level, and target URL
Log Rotation: Automatic log file rotation based on size with configurable retention

Installation

Option 1: Install Globally (Recommended)

npm install -g chromium-console-logger

Then use it anywhere:

chromium-console-logger --tui

Option 2: Use with npx (No Installation)

npx chromium-console-logger --tui

Option 3: Install Locally in Project

npm install chromium-console-logger
npx chromium-console-logger --tui

Option 4: Install from Source

git clone https://github.com/maelos-software/chromium-console-logger.git
cd chromium-console-logger
npm install
npm run build
npm install -g .

Quick Start

1. Launch Browser with CDP Enabled

Launch your Chromium-based browser with remote debugging enabled:

Vivaldi:

/Applications/Vivaldi.app/Contents/MacOS/Vivaldi --remote-debugging-port=9222

Chrome:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

Brave:

/Applications/Brave\ Browser.app/Contents/MacOS/Brave\ Browser --remote-debugging-port=9222

Edge:

/Applications/Microsoft\ Edge.app/Contents/MacOS/Microsoft\ Edge --remote-debugging-port=9222

2. Start the Capture Tool

npx chromium-console-logger

The tool will connect to your browser and start capturing console events to browser-console.ndjson in the current directory.

Usage

Basic Usage

# Start with Terminal UI (recommended)
chromium-console-logger --tui

# List all available browser tabs
chromium-console-logger --list-tabs

# Monitor only specific tabs (by index)
chromium-console-logger --tabs 1,3,4

# Headless mode with default settings
chromium-console-logger

# Enable verbose logging
chromium-console-logger --verbose

# Specify custom log file
chromium-console-logger --log-file logs/console.ndjson

# Filter by console level
chromium-console-logger --level error --level warn

# Connect to custom host/port
chromium-console-logger --host 192.168.1.100 --port 9223

# Filter by target URL
chromium-console-logger --target-url-substring myapp

# Combine TUI with filters and specific tabs
chromium-console-logger --tui --tabs 2,3 --level error --level warn

Tab Management

List Available Tabs:

chromium-console-logger --list-tabs

This will display all open browser tabs with their indices, titles, URLs, and IDs:

Found 4 browser tab(s):

[1] Breaking News, Latest News and Videos | CNN
    URL: https://www.cnn.com/
    ID:  686F8C3B6916D48FD7C8E1386FA80481

[2] GitHub Repository
    URL: https://github.com/user/repo
    ID:  340D008EED3D48A570FADB53D3E45CC4
...

Monitor Specific Tabs:

# Monitor only tabs 1 and 3
chromium-console-logger --tabs 1,3

# Use with TUI for interactive monitoring
chromium-console-logger --tui --tabs 2,4

Terminal UI (TUI) Mode

The interactive Terminal UI provides a powerful, real-time view of your browser console:

Features:

Live Event Stream: See console logs, warnings, errors, and exceptions as they happen
Color-Coded Events: Different colors for log levels (info, warn, error, etc.)
Tab Filtering: Monitor specific browser tabs or all tabs at once
Search Functionality: Find specific log messages with / search
Pause/Resume: Control the flow of events without stopping capture
Event Details: View full stack traces and exception details
Statistics: Real-time counts of events by type and level

Keyboard Controls:

Key	Action
`q`	Quit the application
`p`	Pause/Resume event capture
`c`	Clear the events display
`/`	Search for specific text in events
`v`	Toggle verbose mode (show full event details)
`t`	Toggle Tab Navigation mode
`a`	Show all tabs (remove filter)
`1-9`	Quickly select tab by number
`↑↓`	Navigate tabs (in Tab Nav mode) or scroll events
`Enter`	Confirm tab selection (in Tab Nav mode)

Tab Navigation Mode:

Press t to enter Tab Navigation mode (border turns yellow)
Use arrow keys to highlight different tabs
Press Enter to select the highlighted tab
The selected tab will be highlighted in cyan
Press t again to return to Events mode

Perfect for AI-Assisted Development:

The TUI makes it easy to spot errors and share context with your AI assistant. When you see an error in the TUI, simply tell your AI to read the log file - it will see the same events you're seeing in real-time.

CLI Options

Option	Description	Default
`--host <string>`	CDP host address	`127.0.0.1`
`--port <number>`	CDP port number	`9222`
`--log-file <path>`	Path to log file	`browser-console.ndjson`
`--include-console <boolean>`	Include console events	`true`
`--include-exceptions <boolean>`	Include exception events	`true`
`--level <string...>`	Console levels to capture (can specify multiple)	`[]` (all)
`--verbose`	Enable verbose logging	`false`
`--tui`	Enable Terminal UI mode	`false`
`--list-tabs`	List all available browser tabs and exit	`false`
`--tabs <numbers>`	Monitor only specific tabs by index (comma-separated)	-
`--target-url-substring <string>`	Filter targets by URL substring	-
`--max-size-bytes <number>`	Maximum log file size before rotation	`Infinity`
`--rotate-keep <number>`	Number of rotated files to keep	`5`
`--stdout`	Output logs to stdout instead of file	`false`

Examples

List available tabs:

chromium-console-logger --list-tabs

Monitor specific tabs only:

# Monitor tabs 1, 2, and 4
chromium-console-logger --tabs 1,2,4

Capture only errors and warnings:

chromium-console-logger --level error --level warn

Enable log rotation at 10MB:

chromium-console-logger --max-size-bytes 10000000 --rotate-keep 10

Capture only exceptions:

chromium-console-logger --include-console false

Filter by target URL:

chromium-console-logger --target-url-substring localhost:3000

Monitor specific tabs with TUI:

chromium-console-logger --tui --tabs 2,3 --level error

Output to stdout instead of file:

# Stream logs to stdout (useful for piping)
chromium-console-logger --stdout

# Pipe to jq for filtering
chromium-console-logger --stdout | jq 'select(.type == "error")'

# Pipe to grep
chromium-console-logger --stdout | grep "API error"

# Save to custom location
chromium-console-logger --stdout > /tmp/browser-logs.ndjson

Full configuration example:

chromium-console-logger \
  --host 127.0.0.1 \
  --port 9222 \
  --log-file logs/app-console.ndjson \
  --tabs 1,3 \
  --level error --level warn \
  --verbose \
  --target-url-substring myapp \
  --max-size-bytes 5000000 \
  --rotate-keep 5

Advanced Features

Stdout Mode

Output logs directly to stdout instead of a file. Perfect for:

Piping to other tools (jq, grep, awk)
Integration with log aggregation systems
Real-time processing
Custom log destinations

# Stream to stdout
chromium-console-logger --stdout

# Filter errors with jq
chromium-console-logger --stdout | jq 'select(.type == "error")'

# Search for specific messages
chromium-console-logger --stdout | grep "authentication"

# Count log types
chromium-console-logger --stdout | jq -r '.type' | sort | uniq -c

# Filter logs from a specific tab by title
chromium-console-logger --stdout | jq 'select(.tab.title == "My App - Dashboard")'

# Group errors by tab
chromium-console-logger --stdout | jq -r 'select(.type == "error") | .tab.title' | sort | uniq -c

# Get all unique tab titles
chromium-console-logger --stdout | jq -r '.tab.title' | sort -u

# Filter by tab ID
chromium-console-logger --stdout | jq 'select(.tab.id == "E4E5E5E5E5E5E5E5E5E5E5E5E5E5E5E5")'

# Combine with other filters
chromium-console-logger --stdout --level error --tabs 1,2

NDJSON Output Format

Each line in the log file is a valid JSON object representing a captured event.

Console Event Example

{
  "ts": 1701234567890,
  "event": "console",
  "type": "log",
  "url": "http://localhost:3000/app.js",
  "args": ["User logged in", { "userId": 123 }],
  "stackTrace": {
    "callFrames": [
      {
        "functionName": "login",
        "url": "http://localhost:3000/app.js",
        "lineNumber": 42,
        "columnNumber": 10
      }
    ]
  },
  "tab": {
    "id": "E4E5E5E5E5E5E5E5E5E5E5E5E5E5E5E5",
    "title": "My App - Dashboard"
  }
}

Exception Event Example

{
  "ts": 1701234567892,
  "event": "exception",
  "type": "exception",
  "url": "http://localhost:3000/app.js",
  "stackTrace": {
    "callFrames": [
      {
        "functionName": "processData",
        "url": "http://localhost:3000/app.js",
        "lineNumber": 156,
        "columnNumber": 15
      }
    ]
  },
  "exceptionDetails": {
    "text": "Uncaught",
    "exception": {
      "type": "object",
      "subtype": "error",
      "className": "Error",
      "description": "Error: Invalid data format"
    }
  },
  "tab": {
    "id": "E4E5E5E5E5E5E5E5E5E5E5E5E5E5E5E5",
    "title": "My App - Dashboard"
  }
}

Event Fields

Field	Type	Description
`ts`	number	Timestamp in epoch milliseconds
`event`	string	Event category: `"console"` or `"exception"`
`type`	string	Event type: `"log"`, `"warn"`, `"error"`, `"info"`, `"debug"`, `"trace"`, or `"exception"`
`url`	string	Source URL where the event occurred (script file or page URL)
`args`	array	Console arguments (console events only)
`stackTrace`	object	CDP StackTrace object (when available)
`exceptionDetails`	object	Full exception details (exception events only)
`tab`	object	Tab metadata: `id` (CDP target ID) and `title` (page title)

Log Rotation

When --max-size-bytes is specified, the tool automatically rotates log files:

When the current log file exceeds the size threshold, it's renamed to <filename>.1
Existing rotated files are shifted: .1 → .2, .2 → .3, etc.
Files beyond the --rotate-keep limit are deleted
A new log file is created

Example with --rotate-keep 3:

browser-console.ndjson      (current)
browser-console.ndjson.1    (most recent rotation)
browser-console.ndjson.2
browser-console.ndjson.3    (oldest, will be deleted on next rotation)

Reconnection Behavior

The tool implements robust reconnection logic:

Exponential Backoff: Retries with increasing delays (100ms, 200ms, 400ms, 800ms, ...)
Maximum Delay: Caps at 5 seconds between attempts
Jitter: Adds ±20% random variation to prevent thundering herd
Continuous Retry: Never gives up unless you send SIGINT (Ctrl+C)
Target Reattachment: Automatically reattaches if the target closes

Graceful Shutdown

Press Ctrl+C to gracefully shut down the tool:

Flushes all buffered log data to disk
Closes the log file handle cleanly
Disconnects from CDP
Exits with status code 0

Troubleshooting

"Failed to connect to CDP"

Problem: The tool can't connect to the browser.

Solutions:

Ensure the browser is running with --remote-debugging-port=9222
Check that no other process is using port 9222
Verify the host and port with --host and --port flags
Use --verbose to see detailed connection attempts

"No suitable target found"

Problem: The tool can't find a page target to attach to.

Solutions:

Open at least one tab in the browser
Check if --target-url-substring is too restrictive
Use --verbose to see available targets

"Error writing to log file"

Problem: The tool can't write to the log file.

Solutions:

Check file permissions in the target directory
Ensure sufficient disk space
Verify the path with --log-file is valid

Events Not Being Captured

Problem: Console events or exceptions aren't appearing in the log.

Solutions:

Check filter settings (--include-console, --include-exceptions, --level)
Verify the target URL matches with --target-url-substring
Use --verbose to see if events are being received
Ensure the browser tab is active and not paused in debugger

Log File Growing Too Large

Problem: The log file is consuming too much disk space.

Solutions:

Enable log rotation with --max-size-bytes
Adjust --rotate-keep to control retention
Use level filtering to reduce event volume
Filter by target URL to capture only relevant pages

Development

Build from Source

# Clone the repository
git clone https://github.com/maelos-software/chromium-console-logger.git
cd chromium-console-logger

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Run locally
node dist/index.js

Project Structure

chromium-console-logger/
├── src/
│   ├── index.ts          # CLI entry point
│   ├── cdpClient.ts      # CDP connection and event handling
│   ├── logWriter.ts      # NDJSON file writing and rotation
│   ├── types.ts          # TypeScript type definitions
│   ├── util.ts           # Utility functions
│   └── *.test.ts         # Test files
├── bin/
│   └── chromium-console-logger  # Executable script
├── dist/                 # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

License

MIT

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for development guidelines.

Development Setup

# Clone and install
git clone https://github.com/maelos-software/chromium-console-logger.git
cd chromium-console-logger
npm install

# Run validation checks
npm run validate  # Runs typecheck, lint, format check, and tests

# Build
npm run build

CI/CD

This project uses GitHub Actions for continuous integration:

✅ Type checking with TypeScript
✅ Linting with ESLint
✅ Format checking with Prettier
✅ Unit tests with Jest (70 tests)
✅ Tested on Node.js 16.x, 18.x, and 20.x

All checks must pass before merging.

Support

For issues, questions, or feature requests, please open an issue on GitHub.

Name		Name	Last commit message	Last commit date
Latest commit History 62 Commits
.github/workflows		.github/workflows
.husky		.husky
bin		bin
scripts		scripts
src		src
.eslintignore		.eslintignore
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
.versionrc.json		.versionrc.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

maelos-software/chromium-console-logger

Folders and files

Latest commit

History

Repository files navigation

Chromium Console Logger

Why Use This?

🤖 Perfect for LLM-Assisted Development

🖥️ Interactive Terminal UI

Traditional Development Benefits

Quick Start

Using with AI Coding Assistants

Use Cases

AI-Assisted Development

Traditional Development

Features

Interactive Terminal UI

Core Capabilities

Installation

Option 1: Install Globally (Recommended)

Option 2: Use with npx (No Installation)

Option 3: Install Locally in Project

Option 4: Install from Source

Quick Start

1. Launch Browser with CDP Enabled

2. Start the Capture Tool

Usage

Basic Usage

Tab Management

Terminal UI (TUI) Mode

CLI Options

Examples

Advanced Features

Stdout Mode

NDJSON Output Format

Console Event Example

Exception Event Example

Event Fields

Log Rotation

Reconnection Behavior

Graceful Shutdown

Troubleshooting

"Failed to connect to CDP"

"No suitable target found"

"Error writing to log file"

Events Not Being Captured

Log File Growing Too Large

Development

Build from Source

Project Structure

License

Contributing

Development Setup

CI/CD

Support

About

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages