Quickstart

Five minutes, no Google setup

The demo dataset populates every page, so you can see what the tool does before you connect anything. Node 20+, Python 3.10+, curl and openssl are all it needs.

# see it working
npm install -g n-seo
n-seo init my-sites && cd my-sites
n-seo demo          # synthetic data for example.com
n-seo start         # → http://localhost:4600

# connect your sites
# edit n-seo.config.json, then:
n-seo doctor        # checks key + access
n-seo daily         # the morning run, by hand

Try it on demo data

Every page, every card, every chart — populated. Poke around the queue, open a spec, toggle a module in Settings.

Give it read access

One Google service account, added as a user on Search Console and GA4. The key is signed locally with openssl — no gcloud, no pip installs. Step by step →

Schedule the morning run

launchd on macOS, cron or systemd on Linux. It waits for the network, retries once, logs every step, and tells you when something failed. Scheduling →

Ship what it tells you to

In your own repo, your own way. The next morning's data says whether it worked, and the card moves to watching instead of disappearing.

How it works

What an agency does every month, as a loop that runs every morning

Four planes. The first and second are automated; the third is you (or your AI agent); the fourth is what makes the second one honest.

01 · awareness

Pull everything

Search Console (16 months and the trailing 90 days), GA4 sessions, sources and landing pages, per-page time series, URL Inspection verdicts for every sitemap URL, and a no-auth probe of each site: robots, sitemap, llms.txt, soft 404s, blocked AI crawlers, JS-only shells.

02 · analysis

Rank the moves

Rules over the 90-day window turn snapshots into actions: metadata that misses the ranking language, pages that rank well but rarely get clicked, queries sitting at position 5–15, landing pages that don't deliver what the click promised, traffic drops. Impact per unit of effort orders the queue.

03 · action

You ship

Each card opens to the evidence, the move and a build spec. You change the title, add the section, fix the 404 — in your repo, on a branch, your way. Accept machine proposals into your queue with one click; nothing self-modifies it.

04 · measurement

The data decides

Shipped work becomes watching, never deleted. Watched pages are reported in the daily log; the scan judges whether a change succeeded, failed or needs more time. That feedback is how you hone your own principles.

What you get

A dashboard that leads with what to do next

Server-rendered, no bundler, light and dark. Compact, searchable, and split cleanly into active work and shipped work being measured.

The action queue

Proposed → active → watching. Each card carries its evidence, the move, a spec and a success criterion. Filter by title, site, tag or kind.

Trends

One window drives everything: clicks per day, sessions per day, and which pages were hit on which days. Hover a day to highlight it across every row.

Indexing

Search Console's verdict on every URL in your sitemap. Tells "nobody searches for this" apart from "Google has never fetched this" — they look identical in performance data.

Settings

One config file, edited from the page. Toggle modules, set the digest topics, describe your expertise for briefings, list the pages to watch.

Also: per-site pages (striking distance, CTR gaps, landing pages, AI-referral sources), Insights, Probes, Logs, Content (drafts, campaigns, participation briefings).

The rules

The principles an agency charges for, written down — and yours to edit

n-seo ships with an opinionated operating model. Each rule is a few lines you can read, argue with and change. The queue shows you why it thinks so, every time.

28-day title freeze

After you rewrite a page's title or description, leave it alone for four weeks. Churn reads as manipulation and resets Google's evaluation. Measure, then move.

≈8 metadata changes a week

Twenty-five title rewrites in one afternoon is a pattern. Stagger the batches across your sites.

90 days decide; 16 months remember

Decisions ride the trailing 90 days so a fix you shipped last week stops being accused. The long window is for totals and history.

Impact orders, never forecasts

The clicks-per-month number on a card exists to rank the queue. It is not a promise, and the tool never reports it as one.

Shipped → watching

Done work stays on the board with a dated note until the data has spoken. Deleting it is how you forget what you learned.

Briefings, never comments

Community participation is human. The tool finds the thread and briefs you on the gist, the debate and your genuine angle. It will not write the words.

Why "hone your own principles"? Because the rules above are a starting point, not a doctrine. Every rule in the action engine is a plain TypeScript function with a threshold you can see. When a card is wrong, you learn why; when it is right, you learn what moved. After a few months the queue reflects what works for your sites, and you can explain every line of it.

Bring your own agent

Your AI agent gets the same view you do

A read-only MCP server exposes the queue, per-site metrics, the metadata audit, index coverage, trends and ops health. Claude Code picks it up from the repo's .mcp.json with no setup; Claude Desktop and other clients use stdio or an authenticated HTTP endpoint.

Read-only is the point: an agent can reason over your search data all day and still cannot bypass the freeze, the batching, or you.

What should I do first this week, and why?

Which pages on example.com rank well but rarely get clicked?

Did last week's title change on /pricing move anything yet?

Which sitemap URLs has Google never crawled?

Draft the spec for the top striking-distance page as a PR description.

15 tools, 3 doc resources, every one annotated read-only. MCP docs →

Modules

Opt in, and honest about what each one touches

Everything beyond the core pulls is off until you turn it on. Nothing here posts, sends or publishes on your behalf.

Module	What it does	Needs	Default
Index coverage sweep	URL Inspection verdict for every sitemap URL	Search Console access	on
Metadata audit	Fetches each ranking page's live title and description, judges them against the queries it ranks for	—	on
Opportunity scan	84-day trend refresh; rising queries no queue item covers become candidates	—	on
LLM inference	Turns candidates into proposals and watched items into verdicts; writes digest briefings	any CLI that reads a prompt on stdin — `claude -p` by default	off
Hacker News digest	Finds fresh threads in your expertise areas and briefs you on each	your HN username	off
Reddit digest	Same for subreddits	a free Reddit "script" app's credentials	off
IndexNow	Key generation and pings to Bing / Copilot / Yandex on publish	—	off
Static export	Snapshot the dashboard to HTML for a mirror behind your own auth	—	off
Git auto-commit	Commit the daily log after each run	a git remote, optionally	off
Notifications	Desktop notification when a step fails	macOS	off

Cost

Free means free

No SaaS, no account, no seat price. MIT licensed. Clone it, run it, fork it, ship it inside your company.

Google's APIs are free within quota. Search Console and GA4 reporting cost nothing at this scale; the index sweep is capped well under the daily limit.

Bring the LLM you already have — or none. The core loop needs no model at all. The inference module runs whatever command you give it, or calls an endpoint you choose, with your prompt.

We run our own sites on it. n-seo is the generalized version of the control plane En Dash uses for its own portfolio every morning. When it breaks, we notice first.

An SEO, self-hosted.

Yours, on your hardware

Evidence first

It briefs; you act