Microsoft Clarity is the session replay engine behind the hosted analytics product

Four packages that split capture, decode and playback

Clarity is not a single script. It is a four-package monorepo, and the README describes each one in a way that tells you almost everything about how the system works.

clarity-js is the instrumentation that goes on your website. It tracks user interactions and layout changes. clarity-decode runs, usually on a server, and decodes incoming data back into its original format. clarity-visualize takes the decoded data and turns it back into pixel-perfect session replay. clarity-devtools is a Chromium browser extension that generates live captures against any website.

That split is the interesting architectural decision. The browser side sends a compact encoded representation, the server side reconstructs structure, and the viewing side does the rendering. Nothing about the replay requires the capture to have happened in your browser, which is what makes the devtools extension possible and what makes the whole pipeline testable without a real user.

The library is described as being written in TypeScript with two key goals, privacy and performance, and the README says plainly that it is the same code that powers Microsoft's hosted behavioral analytics solution at clarity.microsoft.com. That matters for evaluation: this is production code from a shipped product, not a demo.

What the instrumentation records, and what it masks by default

The topics are heatmap, session-replay and clarity, and the README describes the library as generating aggregated insights from DOM mutations and user interactions. That phrasing is precise in a way most session replay descriptions are not: the signal comes from changes to the document structure and from what the user did to it, not from a video recording of the screen.

DOM mutation observation is the interesting part. Because the recording is derived from how your page's elements change rather than from pixels, a replay can be reconstructed as real DOM, which is why the visualization is described as pixel-perfect while still being navigable and inspectable rather than a flat video.

On privacy, the README is short but concrete. Sensitive content on the page is masked before uploading to the server, by default, and there are several masking configuration options so you stay in control of your data. Default masking happening before the upload boundary is the detail that matters most for anyone evaluating this for a regulated site, because it means the unmasked text never leaves the browser in the normal path.

The hosted service and this library share the code, so the behaviour you configure here is the behaviour the product has.

Building and testing the monorepo with Lerna and Playwright

The repository is a Yarn workspaces monorepo orchestrated with Lerna, and the root `package.json` at version 0.8.71 exposes the build and test commands. Each package builds individually, and there is also a streaming build across all of them:

yarn build:js
yarn build:decode
yarn build:visualize
yarn build:devtools

Tests run through Playwright rather than a unit test runner, which follows from what the software does: replay correctness is a browser question. The root scripts map directly onto the four packages:

yarn test
yarn test:ui

There is a `playwright.config.ts` in the tree along with a `test/` directory and a `scripts/` folder, and the README's own release procedure is a version bump followed by a commit, a push and a pull request:

yarn bump-version

That command is a thin wrapper over `scripts/bump-version.ts` run through ts-node. Development dependencies are modest and modern: Playwright, Lerna, parse-url and ts-node.

No published package means no quick start

Here is the practical obstacle. The root `package.json` declares the project private, the repository publishes no GitHub releases, and the README contains no install instructions and no snippet for dropping a tracking tag onto a page. There is no npm package name given for the hosted product's script either, only the project site.

So there is no documented path from clone to running analytics. What exists is a source repository with a working build across four packages, a test suite, and the instrumentation you would have to wire into your own pages and point at your own decode service.

That is a coherent thing for Microsoft to publish, since the hosted product is the supported distribution channel and the open source route exists mainly for transparency, self-hosting and contribution. It does mean the README's framing and the practical experience diverge: the page reads like an invitation to use the library, while the actual commitment is a pipeline to run and host yourself.

If you want to see the behaviour before building anything, the README links a live demo project with impressions over the last three days, and it ships two example sessions, one from CNN on the web and one from Cook with Manali on mobile, to show what the captured telemetry looks like once visualised.

A devtools extension for capturing any site without instrumentation

clarity-devtools is the package that makes the rest of the project legible. It is a Chromium based browser extension that generates live captures against any website.

That is a small feature description with large consequences for evaluation. You can point it at a site you do not control, produce a capture, and replay it, without deploying an instrumented build first. For anyone evaluating whether session replay is useful to them, that removes the setup step entirely, and for anyone writing their own tooling it is a working reference for how a capture session gets assembled outside the normal deployment path.

It also explains why the decode and visualize packages are separable. If the capture can come from a browser extension rather than from a deployed script, the encoded payload has to be portable and the reconstruction has to happen somewhere the extension can reach, which is exactly the divide the package structure describes.

The README's design principles and architecture documentation are hosted on the project site rather than in the repository, so the in-repo explanation of how the encode format and reconstruction work is thinner than the package list implies.

Contributing conventions and where the project stands

The repository is set up for outside contributions in the ways that matter for a project of this size. There is a CONTRIBUTING guide, a CODE_OF_CONDUCT that adopts the Microsoft Open Source Code of Conduct, a `.editorconfig` equivalent through its tooling, `yarn.lock` for reproducible installs, and a NOTICE.txt alongside the MIT LICENSE.

It also ships agent-oriented configuration, which is increasingly common and worth knowing about if you work with an assistant on the codebase. A CLAUDE.md holds project context and development guidelines, and a `.mcp.json` configures a Git MCP server. The README documents how to enable it, with a JSON block for auto-enabling project MCP servers in local settings, plus the prerequisite of Python 3 and installing a Git MCP server package with pip3.

Whether that tooling is useful to you depends entirely on whether you are running an assistant against the repo. What it does tell you is that the maintainers expect work on this codebase to happen in a fairly guided way, with build commands, testing and architecture already written down in a file that gets loaded automatically.

The project is not archived and the last push was on 2026-09-23, so it is receiving work even though it publishes no versioned releases.

Editorial conclusion

Clarity is worth reading and worth self-hosting if you need session replay where the data must not leave your infrastructure, and it is the reference implementation to study if you are building replay tooling at all. It is not a drop-in analytics script for a production site, because the repository is a private monorepo with no published releases and the README documents no install route, so adopting it means building the packages and running the decode and visualization pipeline yourself. Two things to check first: that your page markup is compatible with how the instrumentation classifies elements, and that the masking configuration covers every field on your site, since the default is to mask sensitive content before upload rather than after. If a hosted tool is acceptable, clarity.microsoft.com runs this same code and removes the pipeline work.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. microsoft/clarity on GitHub
4. Project website
5. README