{"id":51750968,"url":"https://github.com/shalintripathi/organic-os","last_synced_at":"2026-07-25T02:00:30.826Z","repository":{"id":372071166,"uuid":"1305019427","full_name":"shalintripathi/organic-os","owner":"shalintripathi","description":"Run an always-on SEO/AEO growth loop on your own site with Claude: pulls GA4 and Search Console signals, proposes fixes with the reasoning attached, applies approved changes to WordPress, verifies they landed, and learns from outcomes. Every write is human-approved. MIT, no telemetry, no scraping.","archived":false,"fork":false,"pushed_at":"2026-07-23T18:34:50.000Z","size":649,"stargazers_count":3,"open_issues_count":6,"forks_count":6,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-07-24T01:12:57.685Z","etag":null,"topics":["aeo","agent-skills","ai-agents","ai-search","ai-seo","answer-engine-optimization","claude","claude-code","claude-code-plugin","claude-plugin","claude-skills","content-marketing","generative-engine-optimization","geo","llm","marketing-automation","seo","seo-automation","seo-tools","wordpress"],"latest_commit_sha":null,"homepage":"https://organicos.shivaatripathi.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shalintripathi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":"THREAT-MODEL.md","audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-18T15:36:02.000Z","updated_at":"2026-07-23T18:37:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shalintripathi/organic-os","commit_stats":null,"previous_names":["shalintripathi/organic-os"],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/shalintripathi/organic-os","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shalintripathi%2Forganic-os","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shalintripathi%2Forganic-os/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shalintripathi%2Forganic-os/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shalintripathi%2Forganic-os/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shalintripathi","download_url":"https://codeload.github.com/shalintripathi/organic-os/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shalintripathi%2Forganic-os/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35862474,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-25T02:00:06.922Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aeo","agent-skills","ai-agents","ai-search","ai-seo","answer-engine-optimization","claude","claude-code","claude-code-plugin","claude-plugin","claude-skills","content-marketing","generative-engine-optimization","geo","llm","marketing-automation","seo","seo-automation","seo-tools","wordpress"],"created_at":"2026-07-19T01:00:30.571Z","updated_at":"2026-07-25T02:00:30.804Z","avatar_url":"https://github.com/shalintripathi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# organic-os\n\nAn agentic organic-growth operating system for any website, as a single\nClaude plugin. The loop is the product.\n\n![License](https://img.shields.io/badge/license-MIT-blue.svg)\n![Tests](https://img.shields.io/badge/tests-235%20passing-brightgreen.svg)\n![Version](https://img.shields.io/badge/version-0.3.0-blue.svg)\n![Works with](https://img.shields.io/badge/works%20with-Claude%20Code%20%2B%20Cowork-6f42c1.svg)\n\n## The loop\n\n```mermaid\nflowchart LR\n    Observe[\"Observe\u003cbr/\u003eGA4, GSC, Ads,\u003cbr/\u003ecitations, competitors\"] --\u003e Decide[\"Decide\u003cbr/\u003esignals + proposals\"]\n    Decide --\u003e Approve{\"Approve\u003cbr/\u003ehuman gate\"}\n    Approve --\u003e|approved| Apply[\"Apply\u003cbr/\u003eWordPress writes\"]\n    Approve --\u003e|rejected| Learn[\"Learn\u003cbr/\u003eskillbook entry\"]\n    Apply --\u003e Verify[\"Verify\u003cbr/\u003echange took effect\"]\n    Verify --\u003e Measure[\"Measure\u003cbr/\u003eoutcome vs shipped\"]\n    Measure --\u003e Learn\n    Learn -.-\u003e Observe\n```\n\nObserve a site's search and AI-answer-engine performance, decide what is\nworth proposing, wait for a human decision at the approve gate, apply\napproved changes to WordPress, verify the write actually took effect,\nmeasure the outcome against what shipped, and write what was learned back\ninto the site's skillbook - which feeds the next observe pass.\n\n## Table of contents\n\n- [Why this exists](#why-this-exists)\n- [What you get](#what-you-get)\n- [Install](#install)\n- [Quickstart by persona](#quickstart-by-persona)\n- [Human gates and your data](#human-gates-and-your-data)\n- [How it compares](#how-it-compares)\n- [Routines](#routines)\n- [Evidence honesty](#evidence-honesty)\n- [FAQ](#faq)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n- [Credits and prior art](#credits-and-prior-art)\n- [License](#license)\n\n## Why this exists\n\nPoint-in-time audit tools already exist and are good - [claude-seo](https://github.com/AgriciDaniel/claude-seo)\n(11.6k+ stars) runs a thorough technical/content/schema/GEO audit against a\nsite in one pass, and organic-os's own onsite audit borrows from its\nsignal-quality bar directly (credited below). What none of the point-in-time\ntools do is run every day and remember what happened last time. organic-os\nis the layer underneath that: daily signals, gated execution on your own\nWordPress site, outcome measurement against what you actually shipped, and\na skillbook your site earns entry by entry as changes get confirmed to work\nor not. Point-in-time auditors tell you what is wrong today; organic-os\nruns the loop that fixes, verifies, and remembers. The same gap shows up\none level up the stack: commercial AI-visibility tools monitor where you\nappear in AI answers and leave execution on your desk\n([source](https://discoveredlabs.com/blog/profound-vs-peec-vs-otterly-which-ai-visibility-platform-should-you-buy));\norganic-os closes that loop with gated execution instead of another\ndashboard.\n\n## What you get\n\nThree bounded modules, one install:\n\n| Module | Does |\n|---|---|\n| **head-of-organic** | Observes (GA4, GSC, Google Ads keyword intel with hub-and-spoke topic clustering, AI-citation and AI-referral tracking, competitor content, brand-mention gaps, entity consistency, striking-distance/cannibalization/decay queries, on-page drift) and decides: emits signals and work items with falsifiable reasoning behind each one |\n| **onsite-optimizer** | Audits any public page with no credentials and maps the site's internal-link graph; with a WordPress connection, applies approved on-page fixes and publishes approved drafts, always verified and rollback-capable |\n| **content-engine** | Turns an approved brief (explainer or comparison) into a publish-ready draft - research, brand-voice compliance, SEO/authority pass, editorial QA, a human-review-necessity score for the approver - with an optional featured-image step |\n\nVerified inventory (2026-07-19): **21 skills, 21 slash commands, 14\nspecialist agents, 235 passing tests.**\n\n```mermaid\nflowchart TB\n    Brain[\"site repo (the brain)\u003cbr/\u003eprofile, signals, skillbook,\u003cbr/\u003ebriefs, approvals, ADRs\"]\n    Core[\"lib/core\u003cbr/\u003ethe only reader/writer\"]\n    HOO[\"head-of-organic\u003cbr/\u003eobserve + decide\"]\n    Onsite[\"onsite-optimizer\u003cbr/\u003eaudit + gated WP writes\"]\n    CE[\"content-engine\u003cbr/\u003ebrief in, draft out\"]\n    Routines[\"routines\u003cbr/\u003eany runtime\"]\n\n    Core --\u003e Brain\n    HOO --\u003e Core\n    Onsite --\u003e Core\n    CE --\u003e Core\n    Routines --\u003e Core\n```\n\nModules talk only through the site repo's file contracts, enforced by a\n`lib/core` layer that owns every read and write - a change to one module\nnever breaks another, and each module is fully usable on its own:\nhead-of-organic without WordPress is still an analytics/strategy tool,\ncontent-engine without head-of-organic accepts manually written briefs,\nonsite-optimizer without the others is a standalone on-page audit/fix tool.\n\n## Install\n\n```\n/plugin marketplace add shalintripathi/organic-os\n/plugin install organic-os@organic-os\n```\n\nWorks identically on Claude Code CLI and Claude Cowork - there is nothing\nto host. The plugin is skills, agents, slash commands, and plain scripts\ninvoked over Bash; no server process, no stdio MCP server, no database.\n\nPrerequisite: Python 3.9+ with PyYAML (`python3 -m pip install --user\npyyaml`). Nothing to host.\n\n### Install, step by step\n\n1. Add the marketplace.\n\n   ![Terminal: adding the organic-os marketplace](docs/images/install-1-marketplace.svg)\n\n2. Install the plugin.\n\n   ![Terminal: installing the organic-os plugin](docs/images/install-2-install.svg)\n\n3. First run: `/organic-os:start` walks you through everything else -\n   health check, then quick-start or full setup.\n\n   ![Terminal: running the organic-os guided start](docs/images/install-3-start.svg)\n\nCowork users: the same two `/plugin` commands work in the chat input, no\nCLI needed.\n\n## Quickstart by persona\n\n**Zero credentials: audit any site in 10 minutes.** Run `/organic-os:setup`\n- it asks for your URL first, audits the site itself (brand voice, audience,\nkeywords, competitors, geos proposed from the actual copy), and presents\nthe result as a table to approve; answer the rest with minimal/analysis-only\nanswers (skip WordPress, skip Google Ads, leave connectors unconfigured).\nRun\n`/organic-os:onsite-audit https://yoursite.com` - a read-only on-page audit\nagainst a live URL, no login required. Read the report it writes under\n`runs/` in the brain repo it scaffolded. Full walkthrough:\n`plugin/docs/getting-started.md`.\n\n**WordPress owner: gated writes to your own site.** Work through\n`plugin/docs/credentials/wordpress.md` to create a dedicated Editor user and an\nApplication Password, then run `/organic-os:setup` with that connection\nfilled in. Run `/organic-os:onsite-audit`, then `/organic-os:propose` to\nturn findings into fix proposals, approve the ones you want in\n`approvals/queue.md`, and run `/organic-os:apply` - every write is verified\nagainst the live page after it lands. Full walkthrough:\n`plugin/docs/getting-started.md`.\n\n**Analytics operator, no WordPress.** Connect the GSC and GA4 connectors (or\nany GSC/GA4 MCP server already in your session) at setup, skip WordPress\nentirely. Run `/organic-os:daily` and `/organic-os:weekly` - manually at\nfirst, on a schedule once you trust what they surface (see Routines below).\nWatch `signals/` for the raw observations and `approvals/queue.md` for\nanything that crossed a threshold worth a human decision. Full walkthrough:\n`plugin/docs/getting-started.md`.\n\n## Human gates and your data\n\nMutation is gated in code, not by convention. `core.contracts.require_approved`\nchecks a proposal's current status before every WordPress write;\n`core.contracts.require_approval_lineage` checks that an `approved` decision\nexists in an item's history before a later stage (like publishing a drafted\nbrief) is allowed to run. A hand-edited `status: approved` with no matching\n`approvals:` entry still fails the gate - every approval is recorded with\nwho decided, when, and through which channel. Approvals also expire: after\n30 days (configurable per site via `approvals: {ttl_days: n}`) both gates\nblock until you re-confirm - the item keeps its status, and one `approve`\ncommand refreshes the clock. Expiry applies to every channel because it\nlives in the contract layer, not in any channel adapter: in-session,\nTelegram, and pr-merge approvals all age identically. Verify the gate\nyourself:\n`./scripts/verify-gates.sh` red-teams these functions against a throwaway\nbrain repo, no real site touched. Or try everything risk-free on your real\nsite: set `onsite: {dry_run: true}` in `site-profile.yaml` and apply runs\nthe whole gated flow - approval check included - while writing nothing,\nrecording instead every change it would have made. There is no telemetry, no\nSERP or autocomplete scraping (see ADR-0006), and credentials never live in\nany repo - only env-file references do. Your brain repo is yours: it lives\nwherever you put it, private by default, and organic-os never pushes it\nanywhere you did not configure. Full detail: `SECURITY.md` and\n[CONTRIBUTING.md's data boundary](CONTRIBUTING.md#the-data-boundary-hard-rule).\n\n## How it compares\n\nThese are complements, not rivals - organic-os credits and interoperates\nwith the tools below rather than replacing them.\n\n| | Runs on a schedule | Remembers outcomes | Writes to your site (gated) | Self-hosted / no accounts |\n|---|---|---|---|---|\n| [claude-seo](https://github.com/AgriciDaniel/claude-seo) - the strongest audit suite in this space | No, point-in-time | No | No, audit only | Yes |\n| [seranking/seo-skills](https://github.com/seranking/seo-skills) | No, manual invocation | No | No, deliverables only | No, vendor MCP + account |\n| [open-seo](https://github.com/every-app/open-seo) | Partially, hosted dashboard refresh | Partially, historical dashboard data | No | No, hosted dashboard |\n| **organic-os** | Yes, daily/weekly/monthly | Yes, skillbook | Yes, gated and verified | Yes |\n\nA fourth class worth naming respectfully: monitoring-only AI-visibility\nplatforms (Profound, Peec, Otterly, and similar) measure where you appear\nin AI answers but stop there - no scheduled execution loop, no gated\nwrites back to your site.\n\n## Routines\n\nCadences (daily signal pull, weekly reflection, monthly deep audit) are\ndeclared in the site profile; the runtime that executes them is a separate\nchoice. Four options: claude.ai scheduled tasks (zero setup, runs on your\nsubscription usage), a local OS schedule (your own machine, has to be\non at the scheduled time), GitHub Actions CI (an API key, billed per token,\nseparate from subscription usage), or fully manual (run the commands\nyourself whenever you want). Full comparison and setup steps for each:\n`plugin/docs/routines.md`.\n\n## Evidence honesty\n\nEvery AEO/GEO tactic organic-os recommends is labeled by how strong the\nevidence behind it actually is, and it says so when a popular tactic is\nweakly supported - schema markup shows no measured lift on AI citations in\ncontrolled testing (still shipped, because it holds up independently for\nGoogle rich results), and `llms.txt` sees close to zero AI-bot traffic in\nthe largest study run on it to date (shipped only as an optional, low-cost\nhedge). Full ranked table with sources: `plugin/docs/evidence.md`.\n\n## FAQ\n\n**Will it change my site without asking?**\nNo. Every write is gated on a recorded approval, checked in code by\n`core.contracts.require_approved` / `require_approval_lineage`, not by\nconvention - see [Human gates and your data](#human-gates-and-your-data).\n\n**Do I need WordPress?**\nNo. `onsite-audit` runs credential-free against any public URL,\nhead-of-organic's observe-and-decide loop runs on GA4/GSC connectors alone,\nand content-engine drafts briefs without ever publishing them. WordPress\nonly turns on the gated apply/publish steps.\n\n**What does a routine run cost?**\nDepends on the runtime: claude.ai scheduled tasks and a local schedule run\non your existing Claude subscription usage, no separate bill. CI (GitHub\nActions) is billed per token via your own Anthropic API key, separate from\nsubscription usage. Full comparison: `plugin/docs/routines.md`.\n\n**Can I bring my own SERP/backlink data?**\nYes. organic-os ships no scraper by design (ADR-0006, `docs/adr/0006-no-scraping.md`).\nDataForSEO and similar BYO adapters are documented paths for keyword, SERP,\nand backlink data beyond Google Ads and GSC, connected with your own\ncredentials. organic-os never scrapes on its own.\n\n**What happens if I run setup again?**\nThe very first run is audit-first: give it a URL and it fetches the\nhomepage and sitemap, reads a few representative pages, and proposes\nbrand voice, audience, keywords, competitors, and geos for you to accept,\nedit, or override, asking directly only for what it genuinely can't infer\n(connectors, WordPress, approval channel, runtime). Run\n`/organic-os:start` any time you are not sure what to do next - it\nhealth-checks the environment and routes you to the right place, including\nback into setup. `/organic-os:setup` itself detects your registered sites\nand asks update, add,\nswitch, or status. Update mode only rewrites the `site-profile.yaml`\nsections you pick and never touches `signals/`, `decisions/`,\n`reflections/`, or existing skillbook entries - config is editable, memory\nis not. Add mode onboards a second site into the sites registry\n(`~/.config/organic-os/sites.yaml`) with its own brain path, without\ntouching the first site.\n\n**How do I remove it?**\n`/organic-os:reset` walks through every piece - scheduled routines, the\nregistry entry, the brain repo, the WordPress Application Password, a\nTelegram bot token, the env file - and only touches the local registry or\nenv file with explicit confirmation. Uninstalling the plugin itself never\ndeletes your brain: it is an ordinary git repo or folder that lives outside\nthe plugin's install location.\n\n**What happens when I update - do I lose anything?**\nNo. `/plugin update organic-os` replaces plugin code only; your brain\nrepo(s), `~/.config/organic-os/`, and your WordPress site are outside the\nplugin directory and untouched by design. A brain-layout change ships a\nmigration and a compatibility check blocks routines with a clear message\ninstead of silent corruption. Full policy: `plugin/docs/updating.md`.\n\n**Why does nothing prompt me to connect Google Analytics?**\norganic-os bundles no MCP servers and cannot trigger an OAuth prompt\nitself. `/organic-os:setup`'s connector wizard probes what you have\nalready connected, runs one live verification query (a GSC site list, a\nGA4 7-day sessions pull) before recording anything as `verified`, and\nwalks you through connecting anything missing for your surface, with the\noption to wait and re-probe or decline with an honest note on what\ndegrades. GSC/GA4 absence gets called out explicitly, since `hoo-daily`\nlogs no-data signals without one of them connected. Setup ends on a\npostflight scorecard that tests, not just records, what got configured -\nit never claims success on its own. Full model: `plugin/docs/\nconnectors.md`.\n\n## Roadmap\n\nThemes, not promises - see `ROADMAP.md` for what is planned across v0.2,\nv0.3, and v1.0.\n\n## Contributing\n\nCode, tests, and CMS/channel adapters are welcome; business data is not -\nsee `CONTRIBUTING.md` for the full guide and the data boundary CI enforces.\n\n## Credits and prior art\n\n- [AgriciDaniel/claude-seo](https://github.com/AgriciDaniel/claude-seo) - the point-in-time SEO audit this project's signal-quality bar borrows from directly. `/organic-os:import-audit` now imports its reports as gated proposals: they audit, we operate.\n- [seranking/seo-skills](https://github.com/seranking/seo-skills) - Claude Agent Skills for the SE Ranking MCP server; a reference for how to shape SEO data into finished deliverables as skills.\n- [WordPress/mcp-adapter](https://github.com/WordPress/mcp-adapter) - the official WordPress MCP bridge; not load-bearing in v1 (onsite-optimizer writes over plain REST) but tracked for its 1.0.\n- [Automattic/mcp-wordpress-remote](https://github.com/Automattic/mcp-wordpress-remote) - a reference implementation for remote WordPress MCP auth flows.\n- [Devora-AS/rank-math-api-manager](https://github.com/Devora-AS/rank-math-api-manager) - exposes RankMath's SEO meta fields over the WordPress REST API; the alternative to organic-os's own bundled bridge mu-plugin.\n- [AminForou/mcp-gsc](https://github.com/AminForou/mcp-gsc) - a Search Console MCP server; one of the paths `plugin/docs/credentials/gsc-ga4.md` documents.\n- [DataForSEO MCP server](https://github.com/dataforseo/mcp-server-typescript) - a documented BYO adapter for paid keyword/SERP data beyond Google Ads.\n- [firecrawl/llmstxt-generator](https://github.com/firecrawl/llmstxt-generator) - a reference implementation for generating `llms.txt`, which organic-os ships as an optional hedge per `plugin/docs/evidence.md`.\n- [oneglanse](https://github.com/aryamantodkar/oneglanse) - an open-source GEO/AI-visibility tracker; a reference for how `hoo-citation-tracker` measures share of voice across AI engines.\n- [Aggarwal et al., \"GEO: Generative Engine Optimization,\" KDD 2024](https://arxiv.org/abs/2311.09735) - the controlled-experiment basis for organic-os's strong-tier AEO/GEO tactics.\n- [Shinn et al., \"Reflexion: Language Agents with Verbal Reinforcement Learning,\" NeurIPS 2023](https://arxiv.org/abs/2303.11366) - the memory-via-reflection pattern behind the weekly reflector.\n- [Wang et al., \"Voyager: An Open-Ended Embodied Agent with Large Language Models,\" 2023](https://arxiv.org/abs/2305.16291) - the ever-growing skill-library pattern behind the skillbook.\n- [Suzgun et al., \"Dynamic Cheatsheet: Test-Time Learning with Adaptive Memory,\" 2025](https://arxiv.org/abs/2504.07952) - the adaptive, curated-memory-at-inference-time pattern the skillbook follows.\n- [Zhang et al., \"Agentic Context Engineering: Evolving Contexts for Self-Improving Language Models,\" 2025](https://arxiv.org/abs/2510.04618) - the generator/reflector/curator division of labor and the brevity-bias/context-collapse failure modes the site-repo contract is built to avoid.\n- [MADR - Markdown Architectural Decision Records](https://adr.github.io/madr/) - the ADR template format used throughout `docs/adr/` and every site repo's `decisions/`.\n\n## License\n\nMIT. See `LICENSE`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshalintripathi%2Forganic-os","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshalintripathi%2Forganic-os","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshalintripathi%2Forganic-os/lists"}