competitor-research

Competitor Research Pipeline

Comprehensive competitor research pipeline for Claude Code. Consolidates scattered NotebookLM sources, enriches with live web research via Google AI Mode MCP, cross-references for accuracy, and produces structured 10-section market briefs with automated quality review.

Output is dual-purpose: briefs that serve investor pitch materials (market sizing, funding, threat assessment) AND product strategy decisions (feature gaps, user sentiment, positioning).

Installation

Remove any stale marketplace entry, add fresh, install, and reload:

claude plugin marketplace remove competitor-research
claude plugin marketplace add 3D-Stories/competitor-research
claude plugin install competitor-research@competitor-research

Then reload plugins in your session:

/reload-plugins

After installing, run /competitor-research setup to configure dependencies.

Setup (/competitor-research setup)

Run once to configure all dependencies. Can be re-run to reconfigure. The setup wizard walks through 8 steps and saves configuration to ~/.config/competitor-research/config.json.

If you skip setup and run /competitor-research <name> directly, the skill auto-detects the missing config and runs setup automatically before proceeding.

Step 0: Node.js & npm

Checks if Node.js v20+ and npm are installed (required for MCP servers and npx commands). If missing or too old: installs latest LTS via NodeSource (curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -)

Step 1: Environment Detection

Checks for a graphical display ($DISPLAY + xdpyinfo). If headless, flags that VNC will be needed for browser auth flows (OAuth, CAPTCHA).

Step 2: Virtual Display (headless only)

Checks if /vnc-service:setup is available. If not, installs the vnc-service plugin:

claude plugin marketplace add 3D-Stories/vnc-service
claude plugin install vnc-service@vnc-service

User must run /reload-plugins to activate it. After reload, invokes /vnc-service:setup to install Xvfb + x11vnc, then /vnc-service:run to start the display and get connection info. Waits for user to confirm VNC connection before proceeding.

Step 3: NotebookLM CLI

Installs notebooklm-py via pipx (not pip -- modern Ubuntu/Debian use PEP 668 which blocks direct pip install into system Python):

pipx install notebooklm-py
pipx inject notebooklm-py playwright
$(pipx environment --value PIPX_LOCAL_VENVS)/notebooklm-py/bin/playwright install chromium
# Install system dependencies for Chromium (libatk, libcairo, libpango, etc.)
# Without this, Chromium crashes with "cannot open shared object file" errors
sudo $(pipx environment --value PIPX_LOCAL_VENVS)/notebooklm-py/bin/playwright install-deps chromium

If sudo is unavailable for install-deps, the user must install the packages manually. Run without sudo to see the list of required packages.

Then installs the Claude Code skill and reloads:

notebooklm skill install

/reload-plugins

Handles OAuth login (via VNC with DISPLAY=:99 if headless, direct browser if graphical). The notebooklm login command waits for ENTER after OAuth completes, but Claude Code's Bash tool sends EOF immediately which aborts login. Uses a two-step pattern instead:

Step A: Launch login in background so the user can interact with the browser:

DISPLAY=:99 notebooklm login &
LOGIN_PID=$!

User completes OAuth in the browser (via VNC for headless).

Step B: After user confirms OAuth is complete, kill the background process and re-run with immediate ENTER to save auth from the persistent browser profile:

kill $LOGIN_PID 2>/dev/null
echo "" | DISPLAY=:99 notebooklm login

The persistent browser profile (~/.notebooklm/browser_profile) retains the Google session, so the second run opens an already-authenticated browser and immediately saves.

If login fails (e.g., missing dependencies, Chromium crash): kill the background process before retrying to avoid orphaned browser instances:

kill $LOGIN_PID 2>/dev/null
# Fix the issue, then retry from Step A

Step 4: Google AI Mode MCP

Google AI Mode is an MCP server (not a skill). Installed via:

claude mcp add google-ai-search npx google-ai-mode-mcp@latest

This registers the mcp__google-ai-search__search_ai tool in the session.

HARD STOP after install. MCP servers only load at session start. The user must restart the session and re-run /competitor-research setup. Setup detects that Steps 1-3 are already complete and resumes from Step 4 verification.

After restart, the skill tests with a sample search. If the test fails with "Chromium distribution 'chrome' is not found", Chrome/patchright must be installed:

sudo npx patchright install chrome