Installation Scopes

The Prism plugin involves two separate scope questions that are easy to confuse:

Plugin install scope — where Claude Code’s plugin registration lives (handled by /plugin).
Prism config scope — where the OTEL env vars and your gck_* key live (handled by /prism:setup).

They’re independent. You can install the plugin at one scope and keep your key at another.

Plugin install scope (Claude Code)

Claude Code installs plugins at one of three scopes, written to the corresponding settings file:

Scope	File	Shared with team
`user`	`~/.claude/settings.json`	No (default)
`project`	`.claude/settings.json`	Yes (commit to git)
`local`	`.claude/settings.local.json`	No (gitignored)

Picking a scope at install time

/plugin install prism@optra-prism --scope project

Valid values: user (default), project, local. You can also use /plugin → Discover and pick a scope interactively.

Installing at project scope writes to the committed .claude/settings.json so collaborators who clone the repo get the plugin enabled automatically:

{
  "extraKnownMarketplaces": {
    "optra-prism": {
      "source": { "source": "github", "repo": "grumatic/optra-prism-plugin" }
    }
  },
  "enabledPlugins": {
    "prism@optra-prism": true
  }
}

Each developer then still runs /prism:setup gck_THEIR_KEY — the key itself is never committed.

Changing plugin scope later

Claude Code does not expose a “move” command, so:

/plugin uninstall prism@optra-prism --scope user
/plugin install prism@optra-prism --scope project

Or uninstall / reinstall through /plugin → Installed, which groups plugins by scope.

Prism config scope (OTEL vars + your key)

Telemetry only works if a set of OTEL_* environment variables — one of which embeds your gck_* key in OTEL_EXPORTER_OTLP_HEADERS — is present when Claude Code starts. Claude Code reads those vars from a settings.json file’s "env" block at process launch.

The plugin writes those vars to exactly one of two places, chosen by you at setup:

Config scope	File	Behavior
`user` (default)	`~/.claude/settings.json`	Telemetry active in every project you open
`project`	`$CLAUDE_PROJECT_DIR/.claude/settings.local.json`	Telemetry active only in this project (file is auto-gitignored by Claude Code)

Picking a config scope

/prism:setup gck_YOUR_KEY --user      # activate everywhere (default)
/prism:setup gck_YOUR_KEY --project   # activate only in this project
/prism:setup gck_YOUR_KEY             # keep current scope, or `user` on fresh install

When the current scope and the requested scope differ, /prism:setup prompts before migrating so you don’t silently lose telemetry in other projects.

When each scope makes sense

--user — personal machines, single-key workflows. Simplest default.
--project — multiple repos with different keys (for example, work vs. personal, or per-client orgs), or teams that commit the plugin install to .claude/settings.json but want each developer’s key kept in their gitignored .claude/settings.local.json.

Seeing the current state

/prism:status

Shows the active config scope (user, project, both, or none) and the settings file that holds the OTEL vars. If both is reported, the next /prism:setup will ask which one to keep.

Changing scopes between `user` and `project`

/prism:setup handles the switch for you — it always moves the OTEL vars, never duplicates them. Pass the scope flag you want; the command diffs it against the current scope and prompts before doing anything destructive.

From user → project (you want telemetry scoped to this project only):

/prism:setup gck_YOUR_KEY --project

You’ll see a prompt like:

Prism is currently active globally (user scope). Switching to project scope will stop telemetry in all your other projects. Continue? [y/N]

On y, the command:

Removes the OTEL vars from ~/.claude/settings.json.
Writes them to $CLAUDE_PROJECT_DIR/.claude/settings.local.json (gitignored).
Reminds you to restart Claude Code.

From project → user (you want telemetry everywhere):

/prism:setup gck_YOUR_KEY --user

Mirror prompt:

Prism is currently active only in this project. Switching to user scope will enable telemetry in every project you open with Claude Code. Continue? [y/N]

From both → one scope: run /prism:setup (no flag) and the command asks which scope to keep:

Prism is active in both user scope and this project. Pick one to keep: [user/project]

It removes the other scope’s vars and leaves the chosen scope intact.

After any scope change: restart Claude Code. OTEL env vars are read at process launch, so a running session won’t pick them up.

Need to re-use the same key? Omit the key argument if you’re only switching scopes:

/prism:setup --project

The command reads your existing key from ~/.prism/config.json and applies the scope change.

Editing settings by hand

The supported path is /prism:setup. If you need to edit the settings files directly — e.g. a script is bootstrapping a dev machine — the rules are:

Copy all OTEL_* keys from the old scope’s "env" block to the new scope’s "env" block.
Remove them from the old scope so you don’t end up in both.
Never put them in the shared .claude/settings.json — the OTEL_EXPORTER_OTLP_HEADERS value embeds your gck_* key.

Use /prism:status afterwards to confirm the scope reports what you expect.

Team distribution pattern

The common “team install” is a combination of both scopes:

Commit the plugin registration at project scope — so .claude/settings.json has enabledPlugins["prism@optra-prism"]: true.
Each developer runs /prism:setup gck_THEIR_KEY --project locally — their key lands in the gitignored .claude/settings.local.json.

The repo carries “Prism is enabled here”; each developer’s key stays private.