Tessera

UI retrieval for coding agents.

Search, inspect, and reuse real interface components from existing UI libraries before generating them from scratch.

Tessera v0.1.0 is available on npm. 73 components across five libraries, verified against live upstreams.

Coding agents write a lot of UI from scratch that already exists, and it shows. A pricing section, a terminal hero, a command palette — these are solved problems sitting in five different component libraries, each with its own docs site and its own copy-paste instructions.

Tessera gives an agent a way to search those libraries, see why a component ranked where it did, check the licence and dependencies, and pull the real source. One command, no account, no network call until you actually fetch something.

The rule the project is built around:

Reuse composition, not identity.

Take the structure, drop the branding. A retrieved component gets adapted to your design language, never shipped as the library's demo.

Why

An agent asked to "build a dark developer-tool hero" will happily write one from nothing, badly, while aceternity/terminal and magicui/terminal sit two searches away. The gap is not that good components are missing — it is that nothing tells the agent they exist in a form it can act on.

Tessera fills that gap without becoming a design system, a hosted service, or a build step. It is a local index with an honest licence record and a fetch command.

Related MCP server: CRUX MCP Server

What it looks like

$ tessera search "dark technical terminal hero"

1. magicui/terminal — Terminal (0.612)
   category: terminal | source: magicui | frameworks: react
   motion: unknown | deps: 0 | license: MIT, OSI-approved, redistribution permitted
   artifact: retrievable (shadcn-registry)
   why: exact category match: terminal; matches aesthetics: terminal; no required runtime dependencies

$ tessera fetch aceternity/terminal

aceternity/terminal — 1 file(s) from aceternity
upstream: https://ui.aceternity.com/registry/terminal.json
license: LicenseRef-Aceternity, not OSI-approved, redistribution restricted
files:
  components/ui/terminal.tsx (13977 bytes)

! This license permits use but restricts redistributing the source files.
  Adapt it into your project; do not republish it as a component library.

Tessera wrote these files only because you asked. Nothing was installed or executed.

Install

No clone required:

npx -y @tessera-dev/cli search "dark technical terminal hero"

For repeated use, install globally:

npm install -g @tessera-dev/cli
tessera doctor

doctor checks the runtime, which registry is loaded, that every component validates, that licences carry evidence, and that the MCP server starts.

Other ways to install

GitHub release tarballs, for offline or manual installs. Download the four tarballs from the release and install them together — the CLI depends on the other three packages:

npm install -g ./tessera-dev-registry-0.1.0.tgz ./tessera-dev-core-0.1.0.tgz \
               ./tessera-dev-mcp-0.1.0.tgz ./tessera-dev-cli-0.1.0.tgz

From source, for contributors:

git clone https://github.com/radityama/tessera && cd tessera
pnpm install && pnpm build
node packages/cli/dist/cli.js doctor

See docs/installation.md.

CLI

tessera search "<query>"        # rank components; works offline
tessera inspect <id>            # full metadata, licence and provenance
tessera similar <id>            # alternatives
tessera add <id> --dry-run      # what installing it would involve
tessera fetch <id>              # retrieve the real source
tessera mcp                     # start the MCP server
tessera doctor                  # diagnose the installation

Only fetch and mcp reach the network, and only when you ask. See docs/cli.md.

MCP

npx -y @tessera-dev/cli mcp

Six tools, stable names:

Configure it once:

{
  "mcpServers": {
    "tessera": {
      "command": "npx",
      "args": ["-y", "@tessera-dev/cli", "mcp"]
    }
  }
}

This runs the published package — no checkout needed. If your harness cannot find npx (GUI apps often get a minimal PATH), use an absolute path to npx, or point the config at an installed binary ("command": "tessera") or a source checkout ("command": "node", "args": ["/path/to/tessera/packages/cli/dist/cli.js", "mcp"]) as a fallback.

The key name differs per harness — mcpServers, servers, mcp, context_servers, or a TOML [mcp_servers.x] table. Each has a page in docs/integrations/, checked against that harness's own current documentation.

Agent Skill

