Scopes and workspace trust
Choose settings for all your projects or just one, and review code supplied by a repository.
Choose the narrowest useful scope
Clarvis separates personal defaults from project-specific behavior:
| Scope | Default location | Use it for |
|---|---|---|
| Global | ~/.clarvis/ | Your providers, defaults, agents, skills, workflows, plugins, Extension Profiles, and settings |
| Workspace | <project>/.clarvis/ | Overrides, Extension Profile definitions, and extensions that should travel with one repository |
If CLARVIS_HOME is set, it replaces ~/.clarvis for Clarvis-owned personal files. It does not move the workspace .clarvis directory or .agents interoperability directories.
Use the scope control shown in a settings panel before saving. Prefer global scope for credentials and personal defaults. Prefer workspace scope only when collaborators should receive the same project behavior.
Understand precedence
Effective configuration starts with product defaults, then personal configuration, then workspace configuration. A workspace value normally wins for the same scalar choice. Maps and ordered lists may merge according to their own field rules; the settings panels show the effective value and its source when that distinction matters.
The same pattern applies to user-authored content:
- a workspace agent overrides a personal agent with the same name;
- a workspace Clarvis skill overrides personal and interoperable skills with the same name;
- both
builtin:defaultand custom Extension Profiles resolve plugins by exact scope, filesystem source, and name; a same-name installation never substitutes for another; - operator settings still outrank every plugin contribution.
Global and workspace Extension Profile definitions are authored content. The active global default and per-workspace selection are machine-local state, so committing a workspace definition does not activate it for someone who clones the repository.
Controls changed for the next run do not rewrite an already-active run. Check the scope and the header before starting work when you are switching between repositories.
Review workspace trust
A cloned repository should not gain authority merely by containing configuration. Clarvis fingerprints the workspace path, the parts of its configuration that can execute code, select an executable provider, or change an agent's system instructions, and the complete repository-owned workspace plugin inventory before Extension Profile selection.
When this protected content is new or has changed, Clarvis asks you to approve its fingerprint: an identifier for that exact content. Approval makes it available to future runs. Declining opens Extensions so you can remove unwanted items. Use /workspace-trust later to review or revoke approval. If the repository declares none of the protected content, there is nothing to approve.
Approve and revoke are refused while a run is active, before the trust record changes. When no run is active, either decision causes the selected workspace Extension Profile, including the workspace-derived plugin surface of builtin:default, to be recomposed before the next run.
Until approval, Clarvis withholds these workspace contributions and continues with trusted personal configuration:
- hooks and MCP servers;
- builtin plugin activation, marketplace sources, and every repository-owned workspace plugin;
- executable or plugin providers for Memory and Plans;
- a Tasks provider;
- workspace agent files.
Subscription-backed provider declarations are a stronger exception: workspace files never gain the ability to reuse or redirect your personal subscription credentials, even after workspace approval. Configure subscription providers globally.
Approval is intentionally content-specific. It does not select a plugin that is absent from the active Extension Profile, and plugin hooks still follow their selected plugin atomically. Global plugins are operator-owned and need no additional workspace approval. One approval covers the exact complete workspace plugin inventory across Extension Profile switches; adding a plugin or changing its fingerprinted contribution surface requires review again.
Trust is not a review of every setting
Workspace trust protects the executable and provider-selecting surface above. Other project settings still participate in normal precedence. In particular, review workspace sandbox and command-review settings yourself; they are not made safe merely because the trust command reports an inert workspace.
Keep secrets personal
Do not commit credentials to workspace settings. Configure provider credentials through /settings/providers, or reference environment variables where a format supports ${NAME}. Workspace approval never turns a repository file into an appropriate secret store.
Use /storage to inspect whether Clarvis credential files are present and their permission posture without revealing paths, sizes, or contents. POSIX stores apply owner-only mode bits; Windows relies on the user's profile access controls.