From a6d7ecdaccd415681155cfad08c1bc4233bb2f61 Mon Sep 17 00:00:00 2001 From: turner Date: Sat, 7 Nov 2026 13:37:28 -0500 Subject: [PATCH] Onboarding: marketplace only, granular Claude steps sent word for word MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Drop every hand-added server URL route (Claude custom connector, ChatGPT custom MCP server, other MCP clients). ADR 0001 records why: only marketplace installs get updates. - Claude: eight arrow-and-check steps (Customize → Plugins, new claude.ai/customize/plugins address, add-then-Connect, Sync automatically, per-chat + → Connectors switch, GitHub Issues when stuck). Canonical in README.md, copied verbatim into INSTALL-PROMPT.md, which now tells the assistant to send it word for word with no preamble, options or closing checklist. - scripts/check-install-steps.sh + CI fails if the two copies drift. - ChatGPT: install through Codex in the ChatGPT desktop app. - install.html, maintaining.md and the plugin README follow; add GLOSSARY.md. - Worker /plugins redirect points at claude.ai/customize/plugins (needs wrangler deploy). Co-Authored-By: Claude Opus 5.5 --- .github/workflows/check.yml | 11 +++ GLOSSARY.md | 28 +++++++ INSTALL-PROMPT.md | 79 +++++++++++++------ README.md | 52 ++++++++---- .../adr/0001-marketplace-only-distribution.md | 8 ++ docs/from-mcp-url-to-plugin.md | 4 +- docs/install.html | 77 ++++++++++-------- docs/maintaining.md | 12 ++- install-worker/README.md | 2 +- install-worker/src/index.js | 2 +- plugins/geenee/README.md | 2 +- scripts/check-install-steps.sh | 14 ++++ 12 files changed, 207 insertions(+), 84 deletions(-) create mode 100644 .github/workflows/check.yml create mode 100644 GLOSSARY.md create mode 100644 docs/adr/0001-marketplace-only-distribution.md create mode 100755 scripts/check-install-steps.sh diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml new file mode 100644 index 0000000..73bd3d6 --- /dev/null +++ b/.github/workflows/check.yml @@ -0,0 +1,11 @@ +name: check +on: + pull_request: + push: + branches: [main] +jobs: + install-steps: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: scripts/check-install-steps.sh diff --git a/GLOSSARY.md b/GLOSSARY.md new file mode 100644 index 0000000..2a47bc4 --- /dev/null +++ b/GLOSSARY.md @@ -0,0 +1,28 @@ +# Aiden Lab plugins + +How Aiden Lab's tools, starting with Geenee, reach people's AI assistants. + +## Language + +**Marketplace**: +The `aidenlab/plugins` GitHub repository, added to an app once by name, that lists Aiden Lab's plugins and carries their updates. +_Avoid_: catalog, store, repo (when talking to users) + +**Plugin**: +An installable package from the Marketplace that bundles a Connector and a skill. Geenee is one. +_Avoid_: app, extension, integration + +**Connector**: +An app's saved connection to the Geenee server, which supplies the tools. +_Avoid_: MCP server (when talking to users), integration + +**Marketplace install**: +The only supported way to set up Geenee: add the Marketplace, then install the Plugin from it. See ADR 0001. +_Avoid_: Option A, the plugin route + +**Custom connector**: +A Connector added by pasting the server address by hand. Not offered to users; it gets no updates. +_Avoid_: Option B, manual install, URL install + +**Connect step**: +The click in Claude that switches on a Plugin's Connector after the Plugin is added. Claude never does it automatically. diff --git a/INSTALL-PROMPT.md b/INSTALL-PROMPT.md index 4b615fb..ab87fda 100644 --- a/INSTALL-PROMPT.md +++ b/INSTALL-PROMPT.md @@ -2,13 +2,14 @@ You are reading this because a user pasted a one-line request to set up Geenee. Follow it in the application you are running in. Talk to the user as someone comfortable with chat but unfamiliar with plugins, terminals and MCP: plain language, short explanations, one action at a time when their participation is needed. Perform every step you can yourself; never ask them to type a terminal command you could run. -Start by telling them, in one or two sentences: Geenee lets them drive three genome viewers by typing ordinary requests: the IGV genome browser, the Juicebox Hi-C contact-map viewer and the Spacewalk 3D chromatin viewer, together on one page. That page opens in a browser tab, which must stay open while you work together. +Start by telling them, in one or two sentences: Geenee lets them drive three genome viewers by typing ordinary requests: the IGV genome browser, the Juicebox Hi-C contact-map viewer and the Spacewalk 3D chromatin viewer, together on one page. That page opens in a browser tab, which must stay open while you work together. (On the Claude account path below, fold this into the single sentence before the steps.) ## Facts - Marketplace: `aidenlab/plugins` on GitHub (marketplace name `aidenlab`). Plugin: `geenee`, so `geenee@aidenlab`. Display name **Geenee**. - MCP server: `https://geenee.3dg.io/mcp`, Streamable HTTP, no authentication. It sends workflow instructions to every client on connect; the plugin adds a fuller skill on top. The server name is **Geenee**. - A server connection supplies tools (`open_geenee`, `igv_*`, `juicebox_*`, `spacewalk_*`). The plugin supplies the skill. Both is best; tools alone are enough to work. +- **Marketplace only.** Geenee is installed only from the `aidenlab` marketplace, in every app, because only a marketplace install receives updates. Never offer, suggest or fall back to adding the server address by hand (a "custom connector" or "custom MCP server"), not even when a step fails. When a step fails, send the user to https://github.com/aidenlab/plugins/issues. - Reuse anything already installed or connected. Never add a second connection to the same server. - Retired: an older plugin with the id `juicebot` (shown as JuiceBot or Geenee), and connections to `juicebot-mcp.3dg.io` or `geenee-dev.3dg.io`. If you find one, help the user remove or turn it off so two tool sets do not both appear. - Distinguish three states and report only what you have verified: **installed** (plugin present and enabled), **server connected** (Geenee tools are callable in this conversation), **viewer working** (the page answered a command). @@ -19,32 +20,58 @@ Decide from your own environment; ask the user only if you cannot tell. - A shell with the `claude` CLI, or `/plugin` slash commands → **Claude Code**. - Any other Claude surface: claude.ai on the web, the Claude desktop app's Chat tab, or a Cowork task → **Claude (account path)**. -- A shell with the `codex` CLI, or the Codex desktop app → **Codex**. -- ChatGPT → **ChatGPT**. +- A shell with the `codex` CLI, the Codex desktop app, or Codex inside the ChatGPT desktop app → **Codex**. +- Plain ChatGPT chat (no Codex, no shell) → **ChatGPT**. ## Claude (claude.ai web, desktop Chat, Cowork) -Plugins and marketplaces are added to the user's **account**, once, and then follow them to web chat, the desktop app, Cowork and Claude Code, with updates. There is no command for this; it is a few clicks on one settings page. Do not build or send plugin files. +Plugins and marketplaces are added to the user's **account**, once, and then follow them to web chat, the desktop app, Cowork and Claude Code, with updates. There is no command for this; the user clicks through their settings. Do not build or send plugin files, and do not open the settings page yourself. -**Setup has two parts and the user must do both: add the plugin, then click Connect.** Adding the plugin turns on its skill but not its server: Claude never connects a plugin's server automatically, and until the user clicks **Connect** the plugin page looks installed and enabled while Geenee does nothing. Users do not find this step on their own. Every message that tells the user how to add the plugin must include the Connect step in the same list, and you must not call setup done until the user has confirmed it. +**Setup has two parts and the user must do both: add the plugin, then connect it.** Claude never connects a plugin's server automatically; until the user clicks **Connect**, Geenee looks installed but does nothing. Do not call setup done until the user has confirmed it. 1. If Geenee tools are already callable here, skip to verification. -2. If you have a tool that lists the plugins on the user's account, call it for `geenee` first. If the plugin is already there, skip to step 4. Otherwise, if you have a plugin-catalog search tool, search it for `geenee`; if listed, render the install card and tell the user to click **Install**, then go to step 4. -3. **One message, all the clicks, Connect included.** Do not open the settings page yourself; send exactly this and wait for the user to say they are done: +2. If you have a tool that lists the plugins on the user's account, call it for `geenee` (and `juicebot`) first. If Geenee is already there, skip to **Confirm the Connect click** below. Do not report these checks to the user, except to ask them to remove a retired `juicebot` plugin or JuiceBot connector you actually found. +3. **Send the steps below word for word.** Your whole message is: one sentence (what Geenee is, and that these steps add it in their Claude settings), then the block between the markers, exactly as written, as Markdown, without the marker comments. Do not shorten, reword, reorder, summarize or merge the steps. Do not add options, alternatives or fallbacks. Do not add a checklist after it. Then wait for the user to say they are done. - > Open **https://claude.ai/new#settings/customize-plugins** in a separate tab or window (Ctrl/Cmd-click, or right-click → Open in new tab) so this chat stays put. In the app the same page is **Customize → Plugins**; in Cowork, open the Cowork tab first. Then: - > - > 1. If the `aidenlab` marketplace is not there yet: **Add → Add marketplace → Add from a repository**, enter `aidenlab/plugins`, confirm. - > 2. In the **Discover** tab, find **Geenee** and click **Add**. - > 3. **Don't stop there.** Open Geenee's **Connectors** tab: it says **Not added**. Click **Connect**. No login is needed. Without this click Geenee looks installed but cannot do anything. - > - > Tell me when the Connectors tab shows Geenee as connected. + +You need a paid Claude plan (Pro, Max, Team or Enterprise). There are two parts, adding Geenee and then connecting it. Do both. -4. **Confirm the Connect click.** When the user replies, if you have a tool that lists the plugins on their account, call it filtered to `geenee`. Then, unless the user has already said Geenee shows as connected, ask once, as one short message: +1. Click **Customize** in the left sidebar → **Plugins** - > Last check: on Geenee's **Connectors** tab, does it still say **Not added**? If so, click **Connect** there. If there is no Connect button, use **Settings → Connectors → Add custom connector** instead, name `Geenee`, URL `https://geenee.3dg.io/mcp`, no authentication. + *In a web browser you can instead go straight to [claude.ai/customize/plugins](https://claude.ai/customize/plugins). In Cowork, click the **Cowork** tab first.* - If the account also has the retired `juicebot` plugin or a JuiceBot connector, add one sentence asking them to remove it on the same page. On a Team or Enterprise plan, mention once that an admin can add the connector for the whole organization. + ✓ You see a page called **Plugins** with a **Discover** tab. + +2. Click **Add** → **Add marketplace** → **Add from a repository** + + *Already see **aidenlab** in your list of marketplaces? Skip to step 5. No **Add marketplace**? Your organization has turned it off: ask your Claude admin to allow user-added marketplaces, then come back to this step.* + +3. Type `aidenlab/plugins` → click the button that adds it + + ✓ **aidenlab** now appears in your list of marketplaces. + +4. If you see **Sync automatically** next to **aidenlab**, turn it on. This is how Geenee's updates reach you. + +5. Click the **Discover** tab → find **Geenee** → click **Add** + +6. Click **Geenee** → the **Connectors** tab + + ✓ It says **Not added**. That's expected. + +7. Click **Add** if you see it → then click **Connect**. No login is needed. + + ✓ It now says **Connected**. *Skip this step and Geenee looks installed but does nothing.* + +8. Start a new chat → click **+** in the message box → **Connectors** → make sure **Geenee** is switched on. + +Stuck at any step? Open an issue at [github.com/aidenlab/plugins/issues](https://github.com/aidenlab/plugins/issues) and attach a screenshot of what you see. + + +4. **Confirm the Connect click.** When the user replies, if you have a tool that lists the plugins on their account, call it filtered to `geenee`. Then, unless the user has already said Geenee shows as **Connected**, ask once, as one short message: + + > Last check: click **Customize** → **Plugins** → **Geenee** → the **Connectors** tab. Does it say **Connected**? If it says **Not added** or **Not connected**, click **Add** if you see it, then **Connect**. + + If it still does not connect, send them to https://github.com/aidenlab/plugins/issues with a screenshot. On a Team or Enterprise plan, add one sentence: an Owner may need to add Geenee's connector for the organization first. 5. Only once the user has confirmed Connect: the tools appear in a new conversation. End as described under "How to end your reply", and in its first line say that both parts are done (plugin added, server connected). Everything added this way also reaches Claude Code the next time it starts signed in with the same account (or after `/login`). @@ -68,14 +95,16 @@ In the Codex CLI and the Codex desktop app (they share `~/.codex`, so an install ## ChatGPT -ChatGPT does not use this marketplace: the user adds Geenee's server address by hand, and then must turn Geenee on in each chat. Both are manual; say so up front so the user knows there are two parts. +Plain ChatGPT chat cannot install Geenee from the marketplace, and the server address is never added by hand (see Facts). Geenee is installed through **Codex inside the ChatGPT desktop app**, which installs it from the marketplace by itself. + +1. If Geenee tools are already available here, skip to verification. +2. Otherwise send one short message, as numbered steps: + 1. Open the **ChatGPT desktop app** → click **Codex**. + 2. Paste this line there: `Set up Geenee for me: fetch https://geenee-install.3dg.io and follow its instructions for the app you are running in.` + 3. Each time Codex asks for permission, click **Approve**. + 4. When it finishes, it gives you a message. Paste that into a new chat. -1. If Geenee tools are already available here, skip to verification. If tools from a JuiceBot server or a `geenee-dev` server are available instead, guide them through step 2 and suggest removing the old server afterwards. -2. Otherwise send one message with every step, numbered: - 1. Open **chatgpt.com/plugins → + → Add custom MCP server**: name `Geenee`, URL the server URL above, authentication **None**. If ChatGPT says custom servers need **Developer mode**, turn it on where it points (Settings), then try again. Explain any confirmation ChatGPT shows in plain words. - 2. **Don't stop there.** Start a new chat and turn Geenee on in it (the **+** / tools menu, or type `@Geenee`). Adding the server does not turn it on in chats. - If an option is missing, explain the account or workspace limitation you can verify and the next step. -3. ChatGPT gets tools and the server's built-in instructions; it does not get the plugin skill. That is fine. Server-side changes (new tools, fixes) reach ChatGPT users automatically; only a change of server address would need them to redo step 2. + If they do not have the desktop app, say it is a free download from OpenAI and stop there. ## How to end your reply when the tools are not callable yet (every application) @@ -89,7 +118,7 @@ Whenever setup is done but the Geenee tools are not available in the current con Open Geenee. In Juicebox, load the ENCODE GM12878 in situ Hi-C map at the HOXA cluster and add the gene track. In IGV, go to HOXA1 and add the GM12878 CTCF ChIP-seq track. ``` -Do not put the message inside a bullet or a paragraph, do not add alternatives after it, and do not restate manual steps the user has already completed. Fallback instructions (another way to install) go *before* this block, and only if a step actually failed. +Do not put the message inside a bullet or a paragraph, do not add alternatives after it, and do not restate manual steps the user has already completed. There is no other way to install: if a step failed, point to https://github.com/aidenlab/plugins/issues *before* this block. Do not end with a checklist of things to verify. ## Verification and first use (every application) diff --git a/README.md b/README.md index 131e768..7487a01 100644 --- a/README.md +++ b/README.md @@ -4,37 +4,55 @@ ## Install -How you install depends on the app. Only Claude Code and Codex can install it for you; the others need a few clicks in settings, because a chat cannot change your account settings. +Geenee installs only from the **aidenlab** marketplace, in every app. That is how it gets updates, which matter while Geenee is young. -### Claude Code or Codex (CLI or desktop app): paste one line +### Claude Code, Codex, or ChatGPT's Codex: paste one line ``` Set up Geenee for me: fetch https://geenee-install.3dg.io and follow its instructions for the app you are running in. ``` -The assistant installs everything itself. Start a new session when it says so. +The assistant does the installing. Each time it asks for permission, click **Approve** (or **Allow**). When it finishes it gives you a message to paste into a new chat or session. -### Claude (web, desktop app, Cowork): two parts, once +In the ChatGPT desktop app, open **Codex** first, then paste the line there. Plain ChatGPT chat cannot install Geenee. -1. Open [claude.ai/new#settings/customize-plugins](https://claude.ai/new#settings/customize-plugins). -2. **Add → Add marketplace → Add from a repository**, enter `aidenlab/plugins`. -3. Find **Geenee**, click **Add**. -4. **Then click Connect.** Open Geenee's **Connectors** tab: it says **Not added** until you click **Connect**. Claude never does this for you, and without it Geenee looks installed but does nothing. -5. Start a new chat. +### Claude (desktop app, claude.ai, Cowork): click through once -You can also paste the one-line prompt above into a Claude chat: it walks you through these same clicks. + +You need a paid Claude plan (Pro, Max, Team or Enterprise). There are two parts, adding Geenee and then connecting it. Do both. -This covers every Claude app on your account, Claude Code included. Paid plans only. +1. Click **Customize** in the left sidebar → **Plugins** -Only if there is no Connect button: **Settings → Connectors → Add custom connector**, name `Geenee`, URL `https://geenee.3dg.io/mcp`, no authentication. This gets no plugin updates, so prefer the plugin. + *In a web browser you can instead go straight to [claude.ai/customize/plugins](https://claude.ai/customize/plugins). In Cowork, click the **Cowork** tab first.* -### ChatGPT: add the server by hand + ✓ You see a page called **Plugins** with a **Discover** tab. -[chatgpt.com/plugins](https://chatgpt.com/plugins) → **+** → **Add custom MCP server**, name `Geenee`, URL `https://geenee.3dg.io/mcp`, authentication **None** (if ChatGPT asks for Developer mode, turn it on in Settings). **Then** start a new chat and turn Geenee on in it from the **+** menu. ChatGPT does not use this marketplace. +2. Click **Add** → **Add marketplace** → **Add from a repository** -### Other MCP apps (Cursor and others) + *Already see **aidenlab** in your list of marketplaces? Skip to step 5. No **Add marketplace**? Your organization has turned it off: ask your Claude admin to allow user-added marketplaces, then come back to this step.* -Point them at `https://geenee.3dg.io/mcp`. +3. Type `aidenlab/plugins` → click the button that adds it + + ✓ **aidenlab** now appears in your list of marketplaces. + +4. If you see **Sync automatically** next to **aidenlab**, turn it on. This is how Geenee's updates reach you. + +5. Click the **Discover** tab → find **Geenee** → click **Add** + +6. Click **Geenee** → the **Connectors** tab + + ✓ It says **Not added**. That's expected. + +7. Click **Add** if you see it → then click **Connect**. No login is needed. + + ✓ It now says **Connected**. *Skip this step and Geenee looks installed but does nothing.* + +8. Start a new chat → click **+** in the message box → **Connectors** → make sure **Geenee** is switched on. + +Stuck at any step? Open an issue at [github.com/aidenlab/plugins/issues](https://github.com/aidenlab/plugins/issues) and attach a screenshot of what you see. + + +This covers every Claude app on your account, Claude Code included. You can also paste the one-line prompt above into a Claude chat: it walks you through these same steps. ## First thing to try @@ -47,7 +65,7 @@ You get a link. Open it in a browser tab and keep it open: the assistant drives ## More - **Have the old `juicebot` plugin?** Remove it, then install Geenee as above. -- **Admins (Claude Team/Enterprise):** add `https://geenee.3dg.io/mcp` as an organization connector and members need no setup. +- **Admins (Claude Team/Enterprise):** an Owner may need to allow user-added marketplaces, and to add Geenee's connector for the organization, before members can complete the steps above. - **Maintainers:** [docs/maintaining.md](docs/maintaining.md). How plugins relate to a plain MCP URL: [docs/from-mcp-url-to-plugin.md](docs/from-mcp-url-to-plugin.md). Server source: [aidenlab/geenee](https://github.com/aidenlab/geenee). License: MIT. diff --git a/docs/adr/0001-marketplace-only-distribution.md b/docs/adr/0001-marketplace-only-distribution.md new file mode 100644 index 0000000..bd5ce06 --- /dev/null +++ b/docs/adr/0001-marketplace-only-distribution.md @@ -0,0 +1,8 @@ +# Geenee is distributed only through the marketplace + +Geenee is installed only by adding the `aidenlab/plugins` marketplace and installing `geenee@aidenlab`, in every app. Onboarding never offers the shorter route of pasting the server address (`https://geenee.3dg.io/mcp`) as a custom connector or custom MCP server, not even as a fallback. Geenee is in early development, and only a marketplace install receives plugin updates (the skill and its instructions) as we ship them. A hand-added address freezes the user on whatever they first got. + +## Consequences + +- When a step fails, the user is sent to GitHub Issues on `aidenlab/plugins`, not to a second install route. +- Claude Team/Enterprise admins may still need to allow user-added marketplaces, or add the plugin's connector for the organization. That is part of the marketplace install, not an alternative to it. diff --git a/docs/from-mcp-url-to-plugin.md b/docs/from-mcp-url-to-plugin.md index 9af2bf6..e71a0d6 100644 --- a/docs/from-mcp-url-to-plugin.md +++ b/docs/from-mcp-url-to-plugin.md @@ -28,8 +28,8 @@ Your understanding is mostly right, but how easy it gets depends on the app: |---|---|---| | **Claude Code** | `claude mcp add --transport http geenee ` | `claude plugin install geenee --marketplace aidenlab/plugins`: server **and** skill in one step, with updates through `/plugin update`. | | **Codex** | `codex mcp add …` | `codex plugin marketplace add aidenlab/plugins` + `codex plugin add geenee@aidenlab` | -| **claude.ai / desktop / Cowork** | Settings → Connectors → Add custom connector → paste URL | Customize → Plugins → Add marketplace `aidenlab/plugins` → Geenee → Add, then Geenee's Connectors tab → **Connect** (claude.ai never connects a plugin's server automatically). **It's still a few clicks**, but they're done once per account and then reach every Claude surface, Claude Code included. | -| **ChatGPT** | Add custom MCP server → paste URL | **The same** for now: ChatGPT still needs the custom MCP server step. | +| **claude.ai / desktop / Cowork** | Settings → Connectors → Add custom connector → paste URL | Customize → Plugins → Add marketplace `aidenlab/plugins` → Geenee → Add, then Geenee's Connectors tab → **Connect** (step by step in the [README](../README.md)) (claude.ai never connects a plugin's server automatically). **It's still a few clicks**, but they're done once per account and then reach every Claude surface, Claude Code included. | +| **ChatGPT** | Add custom MCP server → paste URL | Open **Codex** in the ChatGPT desktop app, paste the one-line setup prompt, click **Approve**: Codex installs the plugin from the marketplace. | Two things smooth over what's left: diff --git a/docs/install.html b/docs/install.html index 4e06498..140d194 100644 --- a/docs/install.html +++ b/docs/install.html @@ -132,7 +132,7 @@

