SuperBased — plugins for AI coding agents

Install SuperBased Observer from inside the AI coding agent you already use. Observer is local-first token, cost and cache observability: it captures what your coding agents actually do, and keeps it in a SQLite database on your own machine.

Requires the observer binary already on your PATH (npm i -g @superbased/observer, or pipx install superbased-observer). Every artifact in this repository is wiring only — each one declares an MCP server (and, for Claude Code, lifecycle hooks) that runs a binary you install separately. Nothing here downloads, bundles or installs a binary.

Plugin version: 1.28.0 — kept in lockstep with the observer release it wires.

What's in here

Surface	Install artifact	Detail
Claude Code	.claude-plugin/marketplace.json + superbased/	superbased/README.md
Codex	.agents/plugins/marketplace.json + plugins/superbased/	codex/README.md
Gemini CLI	gemini-extension.json (repository root)	gemini/README.md
Goose	no manifest — Goose extensions are MCP servers	goose/README.md
Cursor	a one-click cursor:// deeplink	cursor/README.md
OpenCode	the @superbased/opencode-plugin npm package	opencode/README.md
Kimi Code	kimi.plugin.json (repository root)	kimi-code/README.md
Qoder	.qoder-plugin/marketplace.json + qoder/superbased/	qoder/README.md
Devin	.devin-plugin/plugin.json + mcp_config.json (repository root)	devin/README.md
Droid	.factory-plugin/marketplace.json + factory/superbased/	droid/README.md
OpenClaw	openclaw.plugin.json (repository root)	openclaw/README.md
Antigravity	antigravity/superbased/ (copied or agy plugin installed)	antigravity/README.md
GitHub Copilot (VS Code)	a one-click vscode:mcp/install link	copilot/README.md
Claude Desktop / Cowork	cowork/superbased/manifest.json — an .mcpb bundle, unverified	cowork/README.md
Crush · Kiro CLI · Copilot CLI · Kilo Code · Roo Code · Open Interpreter · Command Code	a config block to paste (no package format exists)	see "Config listings" below
Pi	nothing — capture is native and Pi has no MCP client	pi/README.md

Two more tools reach this repository through a surface it already carries, per those vendors' own documentation — we have not live-verified either, and neither has an artifact of its own here:

• Qwen Code — qwen extensions install <owner>/<repo> is documented as auto-converting a gemini-extension.json, which is why that manifest sits at the repository root.
• Grok — docs.x.ai states Grok reads Claude Code marketplaces, plugins, MCPs and hooks with "zero configuration needed". Grok's own plugin schema is not publicly documented, so inventing a second manifest would be a guess; the Claude Code artifacts above are the Grok surface.

Install

Claude Code

Install

/plugin marketplace add superbasedapp/plugins
/plugin install superbased@superbased

Full detail: superbased/README.md.

Codex

Install

codex plugin marketplace add superbasedapp/plugins

Then, inside Codex, open the plugin browser with /plugins, find SuperBased Observer under the superbased marketplace, and install it. Start a new thread afterwards — sessions already open do not pick up newly installed plugin files.

Other documented marketplace verbs: codex plugin marketplace list, … upgrade [name], … remove <name>. Installs are cached under ~/.codex/plugins/cache/<marketplace>/<plugin>/<version>/.

Full detail: codex/README.md.

Gemini CLI

Install

gemini extensions install https://github.com/superbasedapp/plugins

Installing from GitHub requires git, and the CLI copies the extension — run gemini extensions update superbased to pick up a new release. Uninstall with gemini extensions uninstall superbased; disable without removing via gemini extensions disable superbased (add --scope=workspace for just the current workspace). Inside the CLI, /extensions list shows what is loaded.

⚠️ The manifest has to be at the root of whatever you install. Gemini documents a GitHub URL or a local path, and nothing else — there is no documented way to install from a subdirectory of a repo. So publishing this directory means either its own repo, or a repo root that also carries the other surfaces (their root-level names — .claude-plugin/, .agents/ — do not collide with gemini-extension.json). That choice is an operator step; nothing here has been published or tested against a live install.

In THIS repository that root-placement choice is already made: gemini-extension.json sits at the top level, alongside the Claude Code and Codex catalogs.

Full detail: gemini/README.md.

Goose

Install — the interactive way

goose configure

Then answer the prompts:

Prompt	Answer
What would you like to configure?	Add Extension
What type of extension would you like to add?	Command-line Extension
What would you like to call this extension?	observer
What command should be run?	observer serve
Please set the timeout for this tool (in secs):	300
Would you like to add environment variables?	No

Install — the config-file way

Add this to ~/.config/goose/config.yaml (merge the extensions: key if you already have one):

