# Your first project

> Create a project from a template, send your first request, read the run, open the preview and undo a run.

Source: https://graspable.dev/docs/first-project

Before you start, choose what powers the agent in **Settings → AI for the agent**. See [Engines and sign-in](https://graspable.dev/docs/engines-and-sign-in.md).

## Create a project

1. On the **Projects** page, type a **Name**.
2. Pick a **Template**. See [Templates](https://graspable.dev/docs/templates.md).
3. Choose **Create**.

Graspable copies the template into a new folder and installs its packages. The project header shows "installing packages" while this runs. You can look at the files and write your first request in the meantime: the agent starts as soon as the packages are in. The preview unlocks when the install ends.

## Send the first request

The project page has three parts: the file list on the left, the editor in the middle, and the run panel on the right.

Type what you want in the box that says "What should we build?" and press Enter. Shift+Enter adds a new line.

You can also say it. Press the microphone beside the box, speak, and press it again. What you said appears in the box, where you can change it before you send it. Voice needs a Graspable account or your own ElevenLabs key. See [Voice](https://graspable.dev/docs/voice.md).

Say what should happen, not how to code it. For example:

```text
Replace the cube with a small solar system. The planets orbit the sun, and tapping a planet shows its name above it.
```

While the agent works, the box says "Steer the agent…". Anything you send then reaches the agent during the same run. The square button cancels the run.

## Read the run

The run panel shows the run as it happens.

| You see | It means |
|---|---|
| Text | The agent talking to you |
| `Thinking…` | The agent's reasoning as it streams: the latest lines, with the earlier ones fading out above. A finished thought folds to one line, `Thought · 120 words`; click it to read the whole text. How much the Graspable agent reasons is set under **Settings → AI for the agent → Reasoning** |
| `▸ name …` | The agent used a tool, such as reading a file or running a command |
| `✎ App.jsx` | The agent wrote that file. The editor shows the new content, keeping any unsaved edits for review |
| `🧠 recalled: …` | Items from [memory](https://graspable.dev/docs/memory.md) were given to the agent for this request |
| An amber card with **Allow** and **Deny** | The agent wants to do something that needs your approval. See [Approvals and safety](https://graspable.dev/docs/approvals-and-safety.md) |
| `✓ build check` or `✗ build check` | A check passed or failed |
| `— success —` | The run completed |

## The checks

When the agent finishes editing, Graspable checks the result:

1. **build** — the project is built.
2. **smoke** — the built app is loaded in a browser on your computer, without a window. Errors, failed requests and a blank page fail the check. A screenshot of what the browser saw appears under the check.
3. **xr** — your XR recordings are replayed. This check only appears when the project has recordings. See [XR tests](https://graspable.dev/docs/xr-tests.md).

If a check fails, the agent gets the error and tries to fix it. It gets at most three repair turns. If the check still fails, the run ends as failed and tells you which check.

If no browser is found, the smoke and xr checks are skipped and the check line gives the reason.

## Open the preview

Use the buttons at the top right of the project page:

- **Code** — the editor only.
- **Split** — the editor above the preview.
- **Preview** — the preview only. The first click starts the project's dev server.
- **Compare** — runs the same request with several engines side by side. You can then **Adopt** one result or **Discard** it.

The preview reloads as files change. See [Preview and headset](https://graspable.dev/docs/preview-and-headset.md).

## Edit by hand

Click a file to open it. Type, then choose **Save**, or press ⌘S on macOS and Ctrl+S on Windows and Linux. Version 0.19.1 labels the button with your platform's shortcut.

Hold Alt (Option on macOS) and drag a decimal number sideways to change it, or hold Shift too for smaller steps. The preview updates as you drag. From version 0.19.1, numbers can become draggable beyond the initially parsed part of a large file, and saved code updates appear without an extra typing delay when you have no unsaved edits.

Version 0.19.1 also keeps your unsaved code when the agent, project history or another editor changes the file. **View saved version** lets you review the new text; **Replace saved version** asks before saving your edits over it. **Discard edits** returns to the saved text. Before a new agent request or comparison, Graspable saves your code drafts. If a save fails or a file changed elsewhere, your request waits and your edits remain. Navigating away from a project with unsaved code asks first. Drafts are held while the project is open; save before quitting the app. The next desktop patch asks before closing or quitting with unsaved code, unsaved animation, or work in progress in the open project. On macOS, this includes **Command-Q** and **Quit** in the app menu. Choose **Keep editing** to return without stopping the agent. This does not recover work after a crash or forced quit.

From version 0.19.1, Undo and Redo stay separate for each file. Graspable remembers the cursor and scroll position in your 12 most recently used files while the project stays open. Switching between Code, Split and Preview keeps this history. If a saved file changes while you are away from it, its old editing history is cleared when you reopen it.

If you select code in the editor, a chip above the prompt box shows the file and lines. The selection goes with your next request, so you can write "make this slower" without naming the file. Click the × on the chip to leave it out. From version 0.19.1, the selected text and line numbers also update as you edit, so your next request receives the current selection.

## Assets

Beside **Files**, the **Assets** tab lists the project's models, images, sounds, videos and the engine's own assets (a Unity prefab, an Unreal Blueprint or level), by folder. Type to find one, or show one kind only. Version 0.19.1 loads image thumbnails as you scroll and releases those that leave view, keeping large asset folders lighter. A selected image stays open until you close its preview.

Search ignores letter case and keeps your selected preview open while you filter the list. If nothing matches, **Clear filters** restores all assets. If the list could not load, choose **Retry**.

Click an asset to see it. The preview scrolls within the sidebar so the asset list remains reachable; **Close** returns to the list. A model (glTF, GLB, OBJ, STL, 3MF and PCD point clouds) is drawn in 3D with its textures: drag to turn it, scroll to move closer. Triangle counts help you compare exports; they do not measure headset frame rate. Images, sound and video are shown and played. Other kinds are listed with their size.

**Add** copies files from your computer into the project, each into the folder its kind belongs in: `public/models`, `public/textures`, `public/audio` and `public/video` in a web project; `Assets/Models` and so on in Unity; `Source/Models` and so on in an Unreal project; `App/Resources/` in a Vision Pro app. The agent uses the same folders, so you can add a model and then ask for it by its file name. If an asset uses symbolic links, use **Add** to copy the original files into the project before previewing them. Version 0.19.1 applies the same protected-file checks to previews as other asset reads. Linked source files inside the project still work, but links cannot be used to change Graspable’s project settings, saved history or recorded headset tests.

You can bring existing models from Meshy, Tripo, Luma Genie or another tool. For web projects, export a **GLB** with its skeleton and animation clips included. Selecting a GLB or glTF in Assets shows its skins, joints, morph targets and clip names. Choose a clip, play or pause it, or scrub to inspect a pose. **Morph controls** lets you test the model's existing facial expressions and deformations, with each mesh named beside its controls. **Fit model** brings the current pose into view without changing your viewing direction. For animated models, **Restore pose** restores the imported pose and expressions without moving the camera. It becomes available after you change the pose. Focus the preview and use Shift plus arrow keys to orbit, or arrow keys to pan.

These are audition controls: they do not write changes to the model or save a performance into your animation take. A model without facial controls does not gain them from this preview. Draco, Meshopt and KTX2-compressed assets use bundled decoders. Preview loading is cancelled when you leave the model, and rendering stops when idle or hidden. Large exports may need smaller textures: previews allow up to 192 MB per file, 256 MB in total, 64 files, 20,000 scene nodes, 512 MB of estimated geometry and animation attributes, a separate 512 MB limit on decoded model buffers, and 64 million texture pixels, with a maximum texture edge of 8,192 pixels. The morph panel shows up to 256 controls and reports when there are more.

A glTF import copies its local buffers and textures together. Missing or external resources, unsupported required features and decoding failures stop the preview instead of silently dropping parts of the model. Existing filenames are preserved by giving a new import a numbered name. See [Characters and models](https://graspable.dev/docs/plugins.md) for connectors, rigging and provider-library limits.

Closing a GLB or glTF preview releases resources from every scene in the model, including scenes that were not displayed. If decoding finishes after you close it, that result is released too. An interrupted graphics preview stops and offers **Retry**.

The texture limit covers every decoded scene, including textures on line and point geometry. A texture shared between scenes is counted once. Closing the preview releases line and point geometry as well as triangle meshes.

Version 0.19.1 checks glTF object hierarchies before decoding. Cycles, repeated parent links and missing child objects produce an error; hierarchies deeper than 256 levels need unnecessary groups flattened before previewing. These checks leave the original file intact. STL, 3MF and PCD previews also avoid creating an unnecessary text copy of the model. OBJ, STL, 3MF and PCD previews redraw when you move or resize the view, then rest while idle. Closing or switching previews cancels their pending downloads.

The same patch rejects malformed ZIP64 data in archive-based models such as 3MF, instead of leaving the preview unresponsive. The original file stays untouched; re-export it from its source application if the preview reports an invalid archive.

That patch also refreshes media previews when an asset's modification time changes and releases their temporary data when no thumbnail or preview needs it. A failed media download offers **Retry** in the preview.

From version 0.17.2, USD assets have an **Open USD inspector** action for scene hierarchy, properties, variants and separate edit layers. **Build preview** converts supported data to a web model; the original USD remains available. GLB and glTF assets also offer **Export as USD**. See [OpenUSD scenes](https://graspable.dev/docs/openusd.md) for supported formats and conversion limits.

## Go back in time and undo

When a run has more than one event, a slider appears at the top of the run panel. Drag it back to see the transcript and the files as they were at that point. The editor is read-only while you do this. **Live** returns to the present.

When a run that changed files has ended, you can undo it:

- **Undo run** puts every file the run changed back to how it was before the run.
- With the slider dragged back, the button reads **Undo after here** and puts the files back to how they were at that point.

If you changed a file after the run, Graspable leaves it alone and tells you how many files "changed since". Choose **overwrite them too** to undo those as well. Undo never deletes a file that existed before the run started.

## History

Undo works on one run. **History**, in the project header, is the whole story of the project: a list of versions, newest first. A version is a snapshot of every file in the project at one moment, with a short note. Graspable records one when the project is created ("Start from the … template") and one at the end of every run that changed files — the note is your request. A run that failed or was stopped is recorded too, so nothing it did is lost.

Click a version to see which files it added, changed or removed. **Restore this version** puts every file back to how it was then, and asks first. Restoring does not delete anything from the history: it adds a new version ("Restore to …") on top, so you can always come forward again. Installed packages, the preview and the agent's memory are not part of versions and are left alone.

Projects made before this feature get their history the next time a run ends or the list is opened; the first version then is the project as it was at that moment.

### Keep the history on your GitHub

On the Pro plan and higher, a project's versions can also go to a repository on your own GitHub. Choose **GitHub** in the project header, then **Connect GitHub**: a GitHub page opens in your browser and asks for the short code shown in Graspable. Back in the app, give the repository a name (it is made if it does not exist, private unless you untick that) and choose **Link and push**.

From then on every run's version is pushed there by itself. **Push now** does it by hand, and **Unlink** stops it; the repository on GitHub stays as it is. Graspable only ever adds to a repository: if it has commits that are not in the project, the push is refused and the panel says so.

The history travels with the project when it moves to a [Cloud Agent](https://graspable.dev/docs/cloud-agents.md) and back. Each version is a git commit, so a project folder also works with git tools you may already use; nothing needs to be installed for Graspable itself. The same list is available as `grasp history` in the [CLI](https://graspable.dev/docs/cli.md) and `project_history` in the [MCP server](https://graspable.dev/docs/mcp-server.md).