Installing Geenee: a cheat sheet

Geenee used to reach people as a bare server address they pasted into their connector settings. It now reaches them as a plugin in a marketplace: one install brings the server and a skill that teaches the assistant how to use it, and updates follow. This page shows how the pieces fit and what to do in each app.

-

Claude Code and Codex: one sentence

+

Claude Code, Codex and ChatGPT: one sentence

-

In Claude Code or Codex, paste this and the assistant installs everything itself:

+

In Claude Code, Codex, or Codex inside the ChatGPT desktop app, paste this and the assistant installs everything itself. Each time it asks for permission, click Approve:

Set up Geenee for me: fetch https://geenee-install.3dg.io and follow its instructions for the app you are running in.
-

In claude.ai, the Claude desktop app, Cowork and ChatGPT no prompt can install anything: adding a plugin or connector is an account setting, and a chat cannot change those. Pasted there, the sentence only gets you the list of clicks, so send people straight to the steps for their app below.

+

In claude.ai, the Claude desktop app and Cowork no prompt can install anything: adding a plugin is an account setting, and a chat cannot change those. Pasted there, the sentence only gets you the list of clicks below. Plain ChatGPT chat cannot install Geenee at all; use Codex in the ChatGPT desktop app.

+ +

Geenee is installed only from the marketplace, in every app, because only a marketplace install gets updates. The server address is never added by hand.