extensions:
  observer:
    type: stdio
    name: observer
    enabled: true
    cmd: observer
    args: ["serve"]
    env_keys: []
    envs: {}
    timeout: 300

Restart Goose (edits to the config file do not reach an already-running session), then check it with goose info -v.

Try it for one session only

goose session --with-extension "observer serve"

Per the Goose docs this does not install the extension — it is enabled for that session only.

Full detail: goose/README.md.

Cursor

The link

cursor://anysphere.cursor-deeplink/mcp/install?name=observer&config=eyJjb21tYW5kIjoib2JzZXJ2ZXIiLCJhcmdzIjpbInNlcnZlIl19

Also in deeplink.txt (single line, newline-terminated) for scripting.

Markdown form for a README or a web page:

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=observer&config=eyJjb21tYW5kIjoib2JzZXJ2ZXIiLCJhcmdzIjpbInNlcnZlIl19)

Full detail — including the security constraint on deeplinks: cursor/README.md.

OpenCode

Install

Add the package to the plugin array of your opencode.json (~/.config/opencode/opencode.json for every project, or a project-local opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@superbased/opencode-plugin"]
}

OpenCode installs npm plugins with Bun at startup and caches them in ~/.cache/opencode/node_modules/ — there is no separate npm install step.

Not published yet. @superbased/opencode-plugin is not on npm; this directory is the package source. Publishing is an operator-gated step.

Full detail: opencode/README.md.

Kimi Code

Install

Inside Kimi Code:

/plugins install https://github.com/superbasedapp/plugins

A bare GitHub repository URL resolves to the latest release, falling back to the default branch. The other documented pinned forms also work: …/tree/<ref>, …/releases/tag/<tag> and …/commit/<sha>. Downloads go through github.com / codeload.github.com only.

Installed plugins live under $KIMI_CODE_HOME/plugins/managed/<id>/. Manage them with /plugins list, /plugins info superbased, /plugins enable|disable superbased, /plugins reload and /plugins remove superbased. The MCP server this plugin declares can be toggled on its own with /plugins mcp enable|disable superbased observer.

Kimi Code shows a trust badge per source; a third-party install (this one, until it is listed in an official catalog) defaults the confirmation prompt to cancel, so you have to confirm deliberately.

⚠️ The manifest has to be at the root of whatever you install. The documented remote install takes a repository URL, so kimi.plugin.json belongs at the repository root — the same constraint gemini-extension.json carries. In this source tree it lives under kimi-code/superbased/ alongside the other surfaces; the public repository puts it at the top level, where its name collides with nothing else that must live there.

Full detail: kimi-code/README.md.

Qoder

Install

Add this repository as a marketplace, then install from it:

qodercli plugins marketplace add superbasedapp/plugins
qodercli plugins install superbased@superbased

marketplace add also takes a git URL, a local directory or a marketplace.json URL, and --scope takes user (the default), project or local.

Or install the plugin directory straight from a clone, with no marketplace at all:

qodercli plugins install ./qoder/superbased

An absolute path or a ~/… path works too, and -s/--scope takes the same three values. Restart the CLI or run /plugins reload afterwards. Locally-installed plugins carry the id superbased@local; manage them with qodercli plugins list|enable|disable|validate|update and qodercli plugins uninstall superbased@local.

Why there is a catalog here at all

Qoder looks for a marketplace manifest in a fixed order — .qoder-plugin/marketplace.json, then .claude-plugin/marketplace.json, then marketplace.json — and this repository carries a .claude-plugin/marketplace.json at its root for Claude Code. Without a Qoder catalog to take the first slot, qodercli plugins marketplace add on this repository would fall through to the Claude Code entry and install that plugin — which bundles hooks/hooks.json full of observer hook claude-code … commands written for a different tool. The catalog above takes the first slot and resolves to the Qoder plugin, which declares an MCP server and nothing else. (Droid documents the same fallback and gets the same treatment; see ../droid/.)

The catalog entry carries no version: Qoder reads the pin from the plugin's own .qoder-plugin/plugin.json, exactly like the Codex and Droid catalogs.

Full detail: qoder/README.md.

Devin

Install

devin plugins install superbasedapp/plugins

A GitHub owner/repo, any git URL, or a local folder are the three documented sources; -y/--yes skips the confirmation prompt. Manage with devin plugins list|info|update|remove.

⚠️ Repository-root placement. A git-URL install takes the repository, so the plugin's own files have to be at that repository's root. In this source tree they live under devin/superbased/ next to the other surfaces; the public repository puts .devin-plugin/ and mcp_config.json at the top level, where neither name collides with another surface's root entry. If you would rather not take the whole repository, clone it and install the directory:

devin plugins install ./devin/superbased

