dispatchseo
Turn your AI agent into your SEO manager - works today with Claude Code, Codex, and Cursor. The open-source alternative to SEObot and Outrank
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/NeoZi12/dispatchseo with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/NeoZi12/dispatchseo'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/neozi12--dispatchseo)HTML
<a href="/listings/neozi12--dispatchseo"><img src="/api/listings/neozi12--dispatchseo/badge.svg" alt="findsafeskills safety rating" /></a>Install
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 39 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- {
- "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
- "name": "dispatchseo",
- "owner": {
- "name": "NeoZi12",
- "url": "https://github.com/NeoZi12"
- },
- "metadata": {
- "description": "DispatchSEO - self-hostable AGPL SEO manager backend for coding agents"
- },
- "plugins": [
- {
- "name": "dispatchseo",
- "source": "./claude-plugin",
- "description": "Connect Claude Code to your DispatchSEO project - SEO keyword research, content queue, and SERP rank tracking over MCP",
- "version": "1.0.0",
- "author": {
- "name": "NeoZi12",
- "email": "neozi2014@gmail.com",
- "url": "https://github.com/NeoZi12"
- },
- "homepage": "https://dispatchseo.com",
- "repository": "https://github.com/NeoZi12/dispatchseo",
- "license": "AGPL-3.0",
- "keywords": [
- "seo",
- "search-console",
- "keyword-research",
- "content-pipeline",
- "rank-tracking",
- "backlinks",
- "self-hosted",
- "claude-code"
- ],
- "category": "productivity",
- "tags": ["seo", "content", "search-console", "marketing", "automation"]
- }
- ]
- }
README.md · README · 282 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <p align="center">
- <a href="https://dispatchseo.com">
- <img src="src/app/icon.png" width="116" alt="DispatchSEO logo">
- </a>
- </p>
- <h1 align="center">DispatchSEO</h1>
- <p align="center">
- <a href="LICENSE"><img alt="License: AGPL-3.0" src="https://img.shields.io/badge/license-AGPL--3.0-7C5CFC?labelColor=1F2328&style=flat-square"></a>
- <a href="docs/AGENTS.md"><img alt="Built for Claude Code, Codex, and Cursor" src="https://img.shields.io/badge/built%20for-Claude%20Code%20%2B%20Codex%20%2B%20Cursor-D97757?labelColor=1F2328&style=flat-square"></a>
- <a href="https://dispatchseo.com/docs#choose-your-install"><img alt="Self-host in one command" src="https://img.shields.io/badge/self--host-one%20command-2496ED?logo=docker&logoColor=white&labelColor=1F2328&style=flat-square"></a>
- <a href="https://dispatchseo.com/discord"><img alt="Join the Discord" src="https://img.shields.io/badge/Discord-join%20the%20server-5865F2?logo=discord&logoColor=white&labelColor=1F2328&style=flat-square"></a>
- </p>
- <div align="center">
- <strong>
- <h2>Free SEO automation: researched articles, published to your site on autopilot</h2><br />
- <a href="https://dispatchseo.com">DispatchSEO</a>: an open-source alternative to SEObot, Outrank and RightBlogger.<br /><br />
- </strong>
- DispatchSEO researches keywords with real search demand, writes fact-checked articles and publishes them for you,<br />as pull requests to your GitHub repo, then shows the Google visitors they bring.<br />
- It works with any website that lives in a GitHub repo, including <a href="https://dispatchseo.com/lovable">sites built with Lovable</a>.<br />
- Two articles per month are free on <a href="https://dispatchseo.com">dispatchseo.com</a>, no card. Paid plans publish 5, 15 or 30 articles per month on up to 5 websites.<br /><br />
- Self-hosting it instead? The whole thing runs in your own accounts, driven by <b>Claude Code</b>, <b>Codex</b>, or <b>Cursor</b> over MCP, including the unattended overnight builder.
- </div>
- <div align="center">
- <br />
- <img alt="Claude Code" src="docs/brand/icons/claude.svg" width="32">
-
- <img alt="Codex" src="docs/brand/icons/openai.svg" width="32">
-
- <img alt="Cursor" src="docs/brand/icons/cursor.svg" width="32">
-
- <img alt="MCP" src="docs/brand/icons/mcp.svg" width="32">
-
- <img alt="GitHub" src="docs/brand/icons/github.svg" width="32">
-
- <img alt="Google Search Console" src="docs/brand/icons/search-console.svg" width="32">
-
- <img alt="Google" src="docs/brand/icons/google.svg" width="32">
-
- <img alt="Docker" src="docs/brand/icons/docker.svg" width="32">
- </div>
- <p align="center">
- <br />
- <a href="https://dispatchseo.com/docs#choose-your-install"><img src="docs/buttons/install.svg" alt="Install now" height="46"></a>
-
- <a href="https://dispatchseo.com/docs"><img src="docs/buttons/docs.svg" alt="Read the docs" height="46"></a>
- </p>
- <p align="center">
- <a href="https://dispatchseo.com">Website</a>
- ·
- <a href="https://dispatchseo.com/discord">Discord</a>
- ·
- <a href="https://github.com/NeoZi12/dispatchseo/discussions">Discussions</a>
- ·
- <a href="https://dispatchseo.com">Hosted version</a>
- </p>
- <p align="center"><i>Self-hosted has zero feature limitations. Everything the paid<br />cloud does, this repo does today, in your own accounts, at $0.</i></p>
- <br />
- ## ⚡ How it works
- 1. **Your AI researches.** The Claude app at claude.ai, or a coding agent
- (Claude Code, Codex, Cursor), connects to DispatchSEO over MCP,
- reads the served playbook, and mines keywords from your Search Console
- data, Google Autocomplete, and what it already knows about your product.
- Ideas land in a queue with the reasoning attached.
- 2. **You approve, or don't.** Each idea is a card on the dashboard: the
- keyword, why it's winnable, the angle. Approve, reject, or reorder.
- Prefer full autopilot? Flip on auto mode and skip the queue entirely.
- 3. **The pipeline builds.** Every morning a scheduled job picks the oldest
- approved idea and builds it into a real pull request against your site's
- repo: a guide or a small free tool, checked against the live SERP and run
- through a sameness reviewer so page twelve doesn't read like page three.
- 4. **It tracks what happened.** Daily rank checks, hourly Search Console
- snapshots, index verification, and a journey view that tells you which
- SEO stage you're actually in. When a scheduled job breaks, you get a red
- banner and an email instead of silence.
- The backend is deliberately boring: state, scheduling, and an approval gate.
- The thinking happens in your agent, where your product knowledge already
- lives.
- <table>
- <tr>
- <td colspan="2"><img src="docs/screenshots/home.png" alt="The dashboard Home: the agent's daily briefing in plain language, the journey stage, publishing pace, and live Search Console stats for a connected site"></td>
- </tr>
- <tr>
- <td><img src="docs/screenshots/queue.png" alt="The queue: keyword ideas with volume and difficulty, each waiting for approval or set to auto"></td>
- <td><img src="docs/screenshots/guide-pr.png" alt="A pull request the pipeline built: target keyword, SERP gate verdict, archetype, and information-gain asset, all named in the description"></td>
- </tr>
- <tr>
- <td><img src="docs/screenshots/search-traffic.png" alt="Search traffic: clicks and impressions from Google Search Console, snapshotted hourly"></td>
- <td><img src="docs/screenshots/rankings.png" alt="Keyword rankings: daily position checks with 30-day trend sparklines"></td>
- </tr>
- </table>
- ## 🤖 Which coding agent
- DispatchSEO talks to your agent over MCP, so "which agent" is a real question
- with a real answer — including the parts that aren't finished yet.
- | Agent | Connect + every tool | Unattended overnight builder |
- |---|---|---|
- | **Claude Code** | ✅ | ✅ |
- | **Codex** | ✅ | ✅ |
- | **Cursor** | ✅ one-paste connect, all 61 tools | ✅ via its API key (any plan mints one) |
- | Gemini CLI · Copilot · any MCP client | ✅ | ❌ |
- Connecting is one paste and gets you the whole tool set: research, the queue,
- approvals, backlinks, reports, and building a guide when you ask for one. The
- overnight builder is the separate thing — scheduled jobs that run an agent with
- nobody watching — and all three do that. Every workflow carries every agent
- and asks the dashboard which to run, so switching agent takes effect on the
- next scheduled run with no repo change.
- The honest difference is who pays: Claude Code runs on a subscription you
- already have, Cursor runs on your Cursor plan's API key, and Codex is
- metered by OpenAI per run.
- You can also skip coding agents entirely. Add DispatchSEO to the ordinary
- Claude app at claude.ai as a custom connector and your Claude does the research
- and the writing on the subscription you already have, then hands the article
- back for the backend to check, finish and publish. It won't build interactive
- tools or run the overnight builder, and claude.ai has to be able to reach your
- install, so that path wants a public URL rather than a laptop. ChatGPT can't
- connect yet.
- [docs/AGENTS.md](docs/AGENTS.md) has the details, the support tiers, and how to
- add an agent.
- ## ✅ What you need before you start
- - **Somewhere to publish.** Either WordPress you host yourself, connected once
- from Settings with an application password and posted to directly, or your
- site's source in a GitHub repo, where content arrives as pull requests. Wix,
- Squarespace, Shopify, Webflow and Ghost have neither door and won't work.
- - **An AI to drive it.** Your AI is the engine, and it can be the ordinary
- Claude app at claude.ai or a coding agent. Claude Code runs on the Claude
- subscription you already pay for; Codex and Cursor do everything Claude Code
- does here, including the overnight builder. Codex is metered by OpenAI per
- run, and Cursor builds draw on your Cursor plan's included usage. See the table above.
- - **A machine with Docker** (~1 GB RAM). A laptop works for a test drive, but
- a machine that stays on is much better for daily use - a $5 VPS, a Raspberry
- Pi, a desktop that never sleeps. Schedules only run while the machine is awake.
- - **Google Search Console access** to your site.
- That's the whole list. No API keys to buy, and no account on our side.
- ## 📖 Documentation
- Everything is at **[dispatchseo.com/docs](https://dispatchseo.com/docs)** - every
- page, every setting, every tool.
- | | |
- | --- | --- |
- | **New here** | [What DispatchSEO is](https://dispatchseo.com/docs/introduction) · [How it works](https://dispatchseo.com/docs/how-it-works) · [Cloud or self-hosted](https://dispatchseo.com/docs/choosing-how-to-run-it) |
- | **Install** | [Quickstart](https://dispatchseo.com/docs#choose-your-install) - your own computer, a VPS, or from source |
- | **Set up** | [Install Claude Code](https://dispatchseo.com/docs/install-claude-code) · [Install Codex](https://dispatchseo.com/docs/install-codex) · [Install Cursor](https://dispatchseo.com/docs/install-cursor) · [The setup wizard](https://dispatchseo.com/docs/setup-wizard) · [Search Console](https://dispatchseo.com/docs/search-console) · [Keyword data](https://dispatchseo.com/docs/keyword-data) · [Publishing](https://dispatchseo.com/docs/publishing) · [Connect your site](https://dispatchseo.com/docs/connect-your-site) |
- | **Use it** | [Day to day](https://dispatchseo.com/docs/day-to-day) · [The dashboard](https://dispatchseo.com/docs/dashboard) · [Automations](https://dispatchseo.com/docs/automations) · [Agent commands](https://dispatchseo.com/docs/agent-commands) |
- | **Reference** | [Concepts](https://dispatchseo.com/docs/concepts) · [MCP tools](https://dispatchseo.com/docs/mcp-tools) · [Environment variables](https://dispatchseo.com/docs/environment-variables) · [Schedules](https://dispatchseo.com/docs/schedules) · [Architecture](https://dispatchseo.com/docs/architecture) |
- | **Help** | [Troubleshooting](https://dispatchseo.com/docs/troubleshooting) · [Common questions](https://dispatchseo.com/docs/faq) · [Security](https://dispatchseo.com/docs/security) · [Upgrading](https://dispatchseo.com/docs/upgrading) |
- **Pointing an agent at this?** Add `.md` to any docs URL for clean markdown, or
- fetch the entire documentation set in one request:
- **[llms-full.txt](https://dispatchseo.com/llms-full.txt)**. There's an index at
- [llms.txt](https://dispatchseo.com/llms.txt) and a [SKILL.md](SKILL.md) that
- walks an agent through connecting a site.
- **Stuck during setup?** The
- [troubleshooting page](https://dispatchseo.com/docs/troubleshooting) covers the
- errors people actually hit. If yours isn't there, ask in the
- [Discord](https://dispatchseo.com/discord) or in
- [Discussions](https://github.com/NeoZi12/dispatchseo/discussions) - questions get
- answered and usually turn into a docs fix.
- ## 🗓️ Using it day to day
- Once the wizard is done, the loop is small on purpose:
- | When | You do | It does |
- | --- | --- | --- |
- | Once a week, 5 minutes | Open the dashboard, work through the queue - approve, reject, reorder | Refills the queue with researched ideas and the reasoning behind each one |
- | Every morning | Nothing | Builds the oldest approved idea into a pull request on your repo |
- | When a PR lands | Review and merge (or let auto-merge do it) | Logs the page, requests indexing, starts tracking its keyword |
- | Whenever you want | Ask your agent: *"research keywords for me"*, *"what should I write next?"*, *"how are we ranking?"* | Answers from live data over MCP - same state the dashboard shows |
- The dashboard's Home page always names the next action, so you don't have to work
- out what to do when you open it.
- ## 🧰 What's in the box
- - **MCP server** with [the full tool set](https://dispatchseo.com/docs/mcp-tools): the
- queue, keywords, rankings, pages, GSC stats, backlink prospects, trend
- topics, site profile. Anything the dashboard can do, your agent can do over
- MCP; parity between the two is a hard rule in this codebase.
- - **Trend radar**: scan for rising topics in your niche, expand a topic into
- concrete guide angles, and queue the good ones.
- - **Guide and tool builders**: guides publish at most one per day, flat and
- permanent (so a queue of thirty approved ideas doesn't become thirty posts
- in a week); free-tool ideas build on approval.
- - **Backlink playbook**: a prospect list prefilled with your product's copy,
- tracked per submission.
- - **Multi-site**: one deployment manages any number of sites. Each project
- gets its own MCP token, its own data, its own settings.
- - **A password-gated dashboard** for the one human in the loop.
- ## 💵 What it costs to run
- Nothing, unless you want paid data. The tiers stack:
- | Tier | Price | What you get |
- | --- | --- | --- |
- | Search Console only | **$0** | Rankings from GSC, keyword ideas from Autocomplete plus your own impression data |
- | + SerpApi free key | **$0** | Live SERP checks, real positions weekly (250 free searches/month) |
- | + DataForSEO | pay per call | Search volume, keyword difficulty, domain rating |
- Free mode finds keywords you can win. Paid mode also knows which ones are
- worth winning.
- ## ☁️ Cloud version
- There's a hosted version for people who'd rather not run a machine: we host it,
- bundle the SERP + volume data into one bill, and replace the Google
- service-account ritual with one click. It's at
- [dispatchseo.com](https://dispatchseo.com). Self-hosting stays feature-complete
- either way - the cloud sells convenience, not capability.
- ## 🧑💻 Developing from source
- ```bash
- git clone https://github.com/NeoZi12/dispatchseo
- cd dispatchseo
- pnpm install
- cp .env.local.example .env.local
- pnpm dev
- ```
- This is the contributor path, not the way to self-host - that's the one-command
- Docker install behind the button at the top. Fill in `.env.local` (Supabase +
- the three secrets) before starting, then open the dashboard on
- **localhost:3000**.
- `pnpm build` is the typecheck - run it before opening a PR. There is no
- separate lint or test setup.
- ## 🏗️ Architecture, briefly
- Next.js App Router, Postgres for state (a bundled container when self-hosted,
- Supabase in the cloud version), `mcp-handler` for the MCP server at `/api/mcp`.
- Schedules and builds run in-stack (cron + builder containers) or on GitHub
- Actions. One deployment is multi-tenant: the MCP bearer token selects the
- project, crons loop over all projects, the dashboard switches with a cookie.
- [Architecture](https://dispatchseo.com/docs/architecture) covers this properly.
- [CLAUDE.md](CLAUDE.md) has the full conventions; it's written for agents, which
- turns out to make it decent documentation for people.
- ## 🤝 Contributing
- Issues before PRs, and you must understand every line you submit, including the
- AI-assisted ones. Details in [CONTRIBUTING.md](CONTRIBUTING.md). Questions go to
- [Discussions](https://github.com/NeoZi12/dispatchseo/discussions) or the
- [Discord](https://dispatchseo.com/discord); vulnerabilities go through
- [private reporting](SECURITY.md).
- ## 📄 License
- [AGPL-3.0](LICENSE). Use it, self-host it, fork it. If you run a modified
- version as a service, share the source. That's the whole deal.
- ---
- <p align="center">
- <sub>Built by <a href="https://github.com/NeoZi12">NeoZi12</a> · If DispatchSEO is useful to you, a ⭐ helps other people find it.</sub>
- </p>
docker/cron/entrypoint.sh · Bundled script · 12 lines · 1 finding marked
- #!/bin/sh
- # Snapshot the env vars the cron jobs need (crond runs jobs with a stripped
- # environment), then run BusyBox crond in the foreground so container logs
- # show every hit.
- {
- echo "CRON_SECRET='${CRON_SECRET}'"
- echo "APP_INTERNAL_URL='${APP_INTERNAL_URL:-http://app:3000}'"
- } > /etc/cron-env
- Note: Quoted as data in code: Sets up something that runs again on its own (cron, launchd, systemd, startup entry or shell profile) and fetches from the network
- Line 8 on GitHub
- chmod 600 /etc/cron-env
- echo "[cron] schedule loaded:"
- cat /etc/crontabs/root
- exec crond -f -l 8 -L /dev/stdout
public/install.sh · Bundled script · 58 lines · 1 finding marked
- #!/bin/sh
- # DispatchSEO one-line installer:
- #
- # curl -fsSL https://dispatchseo.com/install.sh | sh
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 4 on GitHub
- #
- # What it does, in order - each step skips itself if already done:
- # 1. Installs Docker if missing (Linux only, via get.docker.com; on Mac
- # and Windows it points you at Docker Desktop instead).
- # 2. Fetches the repo into ./dispatchseo (git clone, or a tarball when
- # git isn't installed), or updates an existing clone.
- # 3. Runs start.sh, which handles everything else and prints your
- # dashboard URL.
- #
- # Safe to re-run any time; re-running is also the upgrade command.
- set -e
- REPO="https://github.com/NeoZi12/dispatchseo"
- if ! command -v docker >/dev/null 2>&1; then
- case "$(uname -s)" in
- Linux)
- echo "Docker isn't installed - installing it with Docker's official script..."
- curl -fsSL https://get.docker.com | sh
- ;;
- *)
- echo "Docker isn't installed. Install Docker Desktop first:"
- echo " https://docs.docker.com/get-docker/"
- echo "then run this command again."
- exit 1
- ;;
- esac
- fi
- if [ -d dispatchseo/.git ]; then
- echo "Existing install found in ./dispatchseo - updating it."
- # Never let a failed update stop the stack from BOOTING. Under `set -e` a
- # pull that isn't fast-forwardable (a fork with local commits, a hand-edited
- # file, a diverged clone) aborted this script before `sh start.sh` below, so
- # the documented upgrade one-liner left the user's stack down with nothing but
- # a raw git error. start.sh tolerates exactly this for the same reason;
- # GIT_TERMINAL_PROMPT=0 stops a credential prompt hanging an unattended run.
- GIT_TERMINAL_PROMPT=0 git -C dispatchseo pull --ff-only ||
- echo " Couldn't fast-forward (local changes?) - booting the version that's here."
- elif [ -d dispatchseo ]; then
- echo "./dispatchseo exists (tarball install) - refreshing the snapshot."
- curl -fsSL "$REPO/archive/refs/heads/main.tar.gz" | tar xz
- cp -R dispatchseo-main/. dispatchseo/
- rm -rf dispatchseo-main
- elif command -v git >/dev/null 2>&1; then
- git clone "$REPO"
- else
- echo "git isn't installed - downloading a snapshot instead."
- curl -fsSL "$REPO/archive/refs/heads/main.tar.gz" | tar xz
- mv dispatchseo-main dispatchseo
- fi
- cd dispatchseo
- sh start.sh
public/setup.sh · Bundled script · 479 lines · 2 findings marked
- #!/bin/bash
- # DispatchSEO one-command setup.
- # Run from INSIDE your website's repo, with the line your dashboard gives you:
- # curl -fsSL https://dispatchseo.com/setup.sh | bash -s -- <project-key> <slug> [backend-url] [bundled] [agent]
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 4 on GitHub
- #
- # What it does, in order: checks your folder + tools, connects your coding
- # agent in this folder to your DispatchSEO project, saves the GitHub Actions
- # secrets (each value VERIFIED before it is stored), enables PR permissions,
- # then hands off to that agent.
- #
- # Every value is verified before it is saved - this script prefers stopping
- # loudly over storing something broken. Reads answers from /dev/tty so it
- # works when piped from curl.
- #
- # AGENT (5th argument, default claude) picks which coding agent gets connected
- # and which builder credential is collected. It defaults so that every command
- # handed out before this argument existed keeps doing exactly what it did.
- # Both agents get the same pipeline: the workflow files carry both and resolve
- # which to run from the dashboard at run time.
- set -o pipefail
- TOKEN="${1:-}"
- SLUG="${2:-project}"
- BASE="${3:-https://dispatchseo.com}"
- BUNDLED="${4:-0}"
- AGENT="${5:-claude}"
- case "$AGENT" in
- claude) AGENT_CLI="claude"; AGENT_NAME="Claude Code" ;;
- codex) AGENT_CLI="codex"; AGENT_NAME="Codex" ;;
- cursor) AGENT_CLI="cursor-agent"; AGENT_NAME="Cursor" ;;
- *) printf '\n!! Unknown agent "%s". Supported: claude, codex, cursor.\n\n' "$AGENT"; exit 1 ;;
- esac
- say() { printf '%s\n' "$*"; }
- hr() { say "-----------------------------------------------"; }
- die() { printf '\n!! %s\n\n' "$*"; exit 1; }
- ask() { REPLY=""; read -r REPLY < /dev/tty; }
- say ""
- say "==============================================="
- say " DispatchSEO setup - about 3 minutes"
- say "==============================================="
- say ""
- [ -n "$TOKEN" ] || die "No project key given. Copy the FULL command from your DispatchSEO dashboard - it includes your key."
- # ---- 1. Right folder? ------------------------------------------------------
- git rev-parse --is-inside-work-tree >/dev/null 2>&1 || \
- die "This folder is not a git repository. Open a terminal INSIDE your website's repo (the one DispatchSEO publishes to) and run the command again."
- ORIGIN_URL=$(git remote get-url origin 2>/dev/null) || \
- die "This repo has no 'origin' remote. cd into your website's GitHub repo and run the command again."
- REPO=$(printf '%s' "$ORIGIN_URL" | sed -E 's#^(git@github\.com:|https://github\.com/)##; s#\.git$##')
- say "Step 1 of 5 - checking this folder."
- say " Detected repo: $REPO"
- say " Is that your WEBSITE's repo - the one your site deploys from? [y/n]"
- ask
- [ "$REPLY" = "y" ] || [ "$REPLY" = "Y" ] || \
- die "No problem - cd into the right folder and run the same command again."
- # ---- 2. Tools --------------------------------------------------------------
- say ""
- say "Step 2 of 5 - checking your tools."
- if ! command -v "$AGENT_CLI" >/dev/null 2>&1; then
- case "$AGENT" in
- claude) die "Claude Code isn't installed. Install it first (https://claude.com/claude-code), then rerun." ;;
- codex) die "Codex isn't installed. Install it first (npm i -g @openai/codex, or see https://developers.openai.com/codex/cli), then rerun." ;;
- cursor) die "Cursor's CLI isn't installed. Install it first (curl https://cursor.com/install -fsS | bash), make sure ~/.local/bin is on your PATH, then rerun." ;;
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 70 on GitHub
- esac
- fi
- command -v gh >/dev/null 2>&1 || \
- die "The GitHub CLI (gh) isn't installed. Install it (macOS: brew install gh), run 'gh auth login', then rerun."
- gh auth status >/dev/null 2>&1 || \
- die "The GitHub CLI isn't logged in. Run 'gh auth login', then rerun."
- say " All tools present."
- # ---- 3. Connect the agent to your project ----------------------------------
- say ""
- # "in this folder" is Claude's line and stays exactly as it was - it is true
- # because of --scope local. Codex must NOT claim it: its config is global, and
- # the per-project server name is what keeps two sites apart.
- # Cursor joins Claude on the "in this folder" line: its config is
- # .cursor/mcp.json, read relative to the directory the agent runs in, so it is
- # genuinely folder-scoped. Only Codex has to omit the claim.
- if [ "$AGENT" = "codex" ]; then
- say "Step 3 of 5 - connecting $AGENT_NAME to your project."
- else
- say "Step 3 of 5 - connecting $AGENT_NAME in this folder to your project."
- fi
- code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 30 -X POST "$BASE/api/mcp" \
- -H "Authorization: Bearer $TOKEN" \
- -H "Content-Type: application/json" \
- -H "Accept: application/json, text/event-stream" \
- -d '{"jsonrpc":"2.0","id":0,"method":"tools/list"}')
- [ "$code" = "200" ] || \
- die "Your project key was rejected (HTTP $code). Keys change when a project is recreated - copy the CURRENT command from the dashboard and run it instead."
- NAME="dispatchseo-$SLUG"
- if [ "$AGENT" = "claude" ]; then
- # --scope local pins this connection to THIS folder. Without it a connection
- # can end up at user scope and leak into every project the owner opens
- # Claude Code in - an owner with several projects connected would then have
- # all of them active at once in an unrelated repo, and the install
- # workflow's repo-remote check would keep failing against the wrong
- # project's token. Scope local on both remove and add so a stray user-scope
- # entry from an older run gets found and cleaned up too.
- claude mcp remove --scope local "$NAME" >/dev/null 2>&1
- claude mcp remove --scope user "$NAME" >/dev/null 2>&1
- # Name immediately after `add`: the CLI's parser is order-fragile
- # (anthropics/claude-code#2341 - options before the name can throw
- # "missing required argument 'name'").
- claude mcp add "$NAME" "$BASE/api/mcp" --transport http --scope local \
- --header "Authorization: Bearer $TOKEN" >/dev/null 2>&1 || \
- die "Could not add the connection to Claude Code (claude mcp add failed)."
- elif [ "$AGENT" = "codex" ]; then
- # Codex has no scope flag at all - `codex mcp add` always writes the config
- # Codex calls global. The per-project server NAME is what keeps two projects
- # from shadowing each other, and every prompt we hand the agent names its
- # server literally. No remove step: unlike Claude's, this add overwrites an
- # existing entry of the same name instead of erroring.
- #
- # The key rides in the URL rather than in --bearer-token-env-var, which takes
- # the NAME of an environment variable - that variable would then have to
- # exist in every shell the owner ever launches Codex from, and a missing one
- # fails at tool-call time with nothing pointing at the cause.
- codex mcp add "$NAME" --url "$BASE/api/mcp?key=$TOKEN" >/dev/null 2>&1 || \
- die "Could not add the connection to Codex (codex mcp add failed). Check 'codex --version' - the mcp subcommand needs a recent build."
- elif [ "$AGENT" = "cursor" ]; then
- # Cursor has NO `mcp add` command - its whole mcp surface is
- # login/list/list-tools/enable/disable, so connecting means writing the
- # config file. Merged rather than overwritten: .cursor/mcp.json is the
- # owner's file and may already hold other servers.
- mkdir -p .cursor
- command -v node >/dev/null 2>&1 || \
- die "node isn't installed, and Cursor's connection is a JSON file this script edits with it. Install Node (https://nodejs.org), then rerun."
- CURSOR_NAME="$NAME" CURSOR_URL="$BASE/api/mcp" CURSOR_TOKEN="$TOKEN" node -e '
- const fs=require("fs"),f=".cursor/mcp.json";
- const c=fs.existsSync(f)?JSON.parse(fs.readFileSync(f,"utf8")):{};
- c.mcpServers=c.mcpServers||{};
- c.mcpServers[process.env.CURSOR_NAME]={url:process.env.CURSOR_URL,headers:{Authorization:"Bearer "+process.env.CURSOR_TOKEN}};
- fs.writeFileSync(f,JSON.stringify(c,null,2)+"\n");
- ' >/dev/null 2>&1 || \
- die "Could not write .cursor/mcp.json - check the folder is writable and any existing .cursor/mcp.json is valid JSON."
- # Approval is part of connecting, not an afterthought: an unapproved server
- # is not merely unreachable, it is ABSENT - Cursor starts with zero tools and
- # says "not loaded (needs approval)".
- cursor-agent mcp enable "$NAME" >/dev/null 2>&1 || \
- die "Wrote the connection but could not approve it (cursor-agent mcp enable failed). Run 'cursor-agent mcp enable $NAME' in this folder and rerun."
- fi
- say " Connected (key verified against the server)."
- [ "$AGENT" = "codex" ] && \
- say " Tired of approving every call? $BASE/docs/install-codex shows the one config line that stops the prompts for this server."
- # Let the agent actually use gh. Claude Code gates terminal commands, and gh
- # is not allowed by default - so the install agent's FIRST step (gh auth
- # status, the same check this script passed at step 2) gets blocked. That
- # block cannot be lifted from the chat: telling the agent "you have my
- # permission" never reaches the gate, and the agent correctly refuses to
- # grant itself the rule by editing this file. Left to the owner it is a
- # dead stop on step one, right after paying. So write it here, where we
- # already know they want DispatchSEO driving gh in this repo.
- #
- # Additive on purpose: an existing settings.local.json belongs to the owner,
- # so we merge into it and never clobber it. Without a JSON tool we print the
- # line instead of risking their file.
- #
- # Claude only. Codex has no permissions file to pre-write: it asks for approval
- # at the moment it wants to run something and the owner answers, so there is no
- # dead stop to prevent - and writing an allowlist for an agent that does not
- # read one would be a comforting no-op.
- SETTINGS=".claude/settings.local.json"
- GH_RULE='Bash(gh *)'
- # Only Claude Code has a pre-grantable allowlist file. Codex and Cursor both
- # ask at the moment they want to run something, and the owner answers.
- [ "$AGENT" = "claude" ] && mkdir -p .claude 2>/dev/null
- if [ "$AGENT" != "claude" ]; then
- say " $AGENT_NAME asks before it runs a command - approve the gh ones when it does."
- elif [ ! -f "$SETTINGS" ]; then
- ( printf '%s\n' '{' ' "permissions": {' ' "allow": ["Bash(gh *)"]' ' }' '}' > "$SETTINGS" ) 2>/dev/null \
- && say " Allowed Claude Code to run gh in this folder ($SETTINGS)." \
- || say " ! Could not write $SETTINGS - if the agent stalls on a gh command, add \"$GH_RULE\" to its permissions.allow."
- elif grep -Fq "$GH_RULE" "$SETTINGS" 2>/dev/null; then
- say " Claude Code may already run gh here - left $SETTINGS alone."
- elif command -v python3 >/dev/null 2>&1; then
- python3 - "$SETTINGS" "$GH_RULE" <<'PY' 2>/dev/null && say " Allowed Claude Code to run gh in this folder (added to your $SETTINGS)." \
- || say " ! Could not update $SETTINGS - add \"$GH_RULE\" to permissions.allow yourself if the agent stalls on a gh command."
- import json, sys
- path, rule = sys.argv[1], sys.argv[2]
- with open(path) as f:
- data = json.load(f)
- if not isinstance(data, dict):
- raise SystemExit(1)
- perms = data.setdefault("permissions", {})
- allow = perms.setdefault("allow", [])
- if not isinstance(allow, list):
- raise SystemExit(1)
- if rule not in allow:
- allow.append(rule)
- with open(path, "w") as f:
- json.dump(data, f, indent=2)
- f.write("\n")
- PY
- else
- say " ! $SETTINGS exists and python3 isn't available to merge into it."
- say " Add \"$GH_RULE\" to its permissions.allow, or the agent will stall on its first gh command."
- fi
- # ---- 4. GitHub secrets - every value verified before it is stored ----------
- say ""
- say "Step 4 of 5 - the GitHub secrets your automations run on."
- printf '%s' "$TOKEN" | gh secret set SEO_MCP_API_KEY --repo "$REPO" || \
- die "Could not save a secret to $REPO - does your GitHub login have admin access to it?"
- say " Project key saved."
- # The builder credential, per agent. Every one is VERIFIED against the real
- # provider before it is stored - the rule everywhere in this script - because
- # a saved-but-broken credential reads as "automatic builds are set up" and only
- # announces itself as a failed run at 05:13 the next morning.
- if [ "$AGENT" = "cursor" ]; then
- say ""
- if gh secret list --repo "$REPO" 2>/dev/null | grep -q "^CURSOR_API_KEY"; then
- say " A Cursor API key is already saved for this repo."
- say " Keep it? [y = keep / n = replace with a different one]"
- ask
- else
- REPLY="n"
- fi
- if [ "$REPLY" != "y" ] && [ "$REPLY" != "Y" ]; then
- say ""
- say " The overnight builds run on a server with no browser, so the login"
- say " you just used doesn't reach them - they need a Cursor API key."
- say " Any plan can mint one, and nothing is billed by DispatchSEO."
- say ""
- say " Create one at cursor.com/dashboard/api (open that URL directly -"
- say " the page is often missing from the dashboard's own menu), paste it"
- say " here and press Enter. It won't be shown:"
- while true; do
- read -r -s CKEY < /dev/tty
- say ""
- CKEY=$(printf '%s' "$CKEY" | tr -d '[:space:]')
- case "$CKEY" in
- "")
- say " Nothing pasted. Paste the key, or press Ctrl-C to stop and set it later:" ; continue ;;
- sk-ant-*)
- say " That's a Claude token, not a Cursor key. Paste the Cursor one:" ; continue ;;
- sk-*)
- say " That's an OpenAI key, not a Cursor key. Paste the Cursor one:" ; continue ;;
- esac
- if [ "${#CKEY}" -lt 20 ]; then
- say " That looks too short to be a whole key. Copy all of it and paste again:" ; continue
- fi
- # VERIFIED, not just shape-checked. Two measured details make this
- # trustworthy where the obvious version would not be:
- # - `cursor-agent models` EXITS 0 even when the key is invalid, so the
- # text is what gets checked, never $?.
- # - a key set here beats any interactive login already on this machine
- # (the CLI says so: "The API key was loaded from the CURSOR_API_KEY
- # environment variable"), so this cannot pass on the owner's own
- # session the way an unguarded Claude token check can.
- say " Checking the key with Cursor..."
- OUT=$(CURSOR_API_KEY="$CKEY" cursor-agent models 2>&1)
- case "$OUT" in
- *"Available models"*) break ;;
- *"API key is invalid"*|*"Authentication required"*|*Unauthorized*)
- say " Cursor rejected that key. Create a fresh one at"
- say " cursor.com/dashboard/api and paste it again:" ; continue ;;
- *)
- say " Couldn't check the key - Cursor answered with something"
- say " unexpected. Paste it again, or Ctrl-C and set it later:" ; continue ;;
- esac
- done
- printf '%s' "$CKEY" | gh secret set CURSOR_API_KEY --repo "$REPO" >/dev/null 2>&1 || \
- die "Could not save CURSOR_API_KEY to $REPO - does your GitHub login have admin access to it?"
- say " Cursor key verified and saved."
- fi
- elif [ "$AGENT" = "codex" ]; then
- say ""
- if gh secret list --repo "$REPO" 2>/dev/null | grep -q "^OPENAI_API_KEY"; then
- say " An OpenAI key is already saved for this repo."
- say " Keep it? [y = keep / n = replace with a different one]"
- ask
- else
- REPLY="n"
- fi
- if [ "$REPLY" != "y" ] && [ "$REPLY" != "Y" ]; then
- say ""
- say " Your builders run on your own OpenAI API key - OpenAI bills you"
- say " per run, and nothing is billed by DispatchSEO."
- say ""
- say " Create a key at https://platform.openai.com/api-keys (it must be on"
- say " an account with credit on it), paste it here and press Enter."
- say " It won't be shown:"
- while true; do
- read -r -s OKEY < /dev/tty
- say ""
- OKEY=$(printf '%s' "$OKEY" | tr -d '[:space:]')
- case "$OKEY" in
- sk-*)
- [ "${#OKEY}" -gt 20 ] && break
- say " That looks too short - paste the WHOLE key and press Enter." ;;
- "") say " Nothing pasted. Copy the key and press Enter." ;;
- *) say " An OpenAI key starts with sk-. Copy just the key and press Enter." ;;
- esac
- done
- say " Verifying the key against OpenAI..."
- # A real inference call, not a models list: an unfunded account happily
- # lists models it cannot call, so anything cheaper than this would pass a
- # key that then fails on the first real build.
- ocode=$(curl -s --max-time 30 -o /tmp/dispatchseo-openai.json -w "%{http_code}" \
- https://api.openai.com/v1/responses \
- -H "Authorization: Bearer $OKEY" -H "Content-Type: application/json" \
- -d '{"model":"gpt-5-mini","input":"ok","max_output_tokens":16}')
- oerr=$(grep -o '"code": *"[^"]*"' /tmp/dispatchseo-openai.json 2>/dev/null | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
- rm -f /tmp/dispatchseo-openai.json
- case "$ocode" in
- 2*) printf '%s' "$OKEY" | gh secret set OPENAI_API_KEY --repo "$REPO"
- say " OpenAI key verified and saved." ;;
- 401|403) die "OpenAI rejected that key. Copy it again from platform.openai.com/api-keys - a key is only shown once, so a half-copied one is the usual cause." ;;
- 429) die "That key is real but the account can't run anything right now (OpenAI said: ${oerr:-quota exceeded}). Add credit at platform.openai.com/settings/organization/billing, then run this script again." ;;
- *) die "Couldn't reach OpenAI to verify the key (HTTP $ocode). Check your connection and run this script again." ;;
- esac
- fi
- else
- # Claude Code token - minted fresh, verified with NO login fallback (a fake
- # HOME), because a keychain login otherwise masks a bad token.
- CLIP="pbpaste"
- if ! command -v pbpaste >/dev/null 2>&1; then
- CLIP="xclip -o -selection clipboard"
- command -v xclip >/dev/null 2>&1 || \
- die "No clipboard tool found. Install xclip (e.g. sudo apt install xclip), then run this script again."
- fi
- if gh secret list --repo "$REPO" 2>/dev/null | grep -q "^CLAUDE_CODE_OAUTH_TOKEN"; then
- say ""
- say " A Claude Code token is already saved for this repo."
- say " Keep it? [y = keep / n = replace with a fresh one]"
- ask
- else
- REPLY="n"
- fi
- if [ "$REPLY" != "y" ] && [ "$REPLY" != "Y" ]; then
- say ""
- say " Creating your Claude Code token (the builders run on YOUR Claude"
- say " subscription - nothing is billed by DispatchSEO)."
- say " Press Enter; a browser opens - click Approve with your normal"
- say " Claude account."
- ask
- claude setup-token < /dev/tty
- say ""
- hr
- say " See the long token above (starts with sk-ant-oat)? Select it and"
- say " copy it (Cmd+C - two lines is fine), then press Enter here."
- while true; do
- ask
- CTOKEN=$($CLIP 2>/dev/null | tr -d '[:space:]')
- case "$CTOKEN" in
- sk-ant-oat*)
- if [ "${#CTOKEN}" -gt 60 ]; then break; fi
- say " That looks too short - copy the WHOLE token, then press Enter." ;;
- *)
- say " Your clipboard holds something else. Copy JUST the token, then press Enter." ;;
- esac
- done
- say " Verifying the token for real (no login fallback)..."
- mkdir -p /tmp/claude-fakehome
- if HOME=/tmp/claude-fakehome CLAUDE_CODE_OAUTH_TOKEN="$CTOKEN" claude -p "reply with just: ok" </dev/null >/dev/null 2>&1; then
- printf '%s' "$CTOKEN" | gh secret set CLAUDE_CODE_OAUTH_TOKEN --repo "$REPO"
- say " Claude token verified and saved."
- else
- die "The token doesn't work - usually the browser approved the WRONG account. Log into your subscription account on claude.ai and run this script again."
- fi
- fi
- fi # end of the per-agent builder-credential branch
- # DataForSEO - only if this project uses its own account. Cloud projects on
- # the bundled plan skip this entirely: the platform bills a DataForSEO
- # account server-side, so there is nothing to collect here (the owner can
- # still connect their own later, from Settings, for unmetered usage).
- if [ "$BUNDLED" = "1" ]; then
- say ""
- say " DataForSEO is included with your plan - nothing to set up here."
- else
- say ""
- say " Does this project use DataForSEO for keyword data? [y/n]"
- say " (If you picked the free mode in onboarding, answer n.)"
- ask
- if [ "$REPLY" = "y" ] || [ "$REPLY" = "Y" ]; then
- say ""
- say " Your DataForSEO LOGIN is your account email. Type it and press Enter:"
- read -r DFS_LOGIN < /dev/tty
- say ""
- say " Your DataForSEO PASSWORD is the API password from"
- say " app.dataforseo.com/api-access - NOT your dashboard login password."
- say " Paste it and press Enter (it won't be shown):"
- read -r -s DFS_PASS < /dev/tty
- say ""
- say " Verifying against DataForSEO..."
- dfs=$(curl -s --max-time 30 -u "$DFS_LOGIN:$DFS_PASS" https://api.dataforseo.com/v3/appendix/user_data | grep -o '"status_code":20000' | head -1)
- if [ -n "$dfs" ]; then
- printf '%s' "$DFS_LOGIN" | gh secret set DATAFORSEO_LOGIN --repo "$REPO"
- printf '%s' "$DFS_PASS" | gh secret set DATAFORSEO_PASSWORD --repo "$REPO"
- say " DataForSEO verified and saved."
- else
- die "DataForSEO rejected those credentials. Double-check: LOGIN = account email, PASSWORD = the API password from app.dataforseo.com/api-access. Then rerun this script."
- fi
- else
- say " Skipping DataForSEO - the workflows handle its absence cleanly."
- fi
- fi
- # Allow Actions to open PRs (the builders publish via PRs). The 2026-07-20
- # dogfood repo skipped setup.sh, missed this toggle, and its builder wrote a
- # whole guide it then couldn't open a PR for - hence the canary below, which
- # PROVES the toggle works instead of trusting this call succeeded.
- if gh api -X PUT "repos/$REPO/actions/permissions/workflow" \
- -f default_workflow_permissions=write \
- -F can_approve_pull_request_reviews=true >/dev/null 2>&1; then
- say " GitHub Actions allowed to open pull requests."
- else
- say " ! Couldn't change Actions permissions automatically. In the repo's"
- say " Settings > Actions > General, enable 'Allow GitHub Actions to"
- say " create and approve pull requests'."
- fi
- # Prove the PR machinery end-to-end with a throwaway canary PR (opened from
- # inside a workflow, closed by the same run, never merged). Fresh installs
- # don't have the workflows yet - the agent's install playbook runs the canary
- # after its pipeline PR merges; this path covers re-runs and updates.
- if gh workflow run seo-canary.yml --repo "$REPO" >/dev/null 2>&1; then
- say " Proving workflows can open PRs (canary run, ~30s)..."
- verdict=""
- i=0
- while [ $i -lt 24 ]; do
- sleep 5; i=$((i+1))
- verdict=$(gh run list --repo "$REPO" --workflow seo-canary.yml --limit 1 \
- --json status,conclusion --jq '.[0] | select(.status=="completed") | .conclusion' 2>/dev/null)
- [ -n "$verdict" ] && break
- done
- case "$verdict" in
- success) say " Canary passed - workflows can build and publish PRs on $REPO." ;;
- "") say " ! Canary still running - check its result: gh run list --workflow seo-canary.yml" ;;
- *) say " ! CANARY FAILED ($verdict) - workflows cannot open PRs yet. Enable"
- say " 'Allow GitHub Actions to create and approve pull requests' in"
- say " Settings > Actions > General, then: gh workflow run seo-canary.yml" ;;
- esac
- else
- say " (Canary workflow not in this repo yet - your agent runs it after the"
- say " pipeline install PR merges.)"
- fi
- # ---- 5. Hand off to the agent ----------------------------------------------
- # $NAME, not "seo-manager": the prompt must name the server exactly as it
- # was just registered - agents take the name literally and refuse on a
- # name they cannot find.
- #
- # Both agents install the same pipeline. The workflow files it writes carry
- # BOTH agents and resolve which one to run at run time from the dashboard, so
- # there is no per-agent install and no decision for the installer to get wrong.
- say ""
- say "Step 5 of 5 - your agent installs the pipeline (a few minutes; it"
- say "opens a pull request and may ask you questions along the way)."
- PROMPT="Call the $NAME MCP tool get_instructions with workflow install and follow it exactly."
- say ""
- say "Launch $AGENT_NAME now to finish? [y/n]"
- ask
- if [ "$REPLY" = "y" ] || [ "$REPLY" = "Y" ]; then
- exec "$AGENT_CLI" "$PROMPT" < /dev/tty
- else
- say ""
- say "==============================================="
- say " Setup saved. Whenever you're ready, open $AGENT_NAME in this"
- say " folder and paste:"
- say ""
- say " $PROMPT"
- say "==============================================="
- fi
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.