beyondtahir/beyondseo: render an article and wait for its visible content.

Understand your website. Strengthen your answers. Build evidence people can trust.
A complete SEO workflow with its own crawler, reputation system and specialist playbooks.

Quick start · Install the skill · Documentation · Questions & examples · About

What's New

BeyondSEO 2.9.1 · Know your website better. Fix it with confidence.

Windows reliability fix: 2.9.1 closes saved-audit database connections promptly, fixing a file-lock error found by the Windows test suite.

A useful audit should tell you what was checked, what needs attention and what to do next. This update makes those answers clearer—and helps you check the results when changes are made.

• Start with the pages that matter. A normal audit checks up to 15 priority pages, starting with your homepage and favouring about, contact and service pages. Choose a homepage check, specific URLs or a deeper review when you need it.
• Pick up where you left off. Continue a saved audit with another batch of pages instead of checking the same pages again.
• Know what the report covers. See which pages were inspected, only partly captured, blocked or still waiting. A page that could not be read is not treated as proof of missing content.
• Catch more overlooked issues. Get clearer checks for problem sitemap links, conflicting structured data, language-page connections, duplicate descriptions and image settings—with the affected pages and practical next steps.
• Understand what is stopping a check. Readiness checks now test browser JavaScript and file access, with optional checks for your website's connection, robots rules and sitemaps. Installed software alone is not reported as a successful website check.
• Check changes more carefully. Updated guidance separates making a change from verifying it. Supported PHP edits require a syntax check before staging and applying; layout checks, fresh page checks and rollback remain part of the website-work workflow.

Your competitor research, backlink planning, SEO/AEO/GEO guidance, branded reports and optional monitoring remain included. No required paid SEO API has been added.

Try “Audit my 15 most important pages and explain what to fix first” or “Continue my saved audit with 10 more pages.” Page selection uses URL patterns, so your agent should review the selection and use exact URLs when needed.

Download BeyondSEO 2.9.1 · Release notes and validation · Installation guide · All updates

Choose how much of your website to check

Start small or go deeper: choose the homepage, a standard 15-page priority sample, a custom page limit or a list of exact URLs. The report shows what was inspected and what remains, and a saved audit can continue with another batch. A sample is not a complete-site audit.

See audit-depth commands, readiness checks and safe website changes.

Research that explains its evidence

BeyondSEO now checks what a business actually offers before comparing it. Shared search discovery can use native public search, available assistant search tools, saved results or supplied URLs. Failed sources retain their diagnostics and fall back where access is permitted. Candidate pages are checked by the crawler; snippets never count as backlinks.

Business profiles separate services, customers, offices, markets and languages. Competitor selection shows its criteria, supporting pages, important differences and rejected candidates. Audit findings include the affected URL, captured evidence, action and a practical acceptance check. Partial captures stay partial.

Read the step-by-step research guide and host-specific failure guidance. No paid SEO API is required; search access and host permissions still vary.

Your complete SEO house

BeyondSEO connects the work that normally gets scattered across separate audits, content briefs, backlink spreadsheets and follow-up reports. Give it a website and a business goal. It helps you inspect the site, understand the gaps, compare relevant competitors, write useful content and build a practical improvement plan. When you ask it to do the work, your agent can apply approved changes and keep progress visible through an optional private dashboard.

SEO · AEO · GEO · Entity · Authority · Reputation · Local visibility · Backlinks · Conversion

The native Python engine gathers evidence. The reusable skill brings specialist methods and business context. Your existing AI agent brings the available editing and project tools. Together, they support the work from the first crawl through approved improvements and follow-up reviews.

Explore every capability →

Understand your standing, then act

BeyondSEO's deep research workflow starts with your business, checks the browser available to your agent, tries Google through that permitted browser and uses supported fallbacks when needed. It researches a broader pool before recommending up to five comparable businesses, verifies reputation sources and compares equivalent pages. Shared research budgets and evidence checks prevent a thin sample from becoming an inflated competitive ranking. The report connects gaps to keywords, customer answers and a practical publishing plan using the 206-entry directory. Actual search observations, AI readiness and reputation evidence stay distinct.

