Extension Profiles
Create separate sets of extensions for research, coding, review, or any other kind of work.
An Extension Profile is a named set of installed plugins and standalone skills. You choose what each profile includes. For example:
- Research: only extensions for browsing, reading documentation, and working with sources.
- Coding: plugins and skills for implementing changes and writing tests.
- Review: a separate set for reviewing changes before they ship.
These are examples you can create, not preset profiles. A custom profile loads only the extensions you select; it does not pick up extensions from other profiles.
Profiles are not tied to a particular project. You can switch from research to coding in the same workspace, or reuse a global profile across different workspaces. You can also save a profile in a workspace when you want to keep its definition with that project.
Profiles choose extensions, not the active agent or model. Agent profiles, permissions, sandbox rules, credentials, and plugin versions have their own settings.
Open /extensions to build a profile. The guided editor lets you install plugins while choosing your set, then shows everything that will be added or removed before you apply it. Plugins installed through this editor stay inactive until that final step. The Plugins browser has a separate install-and-activate action.
Use fewer input tokens
Tool definitions take up space in the model's context. Leaving a plugin out of a profile also leaves out its tools, including those provided by its MCP servers. A smaller set sends fewer tool definitions to the model, reducing input tokens and potentially lowering usage costs.
The profile also limits which skills appear in the model's catalog. Clarvis normally lists skill names and descriptions first, rather than loading every skill's full instructions into the prompt.
There is no fixed saving: the final cost also depends on the model, prompt caching, and the rest of the conversation. Native Clarvis tools and MCP servers configured separately from plugins continue to follow their own settings.
Start with the builtin default
builtin:default is the built-in profile. You cannot edit it directly:
enabledPluginsselects exact{ scope, source, name }plugin installations;- enabled plugins contribute all of their agents, skills, MCP servers, capability services, and hooks;
- tools advertised by those plugin MCP servers become available to every effective agent in new runs without editing the saved agent profile;
- all four standalone skill roots are available with their existing precedence.
Create a custom profile to choose a set that does not inherit plugins from the built-in list.
Compose and select in the TUI
Open /extensions and press Enter. The editor walks you through five steps:
- choose whether the selection is local to this workspace or the global default;
- edit a profile, copy the current set, or start with an empty one;
- search marketplace listings, exact installed plugins, and standalone skills in one picker;
- review every agent, plugin skill, standalone skill, MCP server, hook, and capability executable;
- review what will be added and removed, approve project-owned code when required, then apply and reconnect.
Step 3 keeps the draft in memory. Enter adds or removes an installed plugin or standalone skill; on a marketplace row it first asks for .agents/plugins or .clarvis/plugins, installs the plugin, and stages the exact returned installation. Installation is immediate, but nothing becomes active until step 5. Escape returns one level; if the draft changed, Clarvis asks before discarding it.
Applying saves the profile and selects it in one operation. If the profile, selection, or installed files changed since your review, Clarvis asks for a fresh preview. The new set applies to future runs. Work already in progress keeps the set it started with. Selecting a plugin includes all of its hooks.
While Clarvis installs, saves, or reconnects, the footer shows the current step and elapsed time. Wait for it to finish before making another setup change.
From /extensions, press e for the Extension Profile diagnostic and selection browser. It shows the active Extension Profile, fingerprint, selection source, installed versus active counts, every resolved contribution, and any issue. Press / to search definitions and Enter to open the selected snapshot in a scrollable detail view.
| Key | Action |
|---|---|
w | Preview the delta, then use the selected Extension Profile only in this workspace. |
g | Preview the delta, then make a global or builtin selection the global default. |
n | Start the guided editor for a new Extension Profile. |
e | Configure the selected definition, or customize a clone of builtin:default. |
x | Clear this workspace's local selection and preview the fallback. |
d | Delete the selected inactive custom Extension Profile after confirmation. |
r | Refresh definitions and diagnostics. |
The advanced browser's selection preview names every plugin, skill, MCP server, and hook entering or leaving while its footer keeps y apply and n cancel visible. No selection changes before y.
Previews use the same precedence as activation. If a workspace selection already shadows the global default, changing that global default previews the unchanged effective Extension Profile and no active delta. A preview is bound to both selection documents; if either changes before confirmation, Clarvis requires a fresh preview.
Use the guided editor to add or remove plugins and standalone skills. A plugin is selected as a whole: its agents, skills, MCP servers, hooks, and other services enter or leave together.
Author a complete allow-list
An allow-list contains everything the profile may load. An installed extension that is not on this list stays inactive.
Global definitions live at ~/.clarvis/extension-profiles/<name>.json. Workspace definitions live at <workspace>/.clarvis/extension-profiles/<name>.json and may be committed to the repository.
{
"schema_version": 1,
"description": "Research with browser and documentation",
"plugins": [
{ "scope": "global", "source": "agents", "name": "browser" },
{ "scope": "global", "source": "clarvis", "name": "github" }
],
"skills": [{ "scope": "user", "source": "clarvis", "name": "deep-research" }]
}plugins and skills are complete allow-lists, not additions to builtin:default. Plugin refs qualify scope (global or workspace) and source (agents for .agents/plugins, clarvis for .clarvis/plugins); another same-name installation is never substituted. Standalone skill refs qualify both scope (user or workspace) and source (agents or clarvis). A global Extension Profile may reference only global plugins and user-scoped skills. A workspace Extension Profile may combine all four plugin inventories.
Definitions do not inherit. Clone an Extension Profile when you want a variation.
Understand selection and sharing
Clarvis resolves the active Extension Profile in this order:
--extension-profilefor this process;- the local selection for this workspace;
- the global default selection;
builtin:default.
Use a qualified selector when scope matters:
clarvis --extension-profile global:research
clarvis --extension-profile workspace:project -p "Review this change"A bare name checks the workspace definition first, then the global one. --extension-profile does not persist a choice, and the running process cannot overwrite its local or global selection while the override is active.
Workspace definitions are shareable, but the active choice is always machine-local under Clarvis state. Cloning a repository therefore cannot activate its Extension Profile by itself.
Diagnose trust and drift
An Extension Profile is ready, degraded, or invalid:
- a missing plugin or standalone skill is
degradedand stays visibly inactive; - an invalid definition or selection is
invalidand never falls back to a broader default; - an Extension Profile that selects an unapproved repository-owned plugin is
degraded, while any selected global plugin remains active.
After the lightweight startup message field paints, Clarvis proactively fingerprints every installed workspace plugin, whether the active Extension Profile selects it yet or not. One approval covers that exact repository inventory across Extension Profile switches. Changing any workspace plugin byte or executable mode that belongs to the fingerprinted contribution surface changes the fingerprint and requires review again; editing only the Extension Profile allow-list does not. Global plugins are operator-owned installations and need no second workspace approval. Declining opens Extensions so the operator can remove unwanted contributions, and /workspace-trust remains a later fallback for review or revocation.
Clarvis refuses to approve or revoke workspace trust while a run is active, before changing the trust record. When no run is active, that decision causes the selected workspace Extension Profile, or the workspace-derived parts of builtin:default, to be recomposed before the next run.
Clarvis keeps a fixed copy of the resolved extension set, called a snapshot. Its fingerprint identifies the manifests, MCP and hook definitions, source revision, agent files, skill instructions and resources, and trust approval used by that set. If a selected file changes, Clarvis blocks later access until /reconnect loads and checks the new set.
Runs, traces, and session turns record the profile ID and fingerprint. When you resume a session with a different set, Clarvis warns you about the change.