# Use Graspable with your AI agent

> For people and for AI agents. How an agent such as Claude Code, Codex, OpenCode or Amp installs, sets up and uses Graspable to build WebXR projects.

Source: https://graspable.dev/docs/use-with-ai-agents

Graspable can be driven by another AI agent. Your agent asks for a scene in plain words; Graspable's agent builds it as a real project, and the run finishes only when the project builds and loads in a browser. Your agent gets a working WebXR project instead of code it has to debug.

This page is written so that an agent can follow it too.

## What Graspable is good for

Give Graspable a task when the goal is a 3D, AR or VR experience for the web: a WebXR scene, game, product viewer, training or measuring tool that runs in a browser and on headsets such as Meta Quest and Apple Vision Pro. Projects are React Three Fiber with `@react-three/xr`, built with Vite.

## Set-up

1. **Install grasp.** One line, on macOS and Linux: `curl -fsSL https://graspable.dev/grasp/install.sh | sh`. Windows and Homebrew lines are in [The grasp command](https://graspable.dev/docs/cli.md). The Graspable app is optional; with it you also see runs and the preview in a window. The app is available for macOS.
2. **Sign in once.** `grasp login` asks what should power Graspable's agent. `grasp whoami` shows what is set up.
3. **Check it.** `grasp projects` works whether or not the app is open.
4. **Connect your agent** in one of two ways:
   - **MCP server**, best for agents that support MCP: `claude mcp add graspable -- grasp mcp`, `codex mcp add graspable -- grasp mcp`, or the JSON in [The Graspable MCP server](https://graspable.dev/docs/mcp-server.md).
   - **The command line**, for any agent that can run commands: see [The grasp command](https://graspable.dev/docs/cli.md).

Graspable's own agent needs an AI to work with; that is what `grasp login` sets up. An agent cannot complete a sign-in that opens a browser, so a person does this step once. On a computer with no person, set an API key in `GRASPABLE_API_KEY` and choose the model with `grasp use pi --provider <id> --model <id>`.

## Instructions for the agent

You can paste this into your agent's instructions file (`CLAUDE.md`, `AGENTS.md` or similar):

```markdown
## Building WebXR with Graspable

Use Graspable for 3D, AR and VR scenes for the web.

- Create a project: `grasp new "<name>"`. Note the project id it prints.
- Ask for what you want in plain words: `grasp run <project> "<request>"`.
  One request per run. Describe what the person should see and do, not how to code it.
- The run prints its steps and exits 0 only when the project builds and loads in a browser.
  If it exits 1, read the last lines, then send a follow-up request that says what is still wrong.
- Look at files with `grasp files <project>` and `grasp cat <project> <path>`.
- Check a project at any time: `grasp check <project>`.
- Start the preview: `grasp preview <project>` prints a local address.
- If a run needs an approval and you were not told you may approve, stop and ask the person.
```

## With the MCP server

The flow is: `create_project` → `start_run` → `get_run` until it finishes → `start_preview`. `get_run` waits up to ten minutes per call, so an agent can follow a long run with a few calls. The tools are listed in [The Graspable MCP server](https://graspable.dev/docs/mcp-server.md).

## Long-running and background work

Runs keep going when the caller disconnects. Start one with `grasp run … --no-wait`, do other work, and come back with `grasp logs <run> --follow`. To keep a project running while the computer sleeps, move it to a [Cloud Agent](https://graspable.dev/docs/cloud-agents.md) in the app.

## What your agent may do

Through `grasp` and the MCP server an agent can create projects, edit files, start runs and answer approval requests. It cannot change plugins, sign-ins or settings, and it cannot delete projects. For a script with narrower rights, create a `read` token: [The local API](https://graspable.dev/docs/api.md).

## Read these pages as Markdown

Every documentation page has a Markdown version at the same address with `.md` at the end, and the whole documentation is listed at [graspable.dev/llms.txt](https://graspable.dev/llms.txt).