AI coding tools all want roughly the same things: skills, agents, commands, and MCP server declarations. Each expects them in its own format, in its own directory. So those files get copied between projects and between tools by hand, with no version, no upgrade path, no integrity check, and no clean way to take them back out.
A facet packages those extensions into a single versioned unit. The facet CLI installs facets into your project through adapters for Claude Code, OpenCode, and Codex, and resolves them from the free public registry at agentfacets.io.
Agent Facets is in open beta. Public publishing remains free. Personal private publishing is free during the beta, and paid private publishing for teams is available by request.
- Reproducible.
facets.jsonrecords what your project depends on.facets.lockpins exact versions and integrity hashes, so teammates and CI get identical results. - Tool-independent. Install a facet once and each connected adapter materializes the asset types it supports, instead of maintaining a copy per tool.
- Verified and deliberate. Every archive is integrity-checked against what was published, and a new or changed MCP server declaration is never written until you approve it.
- Manageable. Move between versions with
facet update, and remove a facet cleanly: only the files and config entries your project actually owns are deleted.
# Install the CLI (macOS/Linux)
curl -fsSL https://agentfacets.io/install | bash
# Or on any platform, including Windows
npm install -g agent-facets
facet --versionConnect the AI tool you use, then add a facet from the registry:
facet adapter add claude-code # or: opencode, codex
facet add cowsayfacet add resolves, verifies, records, and installs in one step:
cowsay installed. Updated facets via 1 adapter ✓
1 installed · 4 assets written
+ 1 skill · 1 agent · 2 commands
Those assets land where your tool already looks for them, so the new command works immediately:
/cowsay hey there
facet install # restore a project's facets after a clone or a pull
facet update # move to newer releases within the ranges facets.json allows
facet remove cowsay # take a facet back out, along with the files it owns
facet list # see what is declared and what resolvedFull documentation lives at docs.agentfacets.io.
Start here
- Quickstart walks through the above in under five minutes.
- Setup covers the CLI, adapters, and registry tokens.
- Key concepts explains facets, the two project files, assets, and adapters.
Using facets
- Install facets covers adding, pinning, collisions, MCP approval, and CI.
- CLI reference documents every command, flag, and exit code.
- Troubleshooting maps common errors to fixes.
Authoring and publishing
- Create a facet covers scaffolding, authoring, and building.
- Publish a facet covers authentication, publishing, and versioning.
Extending and integrating
- Build a custom adapter for a tool we do not support yet.
- Adapter SDK reference documents the adapter contract.
- Specification defines the artifact formats, integrity model, and install guarantees.
Project status
- Agent Facets is currently in open beta. Follow the roadmap and changelog.
- Browse the registry to find facets, or publish your own.
This repository holds the CLI, the protocol reference implementation, and the first-party adapters.
| Package | Purpose |
|---|---|
packages/protocol |
Reference implementation of the facet specification: schemas, integrity, archive format |
packages/engine |
Install pipeline, registry client, adapter machinery, cache |
packages/cli |
The facet binary: commands, terminal UI, error formatting |
packages/adapter |
The published adapter SDK |
packages/adapters/* |
First-party adapters for Claude Code, OpenCode, and Codex |
See CONTRIBUTING.md to get set up.
We use Greptile to review code changes here. They generously provide free reviews to OSS projects.