Keyword Agent

The first keyword research skill for Claude Code and OpenClaw that scores by estimated monthly revenue, not search volume.

Type a service and city. Get back a scored opportunity table with EMR, difficulty, trend, intent, and AI visibility. Runs as a /keyword-agent skill in Claude Code or directly from the CLI.

  KEYWORD                                INTENT                   VOL    CPC  CONV%         EMR  DIFFICULTY             TREND  AI VIS   SCORE
  ────────────────────────────────────── ──────────────────── ─────── ──────  ─────  ──────────  ──────────────────  ────────  ──────  ───────
  hvac repair austin tx                  Find Local Service       720 $18.40  1.50%  $ 2,949.12  100% easier (0)       ↑ 12%    Low      91.20
  emergency hvac repair austin           Find Local Service       390 $22.10  1.50%  $ 1,927.98  100% easier (0)       ↑ 28%    Low      88.43
  how much does hvac repair cost austin  Informational            210 $ 8.30  0.50%  $   392.57   88% easier (6)       ↑ 14%   ⚡ High   83.11
  hvac companies austin                  Find Local Service     1,600 $ 9.80  1.50%  $ 3,528.00   76% easier (12)      ↓  8%    Low      82.17
  emergency hvac repair in cedar park    Find Local Service       AI~ $ 3.50  1.50%  $    73.50   90% easier (5)        → 0%   ~ Med    68.11
  24 hour hvac repair in round rock      Find Local Service       AI~ $ 3.50  1.50%  $    63.00   90% easier (5)        → 0%   ~ Med    67.11

What it does:

• Fetches real search volume, CPC, and competition data via DataForSEO
• Scores every keyword by Estimated Monthly Revenue, ranking difficulty, and trend
• Expands into AI-generated hyper-local neighborhood queries that standard tools miss
• Flags AI Visibility — which keywords are likely to surface in ChatGPT, Perplexity, and Google AI Overviews
• Imports Google Keyword Planner CSV exports and scores them with the same model
• Zero dependencies — pure Python 3.8+, runs entirely on your machine

Setup

1. Get DataForSEO credentials

Sign up at dataforseo.com — pay-as-you-go, roughly $0.0025 per keyword lookup.

export DATAFORSEO_LOGIN=you@example.com
export DATAFORSEO_PASSWORD=your_api_password

Add to ~/.zshrc or ~/.bashrc to persist across sessions.

2. Clone

git clone https://github.com/gbessoni/google-keyword-planner
cd google-keyword-planner

No pip install. No requirements.txt. Just Python 3.8+.

3. Run the web UI

python3 scripts/server.py

Opens at http://localhost:8765. Enter a keyword, or drag in a Google Keyword Planner CSV export.

4. Run as a Claude Code skill

Open Claude Code in this directory and type:

/keyword-agent hvac repair in austin
/keyword-agent airport parking jfk --limit 100
/keyword-agent plumbers in denver

5. Run from the CLI

python3 scripts/keyword-agent.py --seed "hvac repair in austin"
python3 scripts/keyword-agent.py --seed "airport parking jfk" --limit 100
python3 scripts/keyword-agent.py --seed "plumbers in denver" --json

How scoring works

EMR (Estimated Monthly Revenue) is built on organic position-based click-through rates drawn from large-scale search session analysis. The model assumes a top-3 ranking as the target outcome:

EMR = Volume × 30% organic CTR × CPC × Competition Multiplier × YOY Factor

Competition Multiplier:  Low = 2.0×   Medium = 1.5×   High = 1.0×
YOY Factor:              positive trend → small bonus   negative trend → dampened penalty

Composite Score (0–100):

Score = EMR (log-normalized)       × 45%
      + Ease (100 − difficulty)    × 35%
      + Trend (YOY, dampened)      × 20%

Intent-based conversion rates:

Intent	Rate	Triggered by
Navigational	4.0%	Brand name searches
Transactional	2.5%	"book", "hire", "reserve", "buy"
Commercial Local	1.5%	"near me", city name, service + location
Commercial General	1.2%	"best", "top", "compare", "vs"
Informational	0.5%	"how", "what", "why", "cost of"

AI Visibility rating:

Every keyword is scored for likelihood of appearing in AI Overviews, ChatGPT, and Perplexity results:

• ⚡ High — question-based, informational, or long-tail conversational queries (5+ words) that AI engines actively cite
• ~ Med — commercial comparison queries, AI-generated neighborhood keywords
• Low — transactional "buy X" and navigational queries (low AI Overview presence)

AI neighborhood expansion

For local service keywords, the tool generates hyper-local queries for surrounding communities — the kind of conversational queries that voice search and AI answers actually respond to, but that standard volume tools return zero for:

• "who is a plumber in Round Rock who is open this weekend"
• "emergency hvac repair in Cedar Park"
• "24 hour plumbing in Pflugerville"

These are marked AI~ in the volume column. EMR is estimated conservatively from template-based demand signals.

Neighborhood expansion is pre-configured for Nanaimo, Vancouver, Toronto, Denver, Dallas, Los Angeles, Chicago, Miami, JFK/New York, and LAX/Los Angeles. Add your own city in CITY_NEIGHBORHOODS inside scripts/keyword-agent.py.

Google Keyword Planner import

Already have keyword data from Google Keyword Planner? Drag your CSV export into the web UI — no DataForSEO credits needed. The tool reads volume, CPC, competition, and monthly trend data from the export and applies the full EMR scoring model on top.

Files

scripts/
  keyword-agent.py      — Main tool: seed keyword → scored table
  server.py             — Local web server for the UI
  wide-net-expand.py    — Batch expansion from a keyword CSV
data/
  seed-keywords.tsv     — Sample keyword export to test with
web/
  index.html            — Single-file web UI
.claude/
  commands/
    keyword-agent.md    — Claude Code /keyword-agent skill definition

Part of the SEO AGI toolkit

Feed these keywords into SEO AGI to generate the ranking page. github.com/gbessoni/seo-agi

License

MIT