superbased

Install SuperBased from inside your AI coding tool — Claude Code & Codex marketplaces, Gemini CLI extension, Goose, OpenCode, Cursor deeplin
Open source Open in the app JSON README (API)
About

Install SuperBased from inside your AI coding tool — Claude Code & Codex marketplaces, Gemini CLI extension, Goose, OpenCode, Cursor deeplink. Requires the observer binary (npm i -g @superbased/observer, or pipx install superbased-observer).
Details

Kind: Plugins
Topic: Developer tools
Publisher: superbasedapp
Origin: gemini
Category: ferramentas
Version: 1.28.0
Stars: 1
Last push: 2026-08-01T12:08:59Z
Repository state: ativo
Language: TypeScript
License: NOASSERTION
Added: 2026-08-30 14:13:39
Updated: 2026-08-30 14:13:39
Origin id: superbasedapp/plugins
README

<!-- ASSEMBLED by scripts/assemble-plugins-repo.sh in the superbased-observer
     repository. Do not edit by hand: the per-surface sections below are
     copied verbatim out of each surface's own README, which is itself
     generated by plugins/plugingen from the real `observer init`
     registrars. -->

# SuperBased — plugins for AI coding agents

Install [SuperBased Observer](https://superbased.app/) 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/) | [superbased/README.md](superbased/README.md) |
| Codex | `.agents/plugins/marketplace.json` + [`plugins/superbased/`](plugins/superbased/) | [codex/README.md](codex/README.md) |
| Gemini CLI | [`gemini-extension.json`](gemini-extension.json) (repository root) | [gemini/README.md](gemini/README.md) |
| Goose | no manifest — Goose extensions *are* MCP servers | [goose/README.md](goose/README.md) |
| Cursor | a one-click `cursor://` deeplink | [cursor/README.md](cursor/README.md) |
| OpenCode | the `@superbased/opencode-plugin` npm package | [opencode/README.md](opencode/README.md) |
| Kimi Code | [`kimi.plugin.json`](kimi.plugin.json) (repository root) | [kimi-code/README.md](kimi-code/README.md) |
| Qoder | `.qoder-plugin/marketplace.json` + [`qoder/superbased/`](qoder/superbased/) | [qoder/README.md](qoder/README.md) |
| Devin | `.devin-plugin/plugin.json` + `mcp_config.json` (repository root) | [devin/README.md](devin/README.md) |
| Droid | `.factory-plugin/marketplace.json` + [`factory/superbased/`](factory/superbased/) | [droid/README.md](droid/README.md) |
| OpenClaw | [`openclaw.plugin.json`](openclaw.plugin.json) (repository root) | [openclaw/README.md](openclaw/README.md) |
| Antigravity | [`antigravity/superbased/`](antigravity/superbased/) (copied or `agy plugin install`ed) | [antigravity/README.md](antigravity/README.md) |
| GitHub Copilot (VS Code) | a one-click `vscode:mcp/install` link | [copilot/README.md](copilot/README.md) |
| Claude Desktop / Cowork | [`cowork/superbased/manifest.json`](cowork/superbased/manifest.json) — an `.mcpb` bundle, **unverified** | [cowork/README.md](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](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](superbased/README.md).

### Codex

#### Install

```bash
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](codex/README.md).

### Gemini CLI

#### Install

```bash
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](gemini/README.md).

### Goose

#### Install — the interactive way

```bash
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):

```yaml
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

```bash
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](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:

```markdown
[![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](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`):

```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](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](kimi-code/README.md).

### Qoder

#### Install

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

```bash
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:

```bash
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](qoder/README.md).

### Devin

#### Install

```bash
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:

```bash
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](devin/README.md).

### Droid

#### Install

```bash
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](droid/README.md).

### OpenClaw

#### Install

```bash
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:

```bash
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](openclaw/README.md).

### Antigravity

#### Install

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

```bash
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:

```bash
# 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](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:

```markdown
[![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`:

```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](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` |

```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](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](crush/README.md) |
| Kiro CLI | `~/.kiro/settings/mcp.json` | [kiro-cli/README.md](kiro-cli/README.md) |
| GitHub Copilot CLI | `~/.copilot/mcp-config.json` (key `mcpServers`, **not** VS Code's `servers`) | [copilot-cli/README.md](copilot-cli/README.md) |
| Kilo Code | `kilo.jsonc`'s `mcp` key | [kilo-code/README.md](kilo-code/README.md) |
| Roo Code | `.roo/mcp.json` | [roo-code/README.md](roo-code/README.md) |
| Open Interpreter | `~/.openinterpreter/config.toml` | [open-interpreter/README.md](open-interpreter/README.md) |
| Command Code | `~/.commandcode/mcp.json` — though `observer init` writes this one for you | [command-code/README.md](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](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](LICENSE).
superbased

About

Details

README

More
