Competitor Researcher

[Live] · agent__competitor-researcher · Claude Sonnet 4.6

Researches 3–4 direct competitors to map their positioning, content strategy, and keyword gaps — giving the Context File Writer a clear picture of the competitive landscape.

Overview

Triggers

Can be skipped per-tenant: if contextConfig.enableCompetitorResearch = false, the setup chain jumps straight to Context File Writer with a placeholder.

Input

interface SetupJobData {
  tenantId: string;
  tenantName: string;
  country: string;
  plan: string;
  clientResearchOutput: string;   // full Markdown from client-researcher
  knownCompetitors?: Array<{ name: string; domain?: string | null }>; // existing Competitor rows
  revisionNotes?: string;         // present on revision runs
  wakeReason: WakeReason;
}

knownCompetitors is loaded from the Competitor table at chain-time and passed as seed data so the agent doesn’t ignore previously tracked companies.

Output

The agent writes structured Markdown (not JSON). Output is passed as competitorResearchOutput directly to the Context File Writer.

Structure:

• One ## subsection per competitor (name, website, services, audience, channels, strengths/weaknesses)
• Keyword gap table at the end
• Competitive landscape summary (intensity: low / medium / high)

How It Works

1. Receive job — BullMQ dequeues the job with clientResearchOutput and optional knownCompetitors as seed.

2. Skills dir created — createSkillsDir() writes search_knowledge.js + CLAUDE.md + any DB-mapped skill files (e.g. competitor_analysis_framework.md) into a temp directory, which is passed to the Claude Code CLI via --add-dir.

3. Agentic loop — Claude Code CLI runs with --dangerously-skip-permissions and a cap of 20 turns. The agent:

   • Does one WebSearch per competitor to find their homepage URL
   • Does one WebFetch per competitor (homepage only)
   • Synthesises findings into the Markdown output
   • Does not fetch traffic data, SimilarWeb, Alexa, or Ahrefs

4. Chain forward — On success, the worker enqueues a context-file-writer job with both clientResearchOutput and competitorResearchOutput.

5. DB log — A ClientContextLog record is written with action: "research_completed".

System Prompt (live in AgentConfig table)

You are the Competitor Researcher agent for Leadmetrics, a digital marketing agency AI platform.
Your task is to identify and analyse the top competitors for a client based on their niche, location, and services.

RESEARCH REQUIREMENTS:
1. Identify 3–4 direct competitors (same product/service category, overlapping geography). Stop at 4 — do not expand further.
2. For each competitor, do ONE web search to find their homepage, then fetch ONLY their homepage. Document:
   - Company name, website URL
   - Core products or services
   - Apparent target audience
   - Key marketing channels used (SEO, social, ads, email)
   - Notable strengths and weaknesses
3. Perform keyword gap analysis: which high-value search terms do competitors likely rank for that the client does not? Base this on your homepage research — do NOT do additional searches for this.
4. Summarise overall competitive intensity (low / medium / high) with justification.

DO NOT:
- Look up traffic data, Alexa rank, SimilarWeb, or Ahrefs metrics
- Fetch more than 1 page per competitor
- Do more than 1 web search per competitor
- Research indirect or content competitors

OUTPUT FORMAT:
Write structured Markdown. Use a subsection per competitor. End with a competitive landscape summary and keyword gap table.

Output ONLY the competitor research notes. No preamble, no explanation.

The system prompt is stored in AgentConfig.systemPrompt (role competitor-researcher) and can be updated via Manage → Agents without a redeploy. The seed in packages/db/src/seed.ts mirrors this value.

Skills Injected

Tools Used (actual)

Total tool calls target: 8–12. Hard cap via --max-turns 20.

No SEMrush, SimilarWeb, or Alexa lookups — these were removed in April 2026 after they caused runaway tool call chains (31 calls, $1.30+/run).

Cost Profile

Before April 2026 tuning: 22+ WebSearch calls + 7+ WebFetch calls (traffic indicator lookups, SimilarWeb fetches that returned nothing useful) resulted in 31 tool calls, ~6.5 min, ~$1.30/run. Root causes: “traffic indicators” instruction in system prompt + no turn cap + 4–6 competitor target.

Adapter Config

Set in setup.worker.ts for the competitor-researcher role:

{
  cwd,
  model,                        // from AgentConfig.model
  dangerouslySkipPermissions: true,
  timeoutSec: 900,
  maxTurnsPerRun: 20,           // hard cap added April 2026
}

Error Handling

Tenant Settings Used