There is no Devin plugin marketplace to list in. Cognition documents no public catalog for the CLI (the "MCP Marketplace" is Devin Cloud's settings page — a different product surface), so a git-URL install is the whole distribution channel, and no catalog file is generated.

Full detail: devin/README.md.

Droid

Install

droid plugin marketplace add https://github.com/superbasedapp/plugins
droid plugin install superbased@superbased

Or browse with /plugins inside the CLI. A local checkout works too — droid plugin marketplace add ./droid then the same install line.

Factory maintains its own official marketplace at github.com/Factory-AI/factory-plugins. Listing there is a public submission, not something this repository does on its own; the catalog above is the self-hosted form, exactly like the Codex surface.

Full detail: droid/README.md.

OpenClaw

Install

openclaw plugins install https://github.com/superbasedapp/plugins

openclaw plugins install accepts an npm spec, a git URL, a local path, a tarball or a zip. From a local checkout:

openclaw plugins install ./openclaw/superbased

Installed plugins are extracted into ~/.openclaw/extensions/<id>/ and enabled in config. Manage them with openclaw plugins list|info|update|enable|disable|doctor. The plugin id is superbased, which is also the key under plugins.entries in your OpenClaw config.

Full detail: openclaw/README.md.

Antigravity

Install

Clone or download this repository, then either let the CLI stage it:

agy plugin install ./antigravity/superbased

— which copies it into ~/.gemini/antigravity-cli/plugins/superbased/ — or copy the folder into one of the two documented plugin directories yourself and restart:

# active in every workspace
cp -r antigravity/superbased ~/.gemini/config/plugins/

# active in one workspace only
cp -r antigravity/superbased <your-project>/.agents/plugins/

Then agy plugin list to confirm, and agy plugin disable|enable|uninstall superbased to manage it. The argument is the manifest's name, which is why this plugin sets it explicitly instead of inheriting the folder name.

Full detail — including why this one is NOT at the repository root: antigravity/README.md.

GitHub Copilot (VS Code)

Install

Click the link (or paste it into a browser; on Linux, xdg-open "<link>" works from a terminal):

vscode:mcp/install?%7B%22name%22%3A%22observer%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22observer%22%2C%22args%22%3A%5B%22serve%22%5D%7D

VS Code Insiders:

vscode-insiders:mcp/install?%7B%22name%22%3A%22observer%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22observer%22%2C%22args%22%3A%5B%22serve%22%5D%7D

VS Code opens the MCP install prompt with the server pre-filled; confirm it, and the entry lands in your user profile. MCP: Add Server from the Command Palette and code --add-mcp '<json>' are the equivalent manual routes.

As a badge

To put the link in a README of your own:

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_observer-0098FF?logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22observer%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22observer%22%2C%22args%22%3A%5B%22serve%22%5D%7D)

(The image comes from shields.io, a third-party badge host; the link itself is first-party VS Code.)

Or as a workspace file

To share the server with everyone working in a repository, commit this as .vscode/mcp.json:

{
  "servers": {
    "observer": {
      "type": "stdio",
      "command": "observer",
      "args": [
        "serve"
      ]
    }
  }
}

⚠️ servers here, mcpServers in Copilot CLI

VS Code's mcp.json uses the top-level key servers. GitHub Copilot CLI — a different product, documented in ../copilot-cli/ — uses mcpServers and states outright that it will not read .vscode/mcp.json because of the servers key. Copy the block from the page that matches the product you are configuring; the wrong key fails silently.

Full detail: copilot/README.md.

Claude Desktop / Cowork — UNVERIFIED

Install

The documented, grounded route — merge this into claude_desktop_config.json and restart Claude Desktop:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "observer": {
      "command": "observer",
      "args": [
        "serve"
      ]
    }
  }
}

The bundle route (unverified, see the box above): pack this directory into a .mcpb and drag the result into Settings → Extensions.

Full detail — including what is unverified and why: cowork/README.md.

Config listings

Some tools have no plugin or extension package at all: their one first-party extension surface is their own config file. For those, the artifact is the exact block to paste — generated from the same registrars as every manifest above, so a changed launch argument reaches it too.

