Everything you need to run your first optimization.
These guides walk through the operator side of the pipeline — getting a run configured correctly, preparing input the agents can actually use, and reading what comes back. For field-by-field specs, see the reference docs.
01 · Quick start
Six steps from a clean checkout to a pushed commit.
.env file next to main.py with OPENAI_API_KEY set. The server refuses to start a run without it — you'll see that error immediately rather than partway through a run.# .env
OPENAI_API_KEY=sk-...pip install -r requirements.txt
python main.py
# → serving on http://0.0.0.0:7860http://localhost:7860. This is a plain HTML form — no separate frontend build needed. It posts directly to /run.02 · Preparing your CSV
The CSV is the only thing standing between "the agent has an opinion" and "the agent is guessing." url is the only column that's truly required — everything else fills in a sensible default if it's missing, but the fixes get noticeably better the more of this the crawler filled in.
| Column | Minimum viable value |
|---|---|
url | Full page URL — required, used to resolve the file on disk |
title | Leave blank if unknown; the agent will propose one |
top_keywords | Even 2–3 comma-separated terms meaningfully improves output |
canonical_tag | "false" if there isn't one yet — don't leave this blank |
robots_meta | "index, follow" if you're not sure |
AGENTS=technical) against a staging branch to get a baseline sitemap and robots.txt before layering on-page content changes on top.03 · Choosing which agents to run
Set the agents field to one of three values. Each agent commits and pushes independently, so running one doesn't require the other to have run first.
| Value | Runs | Good for |
|---|---|---|
onpage | Titles, meta, schema, OG/Twitter, alt text | A content refresh where crawlability is already solid |
technical | robots.txt, sitemap, canonical, noindex, hreflang | A brand-new site, or a migration where URLs changed |
onpage,technical | Both, in that order | First run against a new repository |
04 · Reading a run's output
The response is JSON with returncode, stdout, stderr, and a success boolean. The interesting detail is in stdout — the orchestrator logs per-page, per-agent progress as it works.
✅ File written: app/pricing/page.js
⚠️ LLM/fix failed, keeping original: app/about/page.js
❌ No file mapped for https://example.com/blog/untracked-post
ℹ️ Client component, skipping metadata-level technical fix: app/widget/page.js| Marker | Meaning |
|---|---|
| ✅ | File written successfully — this page's fix is live in the working tree |
| ⚠️ | The model's output was empty or suspiciously short — original file kept, nothing lost |
| ❌ | No file could be resolved for that URL — usually a stack mismatch or unusual routing |
| ℹ️ | Expected skip — client component, unsupported stack, or similar, not an error |
05 · Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| 500 — OPENAI_API_KEY not set | Missing or unloaded .env | Confirm the key is in .env next to main.py, and that it's actually loaded before the server starts |
| 400 — CSV file is empty | Upload succeeded but the file has 0 bytes | Re-export the audit and confirm it opens locally before uploading |
| 500 — Process timed out after 10 minutes | Large CSV, many OpenAI calls per page | Split the CSV and run in batches, or run technical-only first to shrink onpage's row count |
| "No file mapped for {url}" | URL doesn't match the site's routing, or stack isn't Next.js | Check the URL path against your app/pages directory structure; non-Next.js stacks only get site-level fixes today |
| Nothing changed in the diff | safe_write's truncation guard rejected the model's output | Check stdout for a ⚠️ line on that file — the original was kept intentionally |
Next steps
Once a run looks right, the reference docs cover the full API surface, the write safety guarantees behind these fixes, and what's coming next for Shopify and WordPress support.
Go to reference docs