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.
| 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 agemini-extension.json, which is why that manifest sits at the repository root. - Grok —
docs.x.aistates 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.
/plugin marketplace add superbasedapp/plugins
/plugin install superbased@superbased
Full detail: superbased/README.md.
codex plugin marketplace add superbasedapp/pluginsThen, 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 extensions install https://github.com/superbasedapp/pluginsInstalling 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.
.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 configureThen 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 |
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: 300Restart Goose (edits to the config file do not reach an already-running
session), then check it with goose info -v.
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://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:
[](cursor://anysphere.cursor-deeplink/mcp/install?name=observer&config=eyJjb21tYW5kIjoib2JzZXJ2ZXIiLCJhcmdzIjpbInNlcnZlIl19)Full detail — including the security constraint on deeplinks: cursor/README.md.
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-pluginis not on npm; this directory is the package source. Publishing is an operator-gated step.
Full detail: opencode/README.md.
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.
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.
Add this repository as a marketplace, then install from it:
qodercli plugins marketplace add superbasedapp/plugins
qodercli plugins install superbased@superbasedmarketplace 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/superbasedAn 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.
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 plugins install superbasedapp/pluginsA 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.
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/superbasedThere 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 plugin marketplace add https://github.com/superbasedapp/plugins
droid plugin install superbased@superbasedOr 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 plugins install https://github.com/superbasedapp/pluginsopenclaw 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/superbasedInstalled 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.
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.
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.
To put the link in a README of your own:
[](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.)
To share the server with everyone working in a repository, commit this as
.vscode/mcp.json:
{
"servers": {
"observer": {
"type": "stdio",
"command": "observer",
"args": [
"serve"
]
}
}
}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.
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.
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.
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.
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.
- Wiring only. Requires the
observerbinary 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 initwrites 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 whereobserver initdetects the plugin and stands down by itself.
Apache-2.0 — see LICENSE.