Tool	File	Detail
Crush	crush.json's mcp key	crush/README.md
Kiro CLI	~/.kiro/settings/mcp.json	kiro-cli/README.md
GitHub Copilot CLI	~/.copilot/mcp-config.json (key mcpServers, not VS Code's servers)	copilot-cli/README.md
Kilo Code	kilo.jsonc's mcp key	kilo-code/README.md
Roo Code	.roo/mcp.json	roo-code/README.md
Open Interpreter	~/.openinterpreter/config.toml	open-interpreter/README.md
Command Code	~/.commandcode/mcp.json — though observer init writes this one for you	command-code/README.md

And one tool needs nothing at all: Pi has no MCP client by design, and observer already reads Pi's own session transcripts — pi/README.md explains what would and would not be worth building there.

Why the layout looks like this

Every one of these formats resolves its relative paths from a repository root, so all three root-level entry points have to sit at the top of this repository. Their names do not collide, which is what lets one repository serve all of them:

Root path	Belongs to	Why it must be at the root
.claude-plugin/marketplace.json	Claude Code	the catalog entry's "./superbased" source resolves against the directory holding .claude-plugin/; ../ is forbidden
.agents/plugins/marketplace.json	Codex	Codex reads a repo-scoped catalog at $REPO_ROOT/.agents/plugins/marketplace.json, and the entry's "./plugins/superbased" source resolves against that root
gemini-extension.json	Gemini CLI (and Qwen Code)	gemini extensions install documents a repository URL or a local path and nothing else — installing from a repository subdirectory is not documented
kimi.plugin.json	Kimi Code	/plugins install <github-url> installs a repository, so the manifest is the repository's
openclaw.plugin.json	OpenClaw	openclaw plugins install <git spec> likewise
.devin-plugin/plugin.json + mcp_config.json	Devin	devin plugins install owner/repo makes the repository root the plugin root, and Devin reads its components from that root
.factory-plugin/marketplace.json	Droid	droid plugin marketplace add <source> reads the catalog from the root — and Droid falls back to .claude-plugin/marketplace.json when it is absent, so shipping ours shadows that fallback with a plugin that declares only an MCP server. Its plugin lives at factory/superbased/ so it cannot merge with the Claude Code plugin directory
.qoder-plugin/marketplace.json	Qoder	qodercli plugins marketplace add <source> reads the catalog from the root, trying .qoder-plugin/marketplace.json, then .claude-plugin/marketplace.json, then marketplace.json — so without ours Qoder would install the Claude Code plugin, hooks and all. Only the catalog is at the root; the plugin it names stays at qoder/superbased/, which is also where Qoder's own documented local-path install points

Everything else is in a subdirectory, because nothing about those tools resolves from a repository root: the Qoder PLUGIN installs from a local path (only its catalog needs the root, see above), Antigravity stages a local directory into your own home (and deliberately stays out of .agents/plugins/, which is Codex's), the Claude Desktop bundle is packed rather than read in place, the Copilot link is a URI, and the config listings are pages to read.

The per-surface READMEs below each install section were written against the source tree, where every surface owns its own directory. Where one of them draws a layout with a surface directory at the top (codex/, for example), that directory is this repository's root here.

How this repository is produced

Generated: every manifest (.claude-plugin/marketplace.json, superbased/.claude-plugin/plugin.json, .agents/plugins/marketplace.json, plugins/superbased/.codex-plugin/plugin.json, both .mcp.json files, superbased/hooks/hooks.json, gemini-extension.json), every per-surface README, cursor/deeplink.txt and opencode/src/wiring.generated.ts.

Hand-written: the OpenCode npm package's glue — opencode/package.json, opencode/tsconfig.json and opencode/src/index.ts (the SDK plumbing a generator has no business owning; the wiring it consumes is generated). LICENSE is copied verbatim from the observer repository and .gitignore is a fixed block in the assembler.

Assembled: this landing page. Its per-surface install sections are copied verbatim out of the per-surface READMEs above, so an install command cannot drift between this page and the surface that owns it.

The manifests are generated by plugins/plugingen in the private superbased-observer repository, which does not re-describe observer's wiring — it runs the real observer init registrars against a throwaway sandbox HOME and transposes exactly what they wrote into each surface's format. A changed MCP argument or a new hook event therefore reaches these manifests automatically, and a CI drift gate fails until the regenerated tree is committed.

This repository tree is then assembled from that output by scripts/assemble-plugins-repo.sh, which performs the directory-per-surface → repository-root transpose described above and stamps the release version.

The one deliberate deviation from what observer init writes: init registers the absolute path of the running binary, which a cache-copied plugin cannot know, so every manifest here resolves observer from PATH.

Honesty notes

• Wiring only. Requires the observer binary already on your PATH. No artifact here ships, downloads or bundles a binary, and each listing says so in those words.
• Local by default. Captured data lands in ~/.observer/observer.db. The MCP server makes no network calls of its own; shipping anything off the machine is a separate, opt-in Teams configuration none of these plugins touch.
• No efficiency claims. No listing here promises an efficiency, context or cost benefit of any kind. Observer measures what your agents spend; it does not claim to change it.
• Double-wiring. Several of these surfaces declare the same MCP server observer init writes into that tool's own config. Where a duplicate is possible, the surface's README says so plainly and tells you what to do about it. Claude Code is the one surface where observer init detects the plugin and stands down by itself.

License

Apache-2.0 — see LICENSE.