Chromium Helper
The ultimate toolkit for exploring Chromium and PDFium source code
CLI tool & MCP server for code search, Gerrit integration, and issue tracking
Features • Quick Start • Documentation • Contributing • License
📋 Table of Contents
- Features
- Quick Start
- Documentation
- CLI Tool Usage
- MCP Server Usage
- Installation
- Development
- Contributing
- License
🎯 Features
Why Use Chromium Helper?
- 🚀 Zero Friction - Start searching immediately with
npx, no setup required - 📊 Real-time Data - Direct access to Google's official APIs, same as source.chromium.org
- 🔍 Smart Search - Full Google CodeSearch syntax with regex, filters, and more
- 🤖 AI-Ready - JSON output and MCP integration for automation
- 📱 Cross-Platform - Works on macOS, Linux, and Windows
What Can You Do?
| Feature | Description | Example |
|---|---|---|
| Code Search | Search 20M+ lines with advanced syntax | Find all LOG(INFO) calls |
| Symbol Lookup | Find definitions and usages | Locate Browser::Create |
| Gerrit Review | Check CLs, comments, diffs, try-bots, errors | Review CL 6624568 |
| Issue Tracking | Search and analyze bugs | Find memory leak issues |
| PDFium Support | Full PDFium code and reviews | Check PDFium CL 130850 |
| Commit History | Search by message, author, date | Find recent security fixes |
| Code Ownership | Find OWNERS and reviewers | Who owns chrome/browser? |
Two Ways to Use
- 🔧 CLI Tool (
chromium-helper) - Direct terminal access withchcommands - 🤖 MCP Server (
chromium-codesearch-mcp) - AI integration for Claude Desktop
💡 Why CLI First?
As Armin Ronacher points out, a well-designed CLI is often superior to context-cluttering MCPs. Our CLI works seamlessly with ANY AI coding assistant:
Claude, Cursor, Gemini, or any AI: Just ask them to run:
npx chromium-helper --ai
This dumps comprehensive documentation that the AI can use to help you explore Chromium's codebase without any special configuration or context pollution.
Example AI Prompt:
"Run
npx chromium-helper --aito learn the tool, then help me find all WebRTC-related memory leaks in Chromium"
The AI will:
- Execute the command to understand all capabilities
- Use appropriate search commands with filters
- Analyze results and provide insights
- All without cluttering your AI's context window!
Real Example in Action:
In this example, the AI assistant:
- First runs
npx ch --aito learn the tool - Checks CL 6624568 for test status (✅ all 30/30 bots passed)
- Retrieves review comments with proper formatting
- Provides a comprehensive summary of the CL status and reviewer feedback
- All in a clean, organized output!
🚀 Quick Start
CLI Tool - Use Instantly!
# No installation needed - just use npx!
npx chromium-helper search "LOG(INFO)" --limit 5
npx chromium-helper gerrit bots 6624568
npx chromium-helper --ai # Show comprehensive AI guide
# Or install globally for the short 'ch' alias
npm install -g chromium-helper
ch search "WebContents" --type class
ch gerrit status 6624568 --format json
ch pdfium bots 130850 --failed-only
🤖 Using with AI Coding Assistants (Claude Code, Cursor, Gemini, etc.)
Simply tell your AI assistant:
Run: npx chromium-helper --ai
Then help me [your task here]
Example tasks:
- "Find all uses of base::RefCounted in the codebase"
- "Check if CL 6624568 has passing tests and show me the review comments"
- "Search for recent security fixes in the renderer"
- "Find who owns the password manager code"
- "Help me understand what PDFium CL 130850 does"
- "Show me all failing bots for a specific CL"
MCP Server - For AI Integration
# Add to Claude Desktop (see configuration below)
npm install -g chromium-codesearch-mcp
# Or test directly
echo '{"query": "LOG(INFO)", "limit": 3}' | npx chromium-codesearch-mcp search_chromium_code
📖 Documentation
CLI Tool Documentation
- Quick Help: Run
ch --helpfor command overview - AI Guide: Run
ch --aifor comprehensive usage guide with examples - Full Documentation: See CLI README
Example Commands
# Code search
ch search "CreateWindow" --type function --limit 10
ch symbol Browser::Create
ch file "base/logging.cc" --lines 100-200
# Gerrit operations
ch gerrit status 6624568
ch gerrit comments 6624568 --unresolved-only
ch gerrit diff 6624568 --file "chrome/browser/ui/browser.cc"
ch gerrit bots 6624568 --failed-only
ch gerrit bot-errors 6624568 # Get detailed error messages with stack traces
ch gerrit bot-errors 6624568 --bot linux # Filter to specific bot
# Gerrit list (requires authentication)
ch auth login # One-time browser-based authentication
ch gerrit list --query "status:open owner:me"
ch pdfium list --query "status:open"
# Issue tracking
ch issues search "memory leak" --limit 20
ch issues get 422768753
# PDFium
ch pdfium status 130850
ch pdfium diff 130850
ch pdfium bots 130850
# Commit history & ownership
ch commits "password manager" --author "chrome-team" --since "2025-06-01"
ch owners "chrome/browser/ui/browser.cc"
🔧 CLI Tool Usage
The CLI provides comprehensive access to Chromium's codebase with intuitive commands.
Global Options
--format <json|table|plain>- Output format (default: plain)--debug- Enable debug logging--no-color- Disable colored output--ai- Show comprehensive AI usage guide
Key Commands
| Command | Description | Example |
|---|---|---|
search | Search code with Google syntax | ch search "LOG(INFO)" --limit 5 |
symbol | Find symbol definitions | ch symbol Browser::Create |
file | Get file content | ch file "base/logging.h" --start 100 --end 200 |
auth | Authentication management | ch auth login |
gerrit | Gerrit CL operations | ch gerrit bot-errors 6624568 |
pdfium | PDFium Gerrit operations | ch pdfium status 130850 |
issues | Search/view issues | ch issues search "memory leak" |
commits | Search commit history | ch commits "fix" --author "chrome-team" |
owners | Find OWNERS files | ch owners "chrome/browser/ui/" |
🔐 Authentication for Gerrit Lists
The gerrit list and pdfium list commands require authentication. We've made this super easy!
# One-time setup - interactive cookie setup (recommended)
ch auth manual
# Alternative: automated browser login (may be blocked by Google)
ch auth login
# Check if you're authenticated
ch auth status
# Now use gerrit commands without any cookies!
ch gerrit list
ch pdfium list --query "status:open owner:me"
# Clear saved authentication
ch auth logout
Manual Cookie Option: If you prefer manual setup:
ch auth help # Shows how to extract cookies manually
ch gerrit list --auth-cookie "SID=...; __Secure-1PSID=..."
Output Formats
# Human-readable (default)
ch search "WebContents"
# JSON for scripts/AI
ch search "WebContents" --format json | jq '.[] | .file'
# Table format
ch gerrit bots 6624568 --format table
🤖 MCP Server Usage
The MCP server enables AI assistants like Claude to search and analyze Chromium code.
Claude Desktop Configuration
Add to your claude_desktop_config.json:
{
"mcpServers": {
"chromium-codesearch": {
"command": "npx",
"args": ["chromium-codesearch-mcp"]
}
}
}
Or if installed globally:
{
"mcpServers": {
"chromium-codesearch": {
"command": "chromium-codesearch-mcp"
}
}
}
Available MCP Tools
Core Search & Navigation
search_chromium_code- Advanced code search with filtering optionsfind_chromium_symbol- Symbol definitions and usage examplesget_chromium_file- File content with line number ranges
Chromium Gerrit Integration
get_gerrit_cl_status- CL status, test results, submit requirementsget_gerrit_cl_comments- Review comments with code contextget_gerrit_cl_diff- Code changes and file modificationsget_gerrit_patchset_file- File content from specific patchsetsget_gerrit_cl_bot_errors- Detailed error messages with stack traces from failed try-botsget_ci_build_errors- Detailed error messages from specific CI buildslist_gerrit_cls- List Gerrit CLs with authentication (requires cookies)
PDFium Gerrit Integration
get_pdfium_gerrit_cl_status- PDFium CL status and test resultsget_pdfium_gerrit_cl_comments- PDFium review commentsget_pdfium_gerrit_cl_diff- PDFium code changesget_pdfium_gerrit_patchset_file- PDFium file content from patchsetslist_pdfium_gerrit_cls- List PDFium Gerrit CLs with authentication (requires cookies)
Issue Tracking & History
get_chromium_issue- Detailed issue information with browser automationsearch_chromium_issues- Search issues with full-text and paginationsearch_chromium_commits- Commit history search with date filteringfind_chromium_owners_file- Code ownership and reviewer discovery
Example MCP Prompts
Ask Claude to:
- "Search for LOG(INFO) usage in Chromium"
- "Find the definition of Browser::Create"
- "Check the status of Gerrit CL 6624568"
- "Search for memory leak issues"
- "Get the diff for PDFium CL 130850"
- "List my open Gerrit CLs" (requires providing authentication cookie)
📦 Installation
CLI Tool
# Option 1: Use without installation (recommended)
npx chromium-helper <command>
# Option 2: Install globally for 'ch' shortcut
npm install -g chromium-helper
MCP Server
# Option 1: Use with npx in Claude config (recommended)
# Add to claude_desktop_config.json as shown above
# Option 2: Install globally
npm install -g chromium-codesearch-mcp
From Source
git clone https://github.com/hjanuschka/chromium-helper.git
cd chromium-helper
# For CLI
cd chromium-helper-cli
npm install && npm run build
npm link # Optional: make globally available
# For MCP Server
cd ../
npm install && npm run build
🔧 Development
Prerequisites
- Node.js 18+
- TypeScript
- npm or yarn
Development Commands
# Install dependencies
npm install
# Build both packages
npm run build
# Watch mode (CLI)
cd chromium-helper-cli && npm run dev
# Test MCP server
npm test
# Run locally
node dist/index.js
Project Structure
chromium-helper/
├── chromium-helper-cli/ # CLI tool package
│ ├── src/ # TypeScript source
│ ├── dist/ # Compiled output
│ └── package.json
├── src/ # MCP server source
├── dist/ # MCP compiled output
├── package.json # MCP server package
└── README.md # This file
🤝 Contributing
We welcome contributions! Here's how you can help:
Reporting Issues
- Check existing issues first
- Include reproduction steps
- Mention your OS and Node version
Submitting PRs
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Code Style
- Use TypeScript
- Follow existing patterns
- Add tests for new features
- Update documentation
Ideas for Contributions
- Add more search filters
- Improve error messages
- Add new output formats
- Enhance PDFium support
- Add more MCP tools
📊 Technical Details
API Usage
- Chromium CodeSearch:
https://grimoireoss-pa.clients6.google.com - Gerrit API:
https://chromium-review.googlesource.com - Issue Tracker:
https://issues.chromium.org
Performance
- Caches API responses
- Parallel request support
- Efficient pagination
- Minimal dependencies
❓ FAQ
Q: Do I need to install anything to use this?
No! Just use npx chromium-helper <command> to run instantly.
Q: What's the difference between the CLI and MCP server?
- CLI: Direct terminal usage for developers
- MCP: Integration with AI assistants like Claude
Q: Can I search PDFium code too?
Yes! Full PDFium support for code search and Gerrit operations.
Q: Is this official Google software?
No, but it uses Google's official public APIs that power source.chromium.org.
Q: How do I see all available commands?
Run ch --ai for a comprehensive guide, or ch --help for a quick overview.
Q: Can I use this in scripts?
Yes! Use --format json for machine-readable output.
Q: What API key do I need?
None required! It uses the public API by default.
📄 License
MIT License - see LICENSE for details.
🌟 Acknowledgments
- Google Chromium team for the amazing CodeSearch API
- PDFium team for their great documentation
- MCP protocol team at Anthropic
- All contributors and users
Made with ❤️ for the Chromium community