What gets installed, and where

- + ON GITHUB IN EACH APP @@ -186,7 +188,7 @@

What gets installed, and where

references/ every tool’s arguments scripts/ - a fallback that needs no connector + a command-line helper @@ -201,17 +203,17 @@

What gets installed, and where

Codex installed per machine - - ChatGPT - server address only, no skill + + ChatGPT desktop + through its Codex, like Codex server + skill server + skill - - address, by hand + + server + skill @@ -226,10 +228,9 @@

What gets installed, and where

tool calls
-
The plugin carries the address so no one types it. Claude and Codex get the server and the skill from one install. ChatGPT cannot install this kind of plugin, so it is still given the address; it gets the tools and the server’s short built-in instructions, but not the skill.
+
The plugin carries the address so no one types it. Claude, Codex and ChatGPT (through its Codex) get the server and the skill from one install, and updates follow.
installed from the marketplace - copied by hand requests while you work
@@ -242,27 +243,39 @@

App by app

- + - - +
AppWhat to doToolsSkillHow often
claude.ai, desktop, CoworkAdd the marketplace, add Geenee, click Connect on its Connectors tab: a few clicks on one settings pageOnce per Claude account
claude.ai, desktop, CoworkAdd the marketplace, add Geenee, then connect it on its Connectors tab: eight short steps in settingsOnce per Claude account
Claude CodeNothing, if the account has it. Otherwise one commandOnce per account, or per machine
CodexTwo commandsOnce per machine
ChatGPTAdd a custom MCP server with the addressOnce per ChatGPT account
Anything elsePoint it at https://geenee.3dg.io/mcpPer client
ChatGPT desktopOpen Codex, paste the one sentence, click ApproveOnce per machine

