Docs Your first project
Tutorials

Your first project

Updated October 4, 2026

A project is a piece of work handed to an agent. It starts from a spec, runs in its own container on your runner, and ends with pull requests you review and merge. This tutorial walks the whole road once.

You need a workspace on a runner, an agent account connected under Account → Agents, and for code changes a repository on the canvas (see repositories and git).

1. Select what describes the work

On the canvas, select the blocks the agent should start from: the note that describes the change, the mockup, the link to the research, the repository. With nothing selected, the whole canvas is the context. Pinned blocks always go along.

2. Create spec

Press Create spec → in the selection bar. In the dialog:

  • write what the project should do, in a sentence or two (for example "Add bulk select to the asset grid using the sketch. Keep Undo.");
  • for each repository, choose new worktree (the agent may change it) or read-only;
  • pick the agent and model.

Press Create project (or ⌘/Ctrl+Enter). The project opens with its agent drafting spec.md: a goal and acceptance criteria. Read it and edit it like any note, together with your team, until it says what you mean.

3. Work

Press Work →. The agent plans first, then works through its plan in its own container, in a worktree of each repository on a ctr/<project> branch. You see each step as it runs, and the criteria tick off as they are met. Stop halts it at any time.

If the agent is missing something it asks: the project shows Needs your input and the questions appear in its chat as a short form.

Here is the whole road on sample data. Press Work →, wait for the plan to finish, then follow the bar.

Demo From spec to pull request
spec.md · Bulk select in the asset library
0/3 criteria
Goal People delete assets one at a time today. Let them pick many and act once. Acceptance criteria Shift-click selects a rangeThe floating bar moves and deletes the selectionDelete can be undone for 8 seconds
Work · the project agent plans and implements spec.md in 1 worktree

Runs on sample data · The spec is drafted. Work hands it to the project's agent.

4. Push, review, merge

When the work is done the bar under the spec always names the next step, and a button that cannot be pressed yet says why:

  1. Push changes sends the branches to GitHub. They are pushed as you; agents never push. (If the agent left changes uncommitted, the bar offers Review and commit → first, in the project's Git tab.)
  2. Open PRs → opens a pull request for each repository, also as you. Review them on GitHub or in the project's Git tab.
  3. Merge PRs & close project once they are approved: it merges, then closes the project. Merge PRs only, in the arrow beside it, merges and leaves the project open. If a pull request conflicts with its base, the bar offers Resolve conflicts instead: the agent merges the base in and commits, you push, and then it can be merged.
  4. Close project archives the project with its chat and files. It stays under Closed in the sidebar and can be reopened.

A project without a repository, or without commits, ends differently: the bar offers Take files into the workspace… to bring what the agent made onto the canvas, then Close project.

Next