SEO Machine: a Claude Code workspace for long-form SEO content

Who SEO Machine is built for, and who it is not

The repository describes itself as a specialized Claude Code workspace for long-form, SEO-optimized blog content "for any business." That phrasing hides a narrower fit. The workflow assumes a company with a real blog, an existing set of published posts worth updating, and a keyword list someone has already thought about. The context directory ships as templates, and the README points at examples/castos/ as a filled-in reference for a podcast hosting SaaS company. If your product has no blog and no keyword research, the first /research run has nothing to anchor to.

The second assumption is tooling. SEO Machine is not a standalone app. It runs inside Claude Code, which the README lists as a prerequisite alongside an Anthropic API account. The analysis scripts under the repository root (seo_baseline_analysis.py, seo_competitor_analysis.py, research_serp_analysis.py and others) read credentials for Google Analytics 4, Google Search Console and DataForSEO. A team that wants article generation without those accounts is paying setup cost for modules it will never call.

The third assumption is volume. Commands produce 2000-3000+ word articles and save them to drafts/, research briefs to research/, rewrites to rewrites/. That directory structure only pays off if you publish often enough to need a filing system.

How the command and agent pipeline actually moves a topic to a draft

The mechanism is a set of slash commands backed by subagents, all defined inside .claude/, with the surrounding Python only handling data pulls and scoring. A typical pass starts with /research [topic], which the README says performs keyword research, analyzes the top 10 competitors, identifies content gaps and writes a brief to /research/brief-[topic]-[date].md.

/write [topic or research brief] then produces the article and, per the README, automatically triggers four agents: an SEO Optimizer, a Meta Creator, an Internal Linker and a Keyword Mapper. Those agents run against the draft rather than against the open web, which is why the context files matter. Brand voice comes from context/brand-voice.md; internal link targets come from context/internal-links-map.md; keyword placement is checked against context/target-keywords.md. The draft lands in /drafts/[topic]-[date].md with meta elements attached.

The final stage is /optimize [article file], described as a comprehensive SEO audit that validates elements, produces a publishing readiness score and writes an optimization report. For existing posts the entry point differs: /analyze-existing accepts a URL or a file path, returns a content health score from 0 to 100, and saves to /research/analysis-[topic]-[date].md. /rewrite then updates the piece and records a change summary and before/after comparison in /rewrites/.

One design detail worth noting: the scoring scripts are plain Python at the repository root, not part of the agent layer. That separation means you can read the scoring logic without reading prompt files, which is more than most content tooling offers.

Installing SEO Machine and running a first research pass

The README gives a four-step install. Clone the repository, install the Python dependencies for the analysis modules, open the directory in Claude Code, then fill in the context templates. The clone step is ordinary:

clone https://github.com/TheCraigHewitt/seomachine.git
cd seomachine

The README notes that contributors should fork first and clone their fork instead. Dependencies install from a single requirements file, which the README says covers the Google Analytics and Search Console integrations, the DataForSEO client, nltk and textstat, scikit-learn and beautifulsoup4:

pip install -r data_sources/requirements.txt

If you prefer containers, the repository ships a docker-compose.yml whose seomachine service builds from the included Dockerfile (python:3.12-slim, with build-essential, gcc, libxml2-dev and libxslt1-dev installed for the scientific and XML packages). Credentials are read from data_sources/config/.env, and eight content directories are mounted as volumes so drafts and research survive a container rebuild:

docker-compose build
docker-compose run seomachine bash

The environment file is templated at .env.example and covers GA4_PROPERTY_ID, GA4_CREDENTIALS_PATH, GSC_SITE_URL, GSC_CREDENTIALS_PATH, DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD, plus an optional BLOG_PATH that defaults to /blog/ and must be changed if your posts live under /articles/ or /resources/.

Before any command produces something useful, the context files have to be written. The README calls this step important and lists eight files, including context/writing-examples.md with 3-5 exemplary posts and context/competitor-analysis.md. Only after that does the first real command make sense:

/research content marketing strategies for B2B SaaS

Expect a brief in research/ rather than a finished article. The README's own examples use that exact phrasing, so it is a safe first invocation.

Where SEO Machine breaks down: context debt and credential gaps

The honest limitation is that SEO Machine is a template, not a product. Every context file ships empty or as a placeholder, and the README's quick start is a pointer to examples/castos/ rather than a generator. Until brand-voice.md and writing-examples.md contain your own material, the writing agents have no voice to imitate and will produce generic marketing prose. That is not a bug in the pipeline; it is the pipeline working as designed, which is cold comfort if you expected output on day one.

The second failure mode is credential-shaped. The data integrations need a Google Cloud service account for GA4 and Search Console plus a DataForSEO account. Without them, the performance and SERP scripts have no input, and commands that lean on live data degrade into guesswork. The .env.example warns in capitals never to commit a real .env, and the Docker setup mounts a credentials/ directory, which tells you the project expects secrets on disk rather than in a secret manager.

The third is scope. The README positions the system for long-form blog content. If your need is product descriptions, landing page copy at scale, or short social posts, the 2000-3000+ word target and the research brief stage are overhead you cannot switch off. There is a landing page optimizer agent in the list, but the documented workflows are all article-shaped.

Finally, the repository has no retrieved releases. There is no version number to pin to, so an upgrade means pulling main and re-reading the diff against your edited context files.

SEO Machine compared with wiring Claude Code yourself

The real alternative is not another content platform. It is an empty Claude Code project with your own CLAUDE.md and a couple of hand-written commands. The difference is what you inherit. SEO Machine ships 26 marketing skills covering copywriting, CRO, A/B testing, email sequences and pricing strategy, plus a set of named agents (content analyzer, meta element creation, keyword mapping, headline generator, CRO analyst) and the Python scoring scripts. Building that from scratch is weeks of prompt iteration.

The trade-off runs the other way too. A hand-rolled workspace contains only the commands you actually use, so there is no context directory to maintain and no DataForSEO dependency to satisfy. SEO Machine's breadth is its cost: the more skills and agents in the workspace, the more surface area that reads your context files and can drift from your intent. If you only ever run /write and /optimize, you are carrying the research scripts and integrations for nothing.

A second comparison is with the WordPress integration directory in the repository. The README mentions a /publish-draft command and the tree includes a wordpress/ folder, so the project reaches toward the publishing end of the pipeline. That is a different bet from tools that stop at the draft. Whether the WordPress path is as developed as the research path is not something the README spells out, and that asymmetry is worth checking before you plan around it.

Licence, maintenance and the cost of keeping context current

SEO Machine is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is permissive enough for agency work and for internal tooling. The licence says nothing about the third-party services the project calls: DataForSEO is a paid API, and Google Analytics 4 and Search Console access carry their own terms. Reviewing those separately is your responsibility, not the licence's.

On maintenance, the last push to the default branch was on 2026-08-05, and the repository is not archived. There are no retrieved releases, so there is no changelog to read between pulls.

The ongoing cost that matters is not code upgrades. It is context upkeep. Every time your brand voice shifts, you edit context/brand-voice.md. Every time you publish a post worth imitating, context/writing-examples.md is a candidate for an addition. Every new pillar page belongs in context/internal-links-map.md, or the Internal Linker agent will keep suggesting links to pages you have retired. That is a recurring editorial task, and it is the part teams underestimate when they evaluate a workspace like this.

Editorial conclusion

Adopt SEO Machine if you already run Claude Code and are willing to spend an afternoon writing context/brand-voice.md, context/writing-examples.md and context/internal-links-map.md before the first /research run. Skip it if your content is short-form or you have no Google Analytics 4, Search Console or DataForSEO credentials, because the analysis modules have nothing to read. Verify first that pip install -r data_sources/requirements.txt resolves in your environment and that examples/castos/ matches the shape of your own context files.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. TheCraigHewitt/seomachine on GitHub