Ask BeyondSEO to do the work

BeyondSEO can guide authorised on-site changes while preserving the existing design and concise copy. It records a private project plan, implementation estimates, activity and acceptance evidence. An optional branded monitor shows progress across capable AI assistants, coding agents and website-builder workflows; your existing agent chat remains the place to request work. Local runtimes can serve the monitor privately; hosted environments can return a dated HTML artifact when supported. New pages need authorisation, and off-site recommendations remain a practical manual posting plan.

The native helpers stage conservative static HTML edits and sitemap drafts, retain reviewed changes/backups, and run bounded read-only reviews. Framework editing and visual verification use the host's actual tools. Scheduling requires a working host scheduler; a dashboard is not an always-on worker. See website work and the coding-agent and website-builder installation routes. No ranking, universal-host or zero-error guarantee is implied.

Install in your assistant

Choose your app and follow its short guide. The skill includes the SEO workflows, backlink library and native crawler.

ChatGPT Work · Claude · Claude Code · Codex · Hermes · OpenClaw · Cursor · Lovable · Vercel / v0 projects

Download the skill ZIP · Download the complete source folder · Release packages and checksum · What it installs and accesses

For Claude and ChatGPT Work uploads, use the named beyondseo-2.9.1-skill.zip asset and follow your app's guide. GitHub’s source ZIP is for extracting, not direct skill upload. Windows users can extract the source and follow the local assistant guide without installing Git. The guide includes direct upload steps, a copy-paste GitHub installation request and help for save errors and runtime permissions.

Prefer to let your assistant install it?

Paste this into your assistant:

Install BeyondSEO from https://github.com/beyondtahir/beyondseo in the
assistant I am using. Follow docs/agent-installation.md for this host.
Use the complete skill bundle, register it through this app's supported
skill controls, and confirm it appears in my Skills list.
Set up the native crawler in a permitted execution environment and run
doctor. Report skill registration, HTTP readiness and browser readiness
separately. If a step fails, show the exact error and resolve that step.

Use the step-by-step guide for the upload route or exact CLI command for your app. Saving a skill and preparing its crawler are separate steps.

Run the crawler from a terminal

You need Python 3.10+ and Git. Python 3.12 is recommended. Run these commands in a terminal:

git clone https://github.com/beyondtahir/beyondseo.git
cd beyondseo
python3 scripts/setup.py
python3 scripts/run.py crawl https://example.com --out ../client-runs/example --max-pages 10

Setup creates an isolated environment, installs the local engine and free PDF renderer, downloads Chromium and checks that it launches. The launcher automatically uses that environment, so you do not need to activate it each time.

git clone https://github.com/beyondtahir/beyondseo.git
cd beyondseo
py -3 scripts/setup.py
py -3 scripts/run.py crawl https://example.com --out ../client-runs/example --max-pages 10

.venv/bin/python -m playwright install-deps chromium
python3 scripts/setup.py

python3 scripts/setup.py --http-only
python3 scripts/run.py crawl https://example.com --out ../client-runs/http --mode http

Open ../client-runs/example/report.md for crawl findings and readiness.md for the next questions to review. Check summary.json for limits before interpreting results. A complete strategic audit follows the skill workflow below.

No required crawling-service account. No SEO-data subscription. No API key for the native engine. The CLI makes no language-model calls and consumes no model tokens. When an assistant analyzes evidence or writes copy, its own model usage still applies. Costs and requirements.

Full setup and troubleshooting → · Try the included practice website →

Use it in your assistant

BeyondSEO uses a portable SKILL.md with bundled scripts, references and playbooks. Choose your host in the installation guide.

These are installation routes, not a claim that every host has identical access. Browser, editing and scheduling support depend on the actual environment. Vercel hosting itself does not register or run a skill. Other agents, including Antigravity, need their own supported skill-import and runtime checks before compatibility can be confirmed.

