GSC Audit

What It Does

Google Search Console is the tool Google gives you to see how your websites are doing in search results. This capability checks all of your websites at once, flags which ones are losing clicks, which pages Google is showing but nobody is clicking on, and which topics people are searching for that you do not have a page about yet. For every problem it finds, it suggests a specific fix — like a better page title — and can push the fix live for you if the website is one you own.

When To Use

Weekly or biweekly. Catches drops before they snowball.
After a deploy that could affect SEO. Title changes, sitemap changes, URL structure changes.
When a specific site feels off. Pass the site domain as an argument to run a deep single-site audit.
When you say: “GSC audit”, “search console health”, “check my sites”, “SEO health”, “GSC report”.

How To Invoke

Say any of the trigger phrases above, or run the slash command:

/gsc-audit

For a deep single-site audit:

/gsc-audit themarketingshow.com

Prerequisites

Requirement	Where
Google Search Console OAuth token	`~/apps/google-search-console/token.json` (scopes: `webmasters`, `indexing`)
`gsc-benchmarks.db` SQLite file	VPS only at `/root/apps/google-search-console/gsc-benchmarks.db` (git-ignored, the single source of truth for historical trends)
SSH access to the VPS	`ssh vps` (commands are prefixed with SSH so they hit the VPS DB)
Daily cron job on the VPS	Runs at 8 AM MT — saves a snapshot to the benchmarks DB and emails the report

Where It Lives

Skill definition: ~/.claude/commands/gsc-audit.md
Scripts: ~/apps/google-search-console/ (on every machine, but the DB only lives on the VPS)
- gsc-health-report.py — gathers performance + sitemap data, saves a benchmark snapshot
- gsc.py — per-site commands: performance, queries, pages, inspect, coverage, submit-sitemap, index, list-sites
- gsc-benchmarks.py — compare, history, summary, json for historical trends
- gsc-deep-audit.py — single-site deep dive (sitemap quality, meta tags, robots.txt, 404s, crawl budget)

Example Session

James: GSC audit

Claude: Running gsc-audit. Pulling the latest health report from the VPS.
        [runs: ssh vps "python3 /root/apps/google-search-console/gsc-health-report.py --json"]

        Portfolio overview (ranked by health):
        - mytechsupport.com — clicks -42%, 3 CTR opportunities, 1 sitemap error
        - themarketingshow.com — clicks +8%, 12 CTR opportunities, healthy
        - allthingshandy.com — healthy, trending up
        ... (rest of sites) ...

        Top CTR opportunity across all sites:
        mytechsupport.com/bounties — 2,340 impressions/wk, 0.8% CTR, position 6.2
        Current title: "Bounties — MyTechSupport.com"
        Proposed title: "Get Paid to Fix Tech Problems — MTS Bounty Board"
        Queries driving impressions: "tech support freelance", "fix computer for money", ...

        Apply the fix?
James: yes
Claude: [edits title, commits, pushes, verifies deploy]
        Done. Build 47 is live at https://mytechsupport.com/bounties/

Thresholds And Tuning

CTR opportunity: ≥50 impressions over 7 days, CTR < 2%, position ≤ 20
Content gap: ≥30 impressions, ≤2 clicks, position ≥ 10, no existing page matching 60%+ of query words
Issue flags: clicks −30%, impressions −40%, index rate <50%, sitemap errors >0

Data has a ~3-day lag. Indexing API is capped at 200 requests per day — don’t mass-submit.

Known Gaps / TODOs

Non-VPS runs hit a stale DB. If you accidentally run python3 gsc.py ... on the Studio or MacBook Pro, you lose all historical comparisons. The skill file prefixes every command with ssh vps to prevent this, but it is an easy-to-forget footgun.
No dashboard. All reports are either terminal output or emails. A visual dashboard would make trends more obvious.
No alerting. The daily cron emails a full report, but there is no “wake me up only if something broke” alert path.