GlassKit Docs — AI coding tools

GlassKit is built for Claude Code, Cursor, and Codex. Per-workspace AGENTS.md, .cursor rules, and Meta's official Web Apps plugin pre-vendored under .claude/skills/.

GlassKit is designed for AI coding tools as a first-class user. Developers who run Claude Code, Cursor, or Codex on the repo get an agent that already knows the Meta Ray-Ban Display platform, the monorepo structure, the typed sensor API, and the launcher conventions, with zero re-prompting.

The wiring is three layers:

Layer	Files	What it does
Repo-wide guidance	`AGENTS.md` + `CLAUDE.md` at the repo root	High-level project shape; conventions every agent should read first
Workspace-specific guidance	`app/AGENTS.md`, `companion/AGENTS.md`, `packages/backend/AGENTS.md`, `packages/glasses-ui/AGENTS.md`	Stack, file map, and platform constraints for that workspace
Cursor rules	`.cursor/rules/glasskit.mdc`	Auto-injected for Cursor agents; mirrors the same guidance in Cursor's preferred format
Pre-vendored Meta plugin	`.claude/skills/*/SKILL.md` (9 directories)	Meta's official Web Apps CLI: runs from inside Claude Code with no install step

The per-workspace AGENTS.md files

Each workspace has its own. Highlights:

`app/AGENTS.md` (~7 KB)

The longest one. It embeds the full Meta Web Apps platform spec (600×600 surface, additive display rules, D-pad focus convention, W3C sensor APIs, what's allowed and what isn't). When Claude / Cursor / Codex generates glasses-side code, this file is what keeps it on-platform. No more "the agent suggested a hover state" or "the agent rendered a 1080p layout."

`companion/AGENTS.md` (~1 KB)

The Next.js companion's conventions: App Router file layout, where to add server vs client components, the server-only boundary for files that touch Stripe SDK / Clerk Backend, the <Show> component (Clerk v7) for conditional render.

`packages/backend/AGENTS.md` (~2 KB)

Convex conventions: identity check via ctx.auth.getUserIdentity() in every query/mutation/action, components own their tables, env vars from env.ts not raw process.env, the ConvexError pattern for caller-visible failures.

`packages/glasses-ui/AGENTS.md` (~2 KB)

The library's API surface, the testing pattern (pnpm --filter @glasskit/glasses-ui test runs vitest on the spatial-focus scoring + sensor equality helpers), how to extend without breaking developers' forks.

`.cursor/rules/glasskit.mdc`

Cursor's preferred rule format. Mirrors AGENTS.md's repo-wide guidance so Cursor users get the same context without parsing plain Markdown.

.cursor/rules/glasskit.mdc

---
description: GlassKit project rules
globs: **/*
---

(rule body — see the file)

If you use Cursor, this rule auto-applies to every file in the repo.

Claude Code: `.claude/skills/`

This is where it gets interesting. Meta ships an official Web Apps plugin for Claude Code with 9 skills. GlassKit pre-vendors the entire plugin under .claude/skills/ so the moment you open the repo in Claude Code, these commands work without any install:

/create-webapp

Scaffolds a new Web App from Meta's template.

/add-ui

Adds a UI screen to an existing Web App.

/add-device-sensors

Wires the sensor APIs (orientation, motion, geo) into a screen.

/add-local-storage

Adds platform-correct localStorage usage.

/connect-api

Wires a backend call from a Web App screen.

/test-on-device

Connects to the glasses and tests live.

/qr-code

Generates the deep-link QR for adding the app to the glasses.

/publish-to-vercel

Deploys to Vercel + walks through getting it on the glasses.

/passcode-for-testing

Sets up a private-tester passcode for the Web App.

Try this in Claude Code from inside the boilerplate repo:

/test-on-device

It works. No setup. The plugin's source is at .claude/skills/<command>/SKILL.md, a small Markdown file Claude Code reads as the skill's implementation.

Provenance + refresh

The plugin is vendored, not symlinked. .claude/SOURCE.md documents:

Where the source upstream is (Meta's plugin repo)
The commit SHA the boilerplate is pinned to
How to refresh (re-vendor) when Meta updates the plugin
The license (LICENSE-meta-wearables-webapp lives next to it)

Refresh is a git clone of the upstream plugin + a cp -R over the existing .claude/skills/ directory. Two minutes.

Using AI tools effectively on this codebase

Open the repo in Claude Code
The CLI auto-loads CLAUDE.md (repo root) which points at AGENTS.md
Workspace-specific AGENTS.md files load when you ask about files inside their workspace
Run /test-on-device, /publish-to-vercel, etc. from anywhere

Recommended pattern

Start tasks with a workspace anchor. "Add a new demo to app/ that combines useDeviceMotion() and useAi()": Claude reads app/AGENTS.md, sees the launcher convention, and produces a file that matches the existing demos' shape.

Open the repo in Cursor
The rule at .cursor/rules/glasskit.mdc auto-loads via the globs: **/* matcher
AGENTS.md files get read on demand when you @-mention a workspace

Codex CLI reads AGENTS.md at the repo root by convention. The per-workspace files load when you specify the working directory.

Any agent that reads markdown context files will pick up AGENTS.md if you point it at the repo root. The format is plain Markdown, with no agent-specific syntax to parse.

Extending the guidance

When you add a new workspace, add <workspace>/AGENTS.md following the existing pattern: stack, file map, conventions specific to that surface. The repo-root AGENTS.md doesn't need updating; it points at the workspace files implicitly.

When you adopt a new convention you want every agent to follow (e.g. "all new Convex actions must rate-limit"), add it to the relevant workspace's AGENTS.md. The agents read these files every session; the next prompt will incorporate the new rule without you needing to re-explain it.

What you DON'T need to do

Set up MCP servers: not required today. The plugin under .claude/skills/ is plain Markdown skills, not an MCP server. If Meta later ships an MCP variant of their Web Apps plugin, the re-vendor process (see .claude/SOURCE.md) would adjust to drop the new server registration alongside the existing skills.
Configure agents per-file: the existing setup applies to every file by default.
Re-prompt with project context: AGENTS.md IS the context.

The headline: clone the repo, open it in your AI coding tool, start working. That's the developer experience GlassKit's wiring is designed to produce.

AI coding tools