For example, from this checkout, install a personal Claude Code skill:

python3 scripts/install_skill.py --host claude-code --setup

On Windows use py -3 in place of python3. The installer supports --dry-run and safe updates with a backup. Hermes profiles and OpenClaw workspaces have explicit options. Hosted workers can use a separate approved runtime folder. Exact paths, commands and acceptance checks →

Ask for the whole engagement

Use BeyondSEO to audit https://example.com.

We are based in Pakistan and serve clients in India, the UK, Europe
and Gulf countries. Explain where our website is strong, what is missing
and which improvements matter most for our actual services.

Include technical SEO, answer readiness, entity and authority work,
verified backlink evidence, three relevant competitors, useful content
drafts and a 30/60/90-day plan. Show uncertainty and give each task a
clear way to check the result.

A general website audit includes reputation evidence, named competitor comparisons and a practical plan by default. A focused writing or technical question keeps its narrower scope. More questions you can ask →

Why choose BeyondSEO?

BeyondSEO is a strong fit for evidence-based SEO engagements. It makes no unmeasured speed, ranking or accuracy claim against another crawler.

From your website to work you can follow

Start with a domain and a goal. An audit gives you findings and a plan; implementation begins when you ask your agent to act. Monitoring is optional.

flowchart TD
    A["Your website and goal"] --> B["Understand the business and inspect the pages"]
    B --> C["Research comparable competitors and reputation"]
    C --> D["Clear findings and a practical plan"]
    D --> E["Branded report and off-site posting plan"]
    D --> F{"Ask the agent to apply improvements?"}
    F -->|No| G["Keep the audit and next steps"]
    F -->|Yes| H["Confirm scope, access and a baseline"]
    H --> I["Improve the site while protecting the design"]
    I --> J["Check the changes and record the result"]
    J --> K{"Want a private progress dashboard?"}
    K -->|Yes| L["View progress; give instructions in your usual chat"]
    K -->|No| M["Receive progress in your usual chat"]
    L --> N["Review again on request or through an agreed host schedule"]
    M --> N
    N --> B
    classDef brand fill:#991B1B,color:#fff,stroke:#991B1B
    classDef dark fill:#171717,color:#fff,stroke:#171717
    class A,D,J,L brand
    class B,C,E,G,H,I,M,N dark

You control publication and new pages. Off-site recommendations include where, what and when to post; the skill does not automatically submit articles or forum posts. A dashboard displays progress—it does not create an always-on worker.

How our crawler works

flowchart LR
    A[Website and scope] --> B[Robots and sitemaps]
    B --> C[Saved URL queue]
    C --> D[HTTP capture]
    D --> E{Render needed?}
    E -->|Yes| F[Local Chromium]
    E -->|No| G[Page evidence]
    F --> G
    G --> C
    G --> H[SEO findings and readable content]
    H --> I[Strategy, writing and next review]

1. Discover: start from the URL, inspect robots and sitemaps, and collect in-scope links.
2. Read: fetch raw HTML and render JavaScript when automatic mode detects the need, or when browser mode is requested.
3. Extract: collect main text, Markdown, titles, headings, descriptions, canonicals, hreflang, images, links and JSON-LD observations.
4. Explain: retain errors, redirects, access decisions, incomplete rendering and coverage limits alongside findings.
5. Continue: save the queue in SQLite so an unfinished snapshot can resume. Start a fresh folder to measure changes later.

BeautifulSoup parses HTML; Colorama styles terminal feedback; optional Playwright runs local Chromium. The crawling workflow is implemented in this repository. No hosted scraping backend or external agent skill is required.

Automatic mode is a heuristic. Browser mode supports visible-selector waits and bounded scrolling; neither guarantees every interactive state was captured. Robots rules are respected by default. An explicit owner-authorized override is recorded, but it does not bypass authentication, CAPTCHAs or server denials.

