Extensions reference
Look up file locations, settings, and activation rules for each type of extension.
Locations and precedence
| Extension | Personal location | Workspace location | Precedence |
|---|---|---|---|
| Settings | ~/.clarvis/settings.json | .clarvis/settings.json | Workspace overrides personal settings |
| Skills | ~/.clarvis/skills/<name>/SKILL.md | .clarvis/skills/<name>/SKILL.md | Workspace Clarvis skills win |
| Interoperable skills | ~/.agents/skills/<name>/SKILL.md | .agents/skills/<name>/SKILL.md | Lower than Clarvis skill roots |
| Clarvis plugins | ~/.clarvis/plugins/<name>/ | .clarvis/plugins/<name>/ | Exact source: "clarvis" inventory |
| Shared plugins | ~/.agents/plugins/<name>/ | .agents/plugins/<name>/ | Exact source: "agents" inventory |
| Agents | ~/.clarvis/agents/<name>.md | .clarvis/agents/<name>.md | Workspace agent overrides the same personal agent |
| Extension Profiles | ~/.clarvis/extension-profiles/<name>.json | .clarvis/extension-profiles/<name>.json | Local workspace selection, then global default |
Both builtin:default and custom Extension Profiles resolve every plugin by exact { scope, source, name } identity. Nothing substitutes for a missing reference, and selecting two same-name installations is invalid because their runtime namespaces collide. Plugin contributions remain below personal and workspace settings.
Activation and trust
| Surface | What makes it active |
|---|---|
| Personal hook | Presence in personal settings.json |
| Workspace hook | Exact workspace fingerprint approval |
| Personal MCP server | Presence in personal settings.json |
| Workspace MCP server | Exact workspace fingerprint approval |
| Global plugin unit | Installed and selected by the active Extension Profile |
| Workspace plugin unit | Selected and the complete repository plugin inventory is approved |
| Plugin hook | Its complete plugin unit is active; there is no separate hook approval |
| Marketplace listing | Never active by itself; explicit install activates the complete plugin |
| Workspace agent | Exact workspace fingerprint approval |
| Standalone skill | Discovered from a skill root; slash visibility follows user-invocable |
Workspace trust covers executable or provider-selecting values declared by a repository: hooks, mcpServers, enabledPlugins, marketplaces, memory.provider, plans.provider, tasks.provider, workspace agents, and every installed repository-owned workspace plugin before Extension Profile selection. Until approval, Clarvis withholds those values and workspace plugins while continuing with trusted personal configuration and selected global plugins. One approval covers the exact workspace plugin inventory across Extension Profile switches; changing its contents requires review again. Subscription-provider declarations are a permanent exception: Clarvis removes them from workspace settings before merge, and approval never grants credential or redirect authority. Configure them globally; a workspace may only select a model already enabled there.
Guided Extensions setup in the TUI
Type /extensions and press Enter to open the hub. The guided editor presents five choices:
| Step | Decision | Persistent effect |
|---|---|---|
| 1 | Workspace-local selection or global default | None; stages selection scope. |
| 2 | Existing, cloned-active, or new empty Extension Profile | None; stages a complete definition and expected revision. |
| 3 | Marketplace plugins, exact installed plugins, and standalone skills | A confirmed marketplace install persists immediately; membership stays in the draft. |
| 4 | Resolved agents, plugin skills, standalone skills, MCP servers, hooks, and executables | None; creates an exact bounded preview. |
| 5 | Complete activation delta and workspace trust | Atomically writes the previewed definition and selection, then reconnects. |
In step 3, search plugins and skills in one picker. The .agents and .clarvis sources stay separate, including items with the same name. Enter adds, removes, or installs the selected item; Escape finishes the selection and keeps the draft for review. A marketplace install asks you to choose .agents/plugins or .clarvis/plugins and adds that installation to the draft.
Step 4 shows all the resources that will become available. A plugin is selected as a whole: its skills, MCP tools, hooks, and services cannot be activated separately.
Step 5 applies exactly what you reviewed. If the definition, inventory, selections, or trust approval change, you need a new preview. Apply is unavailable during an active run or when --extension-profile fixes the process selection.
The footer shows the current operation and elapsed time, without estimating a percentage. Wait for each operation to finish before continuing.
/extensions is the only public route. Its hub opens the Extension Profile browser for definitions, selection, deletion, and snapshot diagnostics; Plugins for horizontal marketplace collections, install/update/uninstall and Extension Profile composition; and MCP for connected tools, prompts, and resources. Plugins uses left/right for collections, up/down for rows, / for collection-local search, and Enter for details and the explicit install-and-activate action.
Extension Profile definition
An Extension Profile definition is strict JSON:
{
"schema_version": 1,
"description": "Research",
"plugins": [{ "scope": "global", "source": "agents", "name": "browser" }],
"skills": [{ "scope": "user", "source": "clarvis", "name": "deep-research" }]
}plugins and skills are complete allow-lists. Plugin scopes are global or workspace, and plugin sources are agents or clarvis. Standalone skill scopes are user or workspace, with the same source names. Global definitions may reference only global plugins and user skills; workspace definitions may combine all four plugin inventories. Definitions are limited to 1 MiB, 64 plugins, and 256 standalone skills.
The immutable builtin:default has no file and activates exact enabledPlugins references plus all standard skill roots. Selection precedence is process --extension-profile, machine-local workspace selection, machine-local global selection, then builtin:default. Definitions can be shared; selections live in Clarvis state and are not repository content.
Selection previews resolve through that same precedence and bind both selection documents. A global write that is already shadowed by a workspace selection therefore previews the unchanged effective Extension Profile; a concurrent change to either selection requires a new preview.
The resolved fingerprint covers the definition, status, issues, applicable trust state, exact plugin manifests and companion declarations, install provenance and resolved source revision, agent files, packaged skill bodies and resources, and selected standalone skill bodies and resources. Contribution drift returns unavailable until reconnect rather than consuming changed bytes under the old fingerprint. Approving or revoking workspace trust is refused with conflict while a run is active; when no run is active, the extension set is recomposed before the next run.
Updating or uninstalling an exact selected plugin is also refused with conflict during a run, and run start cannot race that mutation. After a successful selected-plugin mutation, the old kernel returns unavailable for new runs until reconnect.
settings.json
settings.json is strict. Unknown top-level fields are rejected instead of being ignored. The extension-related fields are:
| Field | Shape | Purpose |
|---|---|---|
hooks | Hook object array | Operator-authored lifecycle commands |
mcpServers | Map of server name to server object | Local and remote MCP connections |
marketplaces | Git URL array | Additional catalogs shown in Plugins |
enabledPlugins | Exact { scope, source, name }[] | Activation list for builtin:default |
MCP server object
| Field | Type | Applies to | Notes |
|---|---|---|---|
type | stdio, http, or sse | All | Defaults to stdio |
command | String | stdio | Required |
args | String array | stdio | Optional argv after the command |
env | String map | stdio | Supports ${VAR} interpolation |
env_vars | String array | stdio | Forwards only the named host variables |
cwd | String | stdio | Optional working directory |
shared | Boolean | stdio | Reuses one process across runs; disables elicitation |
url | HTTP(S) URL | http, sse | Required |
headers | String map | http, sse | Supports ${VAR} interpolation |
bearer_token_env_var | Environment variable name | http, sse | Reads a bearer token without persisting its value |
env_http_headers | Header-to-environment map | http, sse | Reads named header values from the environment |
oauth | Object | http, sse | Optional client, callback, and metadata configuration |
resources | Boolean | All | Defaults on; false suppresses resource tools |
startup_timeout_sec | Positive number | All | Per-server startup timeout, at most 3600 seconds |
tool_timeout_sec | Positive number | All | Per-server tool timeout, at most 3600 seconds |
enabled_tools | String array | All | Retains only named advertised tools |
disabled_tools | String array | All | Removes named tools after the allow list |
enabled / required | Boolean | All | Server activation and required-readiness policy |
stdio forbids url and headers. Remote transports forbid command, args, env, and shared.
expandVariables defaults to true and applies to authored env and headers; explicit credential references still resolve when a portable plugin disables general expansion. enabled_tools and disabled_tools cannot overlap.
Remote HTTP/SSE servers may request OAuth during connection, catalog discovery, or a later request. Local interactive and --print hosts open the authorization page, require HTTPS for every OAuth endpoint and redirect except loopback HTTP, validate state, use PKCE, and repeat the refused request once after the callback. Configured MCP headers apply only to resource requests on their configured origin; OAuth exchanges do not inherit them, even on that origin, and SDK-defined authorization headers take precedence. Credentials live in ~/.clarvis/state/mcp-oauth.json, keyed by workspace, owner, and canonical server URL; they are not settings. A host without a browser opener reports that interactive authorization is unavailable. In the interactive TUI, an OAuth challenge never holds a model run open: the server is inactive for that run, one transient sanitized warning is shown outside the transcript, and a completed flow is available to a later run.
Hook object
| Field | Type | Notes |
|---|---|---|
event | Event name | Required |
type | command or mcp_tool | Defaults to command |
command | String | Required for command hooks |
command_windows | String | Windows-specific command override |
async | Boolean | Detaches a command hook except run_end / SessionEnd |
status_message | String | Bounded display metadata; not transcript content |
additional_context_limit | Integer from 0 to 65536 | Narrows captured command output |
plugin_root, plugin_data | Bounded path strings | Normally adapter-supplied; exported through PLUGIN_* and CODEX_PLUGIN_* aliases without creating a sandbox |
server, tool, input | MCP target and input | Required target for mcp_tool; input supports event placeholders |
match.tool | String or string array | Exact name or * glob; tool events only |
match.args | String map | JavaScript regex per argument; all entries must match; tool events only |
timeout_ms | Integer from 1 to 60000 | Optional timeout |
on_failure | pass or deny | deny is valid only for gate events; invalid on mcp_tool |
Events:
| Class | Events | Effect |
|---|---|---|
| Gate | pre_tool_use, post_tool_use, pre_finalize, pre_delegate_task | May pass, advise, or deny |
| Observer | run_start, run_end, post_compact, subagent_start, subagent_complete, model_call_error, budget_exhausted, user_steer | Output cannot block the run |
| Context | session_start | May add pinned entry context |
| Compaction context | pre_compact | May add context to that summarization pass |
| Prompt observer | user_prompt_expansion | Observes a user-invoked skill command |
Only pre_tool_use may replace pending tool arguments with a rewrite verdict. A single settings or plugin source may declare up to 64 hooks; a run uses at most 128 merged hooks, with operator hooks before plugin hooks.
An mcp_tool hook calls a server already connected to the run. It does not trigger other tool hooks and does not block the run if it fails. Async command hooks share a limit of eight background processes. run_end always waits for completion so the command is not lost during shutdown.
Compatible hook payloads spell built-in tools as external names such as Bash, Read, and Skill, and MCP tools as mcp__<server>__<tool>. CLARVIS_HOOK_TOOL retains the Clarvis wire name; CLARVIS_HOOK_TOOL_FULL_NAME carries the stable dotted MCP name when one exists.
SKILL.md
Every skill is a directory containing SKILL.md with YAML frontmatter and a Markdown body.
| Field | Required | Notes |
|---|---|---|
name | Yes | Letters, numbers, ., _, and -; maximum 128 characters |
description | Yes | Short discovery text |
agent | No | Agent for slash invocation; may use <plugin>:<agent> |
version | No | Skill version metadata |
license | No | License metadata |
argument-hint | No | String or string array shown for the slash argument |
user-invocable | No | Defaults to true |
allowed-tools | No | Compatibility metadata; does not change runtime permissions |
tools | No | Alias of allowed-tools |
The body may use $ARGUMENTS or . Conventional resource directories are scripts, references, assets, and examples. An agents sidecar directory is presentation metadata for the host and is never exposed as a skill resource. Its first YAML file may also declare dependencies.tools entries of type: mcp; the skill is withheld from a run whose selected MCP surface does not contain that server.
Skill resources may be at most 8 MiB per file and 32 MiB in the owning snapshot. Model-facing reads return pages of at most 256 KiB and 50,000 decoded characters. Helper execution is opt-in per exact skill directory and still passes through command review and the native sandbox.
plugin.json
plugin.json is tolerant: Clarvis reports unknown fields but does not act on them. name is the only required field after normalization. A native Git install uses it as the directory name; an existing foreign layout may omit it, in which case Clarvis derives it from the install directory. That directory is always the host-owned runtime namespace.
Clarvis first uses a readable root plugin.json that claims the portable Agent Plugins schema. Otherwise it uses .clarvis-plugin/plugin.json when present. Without either authoritative form, it examines the root manifest plus directories shaped like .<host>-plugin/plugin.json, selects the single readable manifest with the most supported contribution directives, and uses root-then-name order to break a tie. Manifests are never merged.
| Field | Type | Purpose |
|---|---|---|
name | Lowercase identifier | Plugin identity and namespace |
version | Non-empty string | Optional display version |
description | Non-empty string | Optional summary |
author | String or { name, email?, url? } | Optional author display |
homepage / repository | Non-empty string | Optional discovery links |
license / keywords | String / string array | Optional display metadata |
interface | Bounded presentation object | Names, copy, links, prompts, colors, and visual assets |
skills | Relative directory or directory array | Collections or individual skills; up to four effective roots |
mcpServers | MCP server map or relative document path | Plugin-provided servers |
hooks | Hook array, document, or relative document path | Plugin-provided hooks |
bootstrapSkill | Skill name | Injects one plugin-owned methodology skill before response |
capabilityExecutables | Capability-to-executable map | Optional persistent capability services |
capabilityRunPolicies | Plans skill-policy map | off, on, or review for plugin skill runs |
Relative paths resolve from the selected manifest's directory first and remain confined to the plugin root. Conventional contribution directories are agents/ and skills/. If mcpServers is absent, Clarvis tries .mcp.json and then mcp.json. If the manifest contributes no hooks, Clarvis also reads hooks/hooks.json. Compatible event-keyed hook documents may be inline, wrapped in a hooks object, or named by one or more relative paths. In a translated event-keyed document, a leading command such as ./hooks/session-start.cmd is anchored to the plugin root while the hook's working directory remains the workspace. Native Clarvis hook arrays are kept exactly as declared.
A Codex-style .mcp.json companion may be a direct map or wrap it under mcpServers or mcp_servers; URL-only entries infer HTTP, http_headers becomes headers, and supported OAuth camel-case fields normalize to the engine's snake-case fields. A shape-matched borrowed-host manifest may translate an exact whole stdio environment value ${user_config.key} only when that userConfig entry has type: "string". It becomes ${DEST_ENV} and reads the operator's existing environment value; defaults and secret metadata are never imported. Unsafe references withhold only the affected MCP server.
Capability executable declaration
{
"capabilityExecutables": {
"memory": {
"command": "quality-memory",
"args": ["serve"],
"env": {
"DATABASE_URL": "${DATABASE_URL}"
},
"timeout_ms": 30000,
"platforms": {
"win32": {
"command": "quality-memory.exe"
}
}
}
}
}command is required. args and env default to empty collections, and timeout_ms defaults to 30000 milliseconds. A capability service remains inert until the plugin is selected by the active Extension Profile and selected as the provider for that capability.
marketplace.json
A Clarvis installation includes https://github.com/getclarvis/marketplace.git as its official marketplace source. The source is available without a settings entry, but its catalog is fetched only for browsing and none of its plugins are installed, selected, or approved automatically. settings.json may add other marketplace sources.
A marketplace repository publishes marketplace.json at its root:
| Root field | Required | Purpose |
|---|---|---|
name | No | Catalog identifier; Clarvis supplies one when absent |
displayName | No | Human-facing title |
description | No | Catalog summary |
plugins | No | Listing array; defaults to empty |
| Listing field | Required | Purpose |
|---|---|---|
name | Yes | Expected installed plugin identity |
source | Yes | Git/local string, or url, git-subdir, local, or npm descriptor |
path | No | Confined Git subdirectory for compatible string-source syntax |
description | No | Listing summary |
displayName | No | Human-facing plugin title |
homepage | No | Project page |
category | No | Presentation grouping |
policy | No | Installation and authentication display policy |
interface | No | Bounded publisher, legal, prompt, color, and asset metadata |
Marketplace files are tolerant and report unknown or defaulted fields. A listing without a usable name or source is omitted. Confined relative local sources are installable; escaping or indeterminate targets remain visible but have no install action. Git descriptors accept at most one ref or full sha. Npm descriptors accept an optional safe version and credential-free HTTPS registry. AVAILABLE, INSTALLED_BY_DEFAULT, NOT_AVAILABLE, ON_INSTALL, and ON_FIRST_USE are display policy only: catalog loading never installs or authenticates anything.
Namespaces
| Contribution | Effective name |
|---|---|
| Settings MCP server | <server> |
| Settings MCP tool | <server>.<tool> |
| Plugin MCP server | <plugin>:<server> |
| Plugin MCP tool | <plugin>:<server>.<tool> |
| Plugin agent | <plugin>:<agent> |
| Plugin skill | Authored skill name; normal skill precedence applies |