claude.ai, the Claude desktop app and Cowork

- + + +

You need a paid Claude plan (Pro, Max, Team or Enterprise). There are two parts, adding Geenee and then connecting it. Do both.

    -
  1. Open claude.ai/new#settings/customize-plugins in a new tab. In the app it is Customize → Plugins.
  2. -
  3. Add → Add marketplace → Add from a repository, enter aidenlab/plugins.
  4. -
  5. In Discover, find Geenee and click Add.
  6. -
  7. On Geenee's Connectors tab, click Connect. It shows “Not added” until you do: Claude never connects a plugin's server for you. No login is needed.
  8. -
  9. Start a new conversation.
  10. +
  11. Click Customize in the left sidebar → Plugins
    + In a web browser you can instead go straight to claude.ai/customize/plugins. In Cowork, click the Cowork tab first.
    + ✓ You see a page called Plugins with a Discover tab.
  12. +
  13. Click Add → Add marketplace → Add from a repository
    + Already see aidenlab in your list of marketplaces? Skip to step 5. No Add marketplace? Your organization has turned it off: ask your Claude admin to allow user-added marketplaces, then come back to this step.
  14. +
  15. Type aidenlab/plugins → click the button that adds it
    + ✓ aidenlab now appears in your list of marketplaces.
  16. +
  17. If you see Sync automatically next to aidenlab, turn it on. This is how Geenee’s updates reach you.
  18. +
  19. Click the Discover tab → find Geenee → click Add
  20. +
  21. Click Geenee → the Connectors tab
    + ✓ It says Not added. That’s expected.
  22. +
  23. Click Add if you see it → then click Connect. No login is needed.
    + ✓ It now says Connected. Skip this step and Geenee looks installed but does nothing.
  24. +
  25. Start a new chat → click + in the message box → Connectors → make sure Geenee is switched on.