Browser behavior → · Architecture and Python interface → · All CLI options →

python3 scripts/run.py scrape https://example.com/article \
  --out ../client-runs/article --mode browser --wait-for-selector article --scroll-steps 5

# Capture a browser viewport image.
python3 scripts/run.py scrape https://example.com --out ../client-runs/visual --screenshot

# Include an observed www alias when it is part of the website.
python3 scripts/run.py crawl https://example.com --allow-host www.example.com \
  --out ../client-runs/site --max-pages 25

# Continue that same snapshot with a larger budget.
python3 scripts/run.py crawl https://example.com --allow-host www.example.com \
  --out ../client-runs/site --max-pages 100 --resume

Our backlink and reputation system

A reputation plan should distinguish a real link from a name in a snippet, a company profile from independent recognition, and an unreadable candidate from verified evidence.

BeyondSEO checks the agent's available browser and search tools, uses permitted native discovery fallbacks, and can import saved search results or supplied URLs/CSVs. Its crawler then inspects the source pages before counting links. Discovery serves both reputation research and business comparisons; it never supplies a complete backlink index.

python3 scripts/run.py discover --target https://example.com \
  --query '"Example" -site:example.com' --out ../client-runs/discovery

python3 scripts/run.py reputation --sources ../client-runs/discovery/sources.csv --target https://example.com \
  --brand "Example" --max-sources 50 --out ../client-runs/reputation

A score you can explain

The BeyondSEO Reputation Score uses supported source-quality points and explicit evidence factors. Repeated publishers are grouped; owned or affiliated sources cannot establish independent editorial proof. Every review can retain its rationale and source.

• Low confidence: provisional headline and adjusted range stay below 50/100.
• No conclusive checks: withhold the headline.
• Client or competitor: the same criteria apply; uneven evidence cannot support a numerical winner.
• Coverage: count actual inspected responses and source pages; a requested five-page plan is not five completed pages or a whole-web backlink total.

The score is our own evidence measure. It is not a proprietary provider's authority score, a search-engine ranking factor or an AI-citation prediction.

Plain-language scoring guide → · Complete formula and verification workflow →

Find the right places to publish

BeyondSEO turns your website and business goals into a practical publishing plan. Its library includes 206 websites and communities, with article platforms, newsletters, professional networks, answers, communities and resource sites kept distinct.

Ask for 15 or 20 suitable sources. The skill reads your services, audience and useful pages, then explains which destinations fit and what contribution to make at each one.

“Review my website and recommend 15 suitable free posting sources. Tell me what to write, where to link and how to publish. Plan around two pieces per week and draft the first two articles.”

The library includes documented posting guidance for 22 destinations, with dates and primary sources. Other entries remain available for research. The helper filters by topic, eligibility, free-term status and guidance freshness. When fewer than the requested count qualify, the skill researches additional suitable sources and explains any remaining gap.

A publishing opportunity is a prospect. Account access, commercial terms, acceptance and the actual link still need checking. Source-sheet DR values are unverified and do not determine recommendations; BeyondSEO does not invent DA scores or promise ranking gains.

For a local plan, copy the example business profile, save it as ../client-runs/business.json, fill in your actual details and run:

python3 scripts/backlink_sources.py --profile ../client-runs/business.json --limit 15 --out ../client-runs/posting-plan

You receive Markdown, CSV and JSON, including writing briefs, posting steps and a calendar. This helper uses no API keys or model calls. The full skill adds website review, current research, editorial judgment and the requested finished writing through your assistant.

Browse all sources → · Posting guide → · Additional reputation routes →

What a complete audit delivers

BeyondSEO includes a branded PDF and HTML report exporter: the existing product logo, white/black/red palette, a strong cover, linked contents, numbered sections, comparison tables, source notes and an action roadmap. PDF generation runs locally with a free renderer; no online design account or browser session is needed.

python3 scripts/run.py present --input /path/to/client/report-content.json \
  --out /path/to/client/deliverable

