Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .github/workflows/check.yml
Original file line number Diff line number Diff line change
@@ -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
28 changes: 28 additions & 0 deletions GLOSSARY.md
Original file line number Diff line number Diff line change
@@ -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.
79 changes: 54 additions & 25 deletions INSTALL-PROMPT.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand All @@ -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.
<!-- claude-steps:start -->
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.
<!-- claude-steps:end -->

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`).
Expand All @@ -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)

Expand All @@ -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)

Expand Down
52 changes: 35 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
<!-- claude-steps:start -->
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.
<!-- claude-steps:end -->

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

Expand All @@ -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.
Loading
Loading