+

Stuck at any step? Open an issue at github.com/aidenlab/plugins/issues and attach a screenshot of what you see.

+

Claude Code

Already there if the Claude account has Geenee. Otherwise:

@@ -275,14 +288,12 @@

Codex

ChatGPT

    -
  1. chatgpt.com/plugins → + → Add custom MCP server.
  2. -
  3. Name Geenee, address https://geenee.3dg.io/mcp, authentication None.
  4. -
  5. In a new chat, enable Geenee from the tools menu.
  6. +
  7. Open the ChatGPT desktop app → click Codex.
  8. +
  9. Paste the one sentence above.
  10. +
  11. Each time Codex asks for permission, click Approve.
  12. +
  13. When it finishes, it gives you a message. Paste that into a new chat.
- -

Other MCP clients

-

Cursor and other clients take the address directly. A client that only speaks stdio can be bridged:

-
npx -y mcp-remote https://geenee.3dg.io/mcp
+

Plain ChatGPT chat cannot install Geenee.

Before and after

@@ -290,12 +301,12 @@

Before and after

- + - +
Sending a server addressSending people to the plugin
What people receiveA URL, and directions to a settings pageOne sentence to paste (Claude Code, Codex), or a few clicks (Claude apps)
What people receiveA URL, and directions to a settings pageOne sentence to paste (Claude Code, Codex, ChatGPT’s Codex), or eight short steps (Claude apps)
What they getThe toolsThe tools, and a skill that teaches the assistant to use them well
ClaudeA custom connector, set up per accountA plugin on the account, reaching every Claude app
A new server addressEveryone edits their settings by handBump the version; everyone gets it with the next update
Better instructionsOnly through the server’s own short instructionsEdit the skill, bump the version
ChatGPTThe same either way: the address, added by hand
ChatGPTA custom MCP server, added by handThe plugin, installed by Codex in the ChatGPT desktop app
@@ -312,7 +323,7 @@

Is it working?

StateHow you knowIf not InstalledGeenee appears in the app’s plugin listRepeat the steps for the app - Server connectedThe assistant can call open_geeneeClick Connect on Geenee's Connectors tab; start a new conversation + Server connectedThe assistant can call open_geeneeClick Connect on Geenee's Connectors tab; in a new conversation, switch Geenee on under + → Connectors Viewer workingThe page changes when you askOpen, or reopen, the Geenee link @@ -333,7 +344,7 @@

Replacing juicebot

claude plugin uninstall juicebot@aidenlab
 claude plugin marketplace update aidenlab
 claude plugin install geenee@aidenlab
-

In claude.ai, remove JuiceBot on the plugins page and any JuiceBot connector. In ChatGPT, remove any JuiceBot or geenee-dev server.

+

In claude.ai, remove JuiceBot on the plugins page and any JuiceBot connector. In ChatGPT, remove any JuiceBot, geenee-dev or hand-added Geenee server, then install through Codex.

Words

diff --git a/docs/maintaining.md b/docs/maintaining.md index a1029a0..c5980bb 100644 --- a/docs/maintaining.md +++ b/docs/maintaining.md @@ -20,12 +20,15 @@ install-worker/ Cloudflare Worker serving it at geenee-insta scripts/gen-tools-md.py regenerates references/tools.md from the live server scripts/package.sh builds dist/geenee.plugin scripts/test-cli.sh smoke-tests both CLIs against the live server +scripts/check-install-steps.sh fails if the Claude steps in README.md and INSTALL-PROMPT.md differ ``` ## Rules - **Server URL** is `https://geenee.3dg.io/mcp`. To change it, edit both MCP files, `SERVERS` in both CLI scripts, the default in `scripts/gen-tools-md.py`, and the docs (`grep -rn geenee.3dg.io .`). - **Bump `version`** in all four manifests on any change. Users update with `claude plugin marketplace update aidenlab` + `claude plugin update geenee@aidenlab`, or `codex plugin marketplace upgrade aidenlab`. +- **Marketplace only** ([ADR 0001](adr/0001-marketplace-only-distribution.md)). Never document adding the server URL by hand as an install route. +- **The Claude click-through steps** live between `` markers in `README.md` (canonical) and `INSTALL-PROMPT.md` (sent word for word). Edit both; `scripts/check-install-steps.sh` (also run in CI) catches drift. Mirror changes in `docs/install.html` by hand. - **Never rename the plugin `name`.** It is the install id; a rename breaks every install. ## Commands @@ -41,16 +44,17 @@ scripts/test-cli.sh smoke-tests both CLIs against the live serve |---|---|---| | Claude Code | Yes, runs `claude plugin install` | marketplace | | Codex | Yes, runs `codex plugin add` | marketplace | -| claude.ai / desktop / Cowork | No: account settings, user clicks | marketplace on the plugins page, or a custom connector | -| ChatGPT | No: user adds a custom MCP server | server URL only | +| claude.ai / desktop / Cowork | No: account settings, user clicks | marketplace on the plugins page | +| ChatGPT desktop (Codex) | Yes, via Codex; user clicks Approve | marketplace | +| Plain ChatGPT chat | No: sent to Codex in the ChatGPT desktop app | none | The only true one-click on claude.ai is a listing in Anthropic's plugin directory: the chat can then show an **Install** card. Submit at [platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit) (or [claude.ai admin settings](https://claude.ai/admin-settings/directory/submissions/plugins/new) for a Team/Enterprise owner); run `claude plugin validate ./plugins/geenee` first. ## Organizations -- **Connector:** add `https://geenee.3dg.io/mcp` as an organization connector (Claude Team/Enterprise). Members get the tools with no setup. +- **Connector:** an Owner may need to add the plugin's bundled connector under Organization settings → Connectors before members can connect it, and to allow user-added marketplaces (Plugins & skills → Policy → User-created skills). - **Plugin:** Organization settings → Plugins & skills → Marketplaces → Sync from GitHub (needs a private or internal mirror with the Claude GitHub App), or upload the release's `geenee.plugin`. See [Manage plugins for your organization](https://support.claude.com/en/articles/13837433-manage-plugins-for-your-organization). ## Retired juicebot -`juicebot` is no longer updated; its last state is the git tag `juicebot-archive`. Users replace it: Claude Code `claude plugin uninstall juicebot@aidenlab` then install geenee; Codex remove `juicebot@aidenlab`, `codex plugin marketplace upgrade aidenlab`, `codex plugin add geenee@aidenlab`; claude.ai remove JuiceBot on the plugins page and any JuiceBot connector; ChatGPT remove any JuiceBot or `geenee-dev` server. +`juicebot` is no longer updated; its last state is the git tag `juicebot-archive`. Users replace it: Claude Code `claude plugin uninstall juicebot@aidenlab` then install geenee; Codex remove `juicebot@aidenlab`, `codex plugin marketplace upgrade aidenlab`, `codex plugin add geenee@aidenlab`; claude.ai remove JuiceBot on the plugins page and any JuiceBot connector; ChatGPT remove any JuiceBot, `geenee-dev` or hand-added Geenee server, then install through Codex. diff --git a/install-worker/README.md b/install-worker/README.md index 13a8c4a..ed55b03 100644 --- a/install-worker/README.md +++ b/install-worker/README.md @@ -1,6 +1,6 @@ # install-worker -Cloudflare Worker behind **https://geenee-install.3dg.io**. It serves `INSTALL-PROMPT.md` from this repository's `main` branch (proxied, cached 5 min) so the one-line setup prompt has a short, stable URL. `/geenee.py` and `/geenee.mjs` serve the skill's CLI scripts; `/plugins` redirects to Claude's plugin settings page (`claude.ai/new#settings/customize-plugins`), `/plugin` to the latest `geenee.plugin` release asset; any other path serves that file from the repo (`/README.md`). +Cloudflare Worker behind **https://geenee-install.3dg.io**. It serves `INSTALL-PROMPT.md` from this repository's `main` branch (proxied, cached 5 min) so the one-line setup prompt has a short, stable URL. `/geenee.py` and `/geenee.mjs` serve the skill's CLI scripts; `/plugins` redirects to Claude's plugin settings page (`claude.ai/customize/plugins`), `/plugin` to the latest `geenee.plugin` release asset; any other path serves that file from the repo (`/README.md`). Deploy (from a machine with `wrangler login` on the account that owns `3dg.io`; needed again whenever `wrangler.toml` or `src/` changes): diff --git a/install-worker/src/index.js b/install-worker/src/index.js index 387d812..b1df92f 100644 --- a/install-worker/src/index.js +++ b/install-worker/src/index.js @@ -67,7 +67,7 @@ export default { }; if (url.pathname === '/plugins') { - return Response.redirect('https://claude.ai/new#settings/customize-plugins', 302); + return Response.redirect('https://claude.ai/customize/plugins', 302); } if (url.pathname === '/plugin') { return Response.redirect(`https://github.com/${REPO}/releases/latest/download/geenee.plugin`, 302); diff --git a/plugins/geenee/README.md b/plugins/geenee/README.md index 7159e9c..093251d 100644 --- a/plugins/geenee/README.md +++ b/plugins/geenee/README.md @@ -12,7 +12,7 @@ In Claude Code or Codex, paste this and the assistant installs everything: Set up Geenee for me: fetch https://geenee-install.3dg.io and follow its instructions for the app you are running in. ``` -In claude.ai, the Claude desktop app, Cowork and ChatGPT no prompt can install it: a chat cannot change account settings. Those take a few clicks, listed in the [marketplace README](../../README.md). Quickest by hand: Claude Code `/plugin install geenee --marketplace aidenlab/plugins` then `/reload-plugins`; Codex `codex plugin marketplace add aidenlab/plugins` then `codex plugin add geenee@aidenlab`; Claude web/desktop/Cowork: https://claude.ai/new#settings/customize-plugins → Add → Add marketplace → `aidenlab/plugins` → Discover → Geenee → Add, then Geenee's Connectors tab → Connect; ChatGPT adds `https://geenee.3dg.io/mcp` as a custom MCP server. +In claude.ai, the Claude desktop app and Cowork no prompt can install it: a chat cannot change account settings. Those take eight short steps, listed in the [marketplace README](../../README.md). In ChatGPT, use Codex in the ChatGPT desktop app and paste the one-line prompt there. Geenee is installed only from the marketplace, never by adding the server address by hand. Quickest by hand: Claude Code `/plugin install geenee --marketplace aidenlab/plugins` then `/reload-plugins`; Codex `codex plugin marketplace add aidenlab/plugins` then `codex plugin add geenee@aidenlab`. ## Try it diff --git a/scripts/check-install-steps.sh b/scripts/check-install-steps.sh new file mode 100755 index 0000000..d88f6be --- /dev/null +++ b/scripts/check-install-steps.sh @@ -0,0 +1,14 @@ +#!/usr/bin/env bash +# The Claude click-through steps exist twice: in README.md (canonical) and in +# INSTALL-PROMPT.md (sent word for word by the assistant). Fail if they differ. +set -eu +cd "$(dirname "$0")/.." +extract() { sed -n '//,//p' "$1"; } +a="$(extract README.md)"; b="$(extract INSTALL-PROMPT.md)" +[ -n "$a" ] || { echo "FAIL: no claude-steps block in README.md"; exit 1; } +if [ "$a" != "$b" ]; then + echo "FAIL: Claude steps differ between README.md and INSTALL-PROMPT.md:" + diff <(echo "$a") <(echo "$b") || true + exit 1 +fi +echo "Claude steps match"