The assistant fills the report with inspected evidence and reviewed recommendations. For a direct export of native findings, use present --audit /path/to/client/audit.json. Long content and tables paginate; unknown measurements stay unknown. Report design and content format →

The engine produces crawl evidence and technical reports. The complete skill uses that evidence with market context, specialist methods and any supplied performance data. It does not invent traffic, search volume, rankings or AI citations when those measurements are unavailable.

Audit delivery standard → · Complete plan template →

client-runs/example/
├── report.md          Crawl findings
├── readiness.md       Search and answer-readiness review
├── summary.json       Version, counts, settings and coverage
├── access.json        Requests, restrictions and stop reasons
├── documents.jsonl    Readable content and its representation
├── content/           Page Markdown and text
├── pages.jsonl        Detailed raw/rendered observations
├── pages.csv          Page inventory
├── links.csv          Observed links and checked destinations
├── issues.json        Finding candidates and actions
├── html/              Captured raw and rendered HTML
├── screenshots/       Optional viewport images
└── crawl.sqlite3      Saved URL queue and results

Where you can use it

Agencies and consultants: organize audits, source reviews, content briefs and client plans around one repeatable workflow.

Founders and in-house teams: understand what the website communicates, what prospects still need answered and which changes to make first.

Developers: inspect raw/rendered differences, metadata, sitemap coverage, access behavior and broken journeys using saved evidence.

Content and reputation teams: draft useful answers, strengthen entity consistency, build credible proof and review relevant third-party opportunities.

Researchers and educators: inspect the source, practice with local fixtures and learn where crawl evidence ends and interpretation begins.

Use it on local hardware or a suitable remote environment with Python, permitted network access and optional Chromium. Choose the appropriate assistant setup and check the engine in the environment where it will run.

Keep improving

Compare fresh snapshots or run a bounded watch review. For compatible websites, stage a single local/SFTP/FTPS text-file change, inspect the diff, apply the reviewed plan within your authorization and retain a backup for rollback.

The watch command collects evidence. The skill uses it to recommend subsequent work. An ongoing schedule needs the host's scheduler; CMS/database edits and build deployments need their own suitable workflow.

Review loops, hosting setup and guarded edits →

Project status

BeyondSEO 2.7.0 is available under the MIT license and remains in beta. Python 3.10 or newer is required; local Chromium enables JavaScript rendering. Use scripts/run.py doctor to check your environment before starting an engagement.

The engine reports access restrictions and incomplete observations. Actual rankings, search-engine indexing, AI citations and business outcomes require their own evidence. Share reproducible issues and useful improvements through the repository's contribution process.

Automated regression tests cover crawling, rendering, discovery fallbacks, evidence handling, reputation assessment and installation behavior. Public test fixtures are fictional. Test summaries describe what passed and any limits; client websites, personal information, private reports and live-test captures are kept outside the repository. The test-workflow badge shows published CI results, not a guarantee that every assistant environment has been tested.

Release notes → · Development guide → · Contribute →

Documentation and support

Documentation index · Changelog · Report a bug · Request a feature · Contributing · Security

About the creator

BeyondSEO is created and maintained by Muhammad Tahir Ashraf, known as Beyond Tahir.

Based in Pakistan, Tahir works across AI consulting, development and practical training. Through Beyond Tahir and Beyond Tahir Academy, he helps people and organizations understand AI and put it to work. Learn more about his work at beyondtahir.com.

BeyondSEO brings that practical approach to search: inspect the real website, make the evidence understandable, create useful improvements and review the result. Its purpose is to help people carry out a complete SEO engagement with clarity and control.

Stay connected

Website · Instagram · YouTube · LinkedIn · Academy

Copyright © 2026 Muhammad Tahir Ashraf — Beyond Tahir. Released under the MIT license. You may use, modify and redistribute the project under its terms. Keep the copyright and license notice. Dependency notices are in THIRD_PARTY_NOTICES.md.