This guide covers installing facets into a project: setting up an adapter, searching the registry, adding facets, and managing the project manifest and lockfile.
Install an adapter
An adapter is the bridge between facets and your AI coding tool. It tells the facet CLI where to place assets on disk so your tool can find them. You need at least one adapter installed before you can add facets.
Without a specifier, facet adapter install launches an interactive picker listing the first-party adapters:
| Name | Package | Tool |
|---|
opencode | @agent-facets/adapter-opencode | OpenCode |
claude-code | @agent-facets/adapter-claude-code | Claude Code |
codex | @agent-facets/adapter-codex | Codex |
facet adapter install opencode
adapter.js, and placed in ~/.facet/adapters/<name>/. See facet adapter install for all specifier formats (npm packages, git URLs, local paths).
Search the registry
facet search results show the facet name, latest version, asset counts, and the install command:
viper-plans v1.2.0
2 skills, 1 agent, 1 command
-> facet add viper-plans
rezi v0.5.0
3 skills
-> facet add rezi
facet search with no arguments to list all published facets.
Add a facet
facet add is the single command for bringing a facet into your project. It writes the entry to facets.json and runs the install pipeline in one step. There is no separate “install after add” step.
Source grammar
| Form | Example |
|---|
| Registry name | facet add viper-plans |
| Registry name with version | facet add viper-plans@1.2.3 |
| Major-pinned wildcard | facet add viper-plans@1.* |
| Scoped registry name | facet add @acme/deploy-tools |
| GitHub shorthand | facet add github:owner/repo#main |
| HTTPS git URL | facet add https://github.com/owner/repo.git |
| Local path | facet add ./local-facets/my-plans |
facets.json. Wildcards like 1.* are preserved in facets.json; the specific resolved version goes in the lockfile.
You can add multiple facets at once:
facet add viper-plans rezi planner@2.*
facet add for the full source grammar and edge cases.
Understand the project files
After running facet add, your project contains two new files:
facets.json
The project manifest. Maps facet names to source specifiers:
{
"facets": {
"viper-plans": "1.2.3",
"rezi": "0.5.0",
"@acme/deploy-tools": "2.0.0"
}
}
@scope/name) appear as keys verbatim, including the leading @.
facets.lock
The lockfile. Records the exact resolved versions, integrity hashes, and asset lists for every installed facet. It ensures reproducible installs across machines.
The lockfile is written by facet install and facet add. You should commit both facets.json and facets.lock to version control so that all team members and CI environments get the same versions.
The lockfile honors the manifest: a pinned entry is reused as long as it satisfies the manifest specifier. When the manifest and lockfile disagree (you bumped a version or widened a wildcard), facet install re-resolves the manifest specifier and updates the lockfile.
Reinstall after git clone
After cloning a project that already has facets.json and facets.lock:
facet install fetches and materializes every declared facet into your installed adapters. The lockfile ensures you get exactly the same versions your teammates resolved.
For CI environments, use frozen mode to guarantee the lockfile and manifest are already in agreement:
facet install --frozen-lockfile
facet add, a hand-edited manifest, or drifted local content fails the build instead of silently mutating the lockfile.
List installed facets
facet list shows all facets declared in facets.json. When facets.lock is present, displays the resolved version from the lockfile. For entries not yet installed, shows the source specifier so you know to run facet install.
Remove a facet
facet remove removes the facet from facets.json, deletes its assets from every connected adapter, and rewrites the lockfile without it. Aliased as facet rm.
# Remove a single facet.
facet remove viper-plans
# Remove several at once (all-or-nothing).
facet remove viper-plans rezi
facets.json, the command fails and changes nothing.
Manage adapters
List installed adapters:
Remove an adapter:
facet adapter remove opencode