skills/tessera/SKILL.md teaches an agent the workflow, not just the tools: decompose the page, decide the design language, search, read the score reasons, check the licence, retrieve, adapt, then run a cohesion pass. It explicitly tells the agent to reject a highly ranked component that clashes with the page, because "call search_components and paste rank #1" produces exactly the incoherent result Tessera exists to prevent.

Install it where your harness looks for skills, or use the project-rule snippet for harnesses that have no skill support.

Example workflow

"Build a dark developer-tool landing page with a technical hero and a terminal."

  decompose → hero, feature grid, pricing, footer
  design language → dark, 12px radius, hairline borders, low motion
  search_components "dark technical hero terminal subtle motion"
  → 5 candidates with scores and reasons
  inspect aceternity/terminal → LicenseRef-Aceternity, redistribution restricted
  get_component_artifact magicui/terminal → real files + deps + MIT
  adapt → swap the palette for the project's tokens, drop the demo copy
  cohesion pass → the top-ranked hero clashes on radius; take the second

How retrieval works

Search and retrieval are deliberately separate.

provider registry  →  pnpm registry:sync  →  pinned snapshot  →  local search
                                                               ↘
                                                                 fetch on request

Search never touches the network, so it is deterministic and testable offline. fetch is the only network path: it resolves the upstream URL from the registry, never from the caller, validates every redirect against an allowlist of hosts the registry already advertises, caps the response size, and validates the payload before returning it. Retrieved code is never executed, written unprompted, or installed.

See docs/retrieval.md.

Supported sources

Every record traces to a real upstream item. Licences carry an evidence URL or are recorded as unknown — a known licence without evidence fails validation and the build. The registry has no hand-written entries; pnpm registry:sync generates it.

Sources and their evidence: docs/sources.md.

Supported coding agents

Claude Code is runtime-verified. Ten more are config-verified against their current official docs, and the compatibility matrix marks the difference rather than claiming universal support.

Claude Code · Codex · Cursor · Windsurf · OpenCode · Cline · Roo Code · VS Code Copilot · Gemini CLI · Zed · Continue · any MCP client

Architecture

registry ← adapters
   ↑
 core ──→ cli
   │      mcp
   └──→ web explorer

Dependency direction is one-way. core contains no provider-specific branches — provider behaviour lives in adapters, and ranking stays provider-neutral. The CLI, MCP and explorer all call the same searchRegistry; a parity test fails the build if the explorer's bundled copy ever diverges.

Safety and licensing

• Tessera indexes metadata. It does not store or redistribute component source.

• Every licence carries evidence or is marked unknown. Unknown licences rank lower and warn.

• status and redistribution are separate, because a licence can be known and still forbid reuse.

• fetch never overwrites a file silently, and rejects upstream paths that escape the output directory.

• No shell execution, no dependency installation, no telemetry.

See SECURITY.md and docs/security-licensing.md.

Known limitations

v0.1 is a working local loop, not a finished product. The honest list:

• Five sources, React only. Enough to prove the thesis, not to cover the ecosystem.

• fetch does not resolve registry dependencies. A component that declares them returns its own files only; the artifact reports them, and the shadcn CLI would install them transitively.

• Declared dependencies can under-report imports. magicui/terminal imports motion, which its registry entry does not declare.

• Lexical ranking. Deterministic and explainable, but it does not understand that a query naming several intents should prefer components satisfying more than one.

• add never mutates. Dry-run only.

• Ten of eleven harnesses are config-verified, not runtime-tested. The compatibility matrix says which is which.

Development

pnpm install
pnpm build          # required before test: the registry bundle is built here
pnpm test
pnpm release:check  # the full gate
pnpm dogfood        # end-to-end against live upstreams (network)

See CONTRIBUTING.md. The one rule that matters most: do not invent metadata. Unknown is a correct answer; a plausible guess is not.

Roadmap

v0.1 proves the local loop. Deliberately excluded: embeddings, vector search, a hosted index, automatic installation, screenshot similarity.

See docs/roadmap.md.

License

MIT.

Tessera is not affiliated with any of the component libraries it indexes. Their names and links identify where metadata comes from, nothing more.