---
name: graspable
description: Build, edit and verify 3D, AR, VR and AI glasses projects with Graspable's local CLI or MCP server. Use for Graspable projects, WebXR apps, interactive films, Ray-Ban Meta companion apps and Meta Ray-Ban Display web apps.
---

# Build with Graspable

Graspable edits real project files on the person's computer. Use the connected Graspable MCP tools when available, or `grasp` through your command tool. Preserve the person's chosen project, AI account and approval policy.

## Connect and choose a project

- If Graspable is not installed, direct the person to [Download](https://graspable.dev/download). The app installs `grasp` from **Settings → Plugins and connectors → Use Graspable from other tools**. Agent-operated installers are documented in [CLI](https://graspable.dev/docs/cli.md).
- Connect a stdio MCP client to command `grasp` with arguments `["mcp"]`. The website is documentation, not a hosted MCP endpoint. See [MCP setup](https://graspable.dev/docs/mcp-server.md).
- Call `list_projects` before creating a duplicate. Use `list_templates` for current template IDs and `list_files`, `read_file` and `project_history` to understand an existing project before editing it.
- For a new free web project, call `create_project` with `name` and template `react-xr-developer`. Wait for that project's `install: done` in `list_projects`; report an installation error instead of waiting indefinitely. Premium or native creation may require the person to create the project in the app first. Do not request raw sign-in tokens or bypass plan checks.

## Choose the target before the template

Use the person's device and intended interaction to choose the project. AI glasses, display glasses and immersive headsets use different runtimes.

| Intended experience | Template ID to look for in `list_templates` | Runtime and checks |
|---|---|---|
| A timer, checklist or short instructions on Meta Ray-Ban Display | `display-glasses-developer` | A 600 by 600 web app. Check navigation and readable text in its browser preview; verify input and installation on the glasses. It has no camera or microphone access. |
| A phone companion using Ray-Ban Meta or Oakley Meta glasses | `meta-glasses-developer` | An Expo companion using Meta's Device Access Toolkit. The browser preview simulates glasses; use **Run on my phone** in Graspable for a device build. |
| A photo journal with spoken notes | `glasses-journal-developer` | The same companion route with a worked example. Handle unavailable experimental speech and input features. |
| An immersive 3D scene for a WebXR headset | `react-xr-developer` | A React Three Fiber scene. Check the browser result, then the intended headset interactions. |

Read [Meta glasses](https://graspable.dev/docs/meta-glasses.md) before changing a glasses app. The three glasses templates require Builder or higher; create them in the app, then select the existing project through `list_projects`. Do not substitute the free React XR template for a requested glasses app because creation was denied. Use the current catalog and pricing for entitlement requirements.

The catalog's `kind: web` includes the Expo companion templates because they have a browser preview. It does not mean the companion can use real glasses hardware from a published web page. Preserve the project's runtime and dependencies; do not replace an Expo app with a Vite scene. The device guide covers platform tools, account requirements and release restrictions. Meta templates do not establish Android XR or Snap Spectacles compatibility.

## Build, check and show the result

Choose who makes the edits. As the connected coding agent, you can read and write the project yourself, then use Graspable to check and preview it. Free-template creation, file edits and local checks require no additional AI sign-in and spend no Graspable Credits; your own agent usage terms still apply. Premium templates and paid services retain their requirements.

For direct editing, use `write_file` with the project ID, project-relative path and complete new file content. Read first and preserve unrelated changes. Prefer the available motion/USD tools for structured animation or scene edits; inspect their current schemas and [animation API](https://graspable.dev/docs/api.md) before calling them.

If the person wants to delegate generation, call `start_run` with `project` and a `prompt` describing what they should see and do. Omit engine/model overrides unless the task requires them, so the person's configured account is used. Delegated generation uses that account's allowance or balance; respect the authorized budget.

Follow the returned run ID with `get_run`. Pass its returned `since` value unchanged on the next call to read only new events. States `completed`, `failed` and `cancelled` are terminal. A disconnect is not a failed run; reconnect to the same run rather than starting a duplicate. When `needs_approval` is returned, relay the concrete action to the person unless their existing authorization already covers it. The skill itself grants no permission.

Call `check_project` after manual edits. For web projects it builds and loads the scene in a headless browser. On Graspable 0.19.0 or later, request `includeImage: true` when you need to inspect the picture; the returned MCP image is sent to your connected agent. Read the text report too: a skipped browser check is not a rendered pass. A failed or cached check can include an image, and a missing image is not visual verification. A failed check is not a finished result: inspect the failure, make a focused correction and check again. Stop and report a repeated blocker rather than retrying forever. Native checks depend on the engine and installed build tools; read [Native XR](https://graspable.dev/docs/native-xr.md).

For a web project, call `start_preview` after a successful check and return the project ID, local preview address, check result and any remaining device checks. The preview address is local to that computer. For Unity, Unreal or visionOS projects, use the native check result and available image, then direct the person to the native preview in Graspable. Do not call `start_preview` for native projects; it starts a web server. Publish only when the person has authorized publication; use the app or the documented [publishing flow](https://graspable.dev/docs/publishing.md).

## Without MCP

To delegate a request without MCP, use the CLI:

```text
grasp projects
grasp templates
grasp new "Project name" --template react-xr-developer
grasp run <project-id> "Describe the requested experience"
grasp check <project-id>
grasp preview <project-id>
```

Use `grasp files <project-id>` and `grasp cat <project-id> <relative-path>` to inspect files. For background work, `grasp run … --no-wait` returns the run ID; follow it with `grasp logs <run-id> --follow`. Do not enable blanket approval flags merely to avoid an approval request.

If delegated generation is not configured, the person signs in through the app's **Settings → AI for the agent** or the interactive `grasp login` flow. API keys configured in the app are not shared with a separately running CLI. Never copy credentials from a vault into a prompt or tool transcript. See [CLI sign-in](https://graspable.dev/docs/cli.md).

## Match the actual device

Web projects use React Three Fiber and WebXR. Immersive features need a compatible browser and device. The Tabletop AR template uses a tracking mat in iPhone browsers; it does not detect a bare table there. Surface placement is available through supported WebXR or the native Unity AR project. Native templates require the corresponding Unity, Unreal Engine or Xcode tools and plan access.

A successful headless check does not prove headset comfort, hand input, tracking, audio or frame rate. Say what was checked and what still needs the target device. Use the current [template catalog](https://graspable.dev/docs/templates.md) and [pricing](https://graspable.dev/pricing.md) for requirements rather than inventing capabilities or prices.
