Projects and layers

Layers let several agents change the same project at the same time without getting in each other’s way. This page shows how to make a layer, get it ready to run, and put it away when the task is done.

Figure: One project, three layers. Base is your own project folder. Each task layer has its own folder, branch, ports and agents.

What a layer is

When you add a project folder, Cuewire opens it as a workspace with one canvas. That canvas starts on the Base layer: your project folder, as it is.

A layer is a separate copy of your project for one task. It is a git worktree: a folder of its own, on a branch of its own, that shares your repository’s history. Each layer also has its own copy of the canvas.

• Agents in a layer work in that layer’s folder. Your own checkout stays as it is.
• Agents work with the agents, notes and portals of their own layer only.
• Switching layers never stops an agent. Agents in the other layers keep working.

Note

Layers need a git repository with at least one commit. Remote projects can’t have layers yet.

The layer chip

The layer chip is at the top left of the canvas. It shows the layer you are looking at, for example Layer Base ▾. Click it to open the layer menu.

Figure: The layer menu. The tick marks the layer you see.

The top of the menu lists the canvas’s layers:

• ✓ marks the layer you see. Click another layer to switch to it.
• restore marks an archived layer. Click it to bring the layer back.
• creating… shows while Cuewire makes the layer.
• failed · remove marks a layer Cuewire could not make. Click it to clean up what was made.

Below the list are the actions:

• New layer from this one makes a new layer.
• Review changes, Commit all changes and Open pull request check and ship the layer’s work. See Review your agents’ work.
• Archive Fix login (back to Base) puts the layer away. The name is the layer’s own.

The last four show on task layers only, not on Base.

Tip

The command palette has the same actions. Press Ctrl+K (Cmd+K on a Mac) and type “layer”: New layer from this one, Switch to layer: … and Archive layer: ….

Make a layer

1. Open the layer whose canvas you want to copy. Usually that is Base.
2. Click the layer chip, then New layer from this one. The New layer from this one sheet opens.
3. Type a Name for the task, for example Fix login. Cuewire suggests Layer 1, Layer 2 and so on.
4. Leave Branch (optional) empty, or type a branch name. The line under the field says what will happen.
5. Click Create layer, or press Enter. Esc cancels.

Figure: The New layer sheet. An empty branch gives the layer a branch of its own.

Cuewire makes the layer’s folder, gets it ready (see below) and switches to it. This can take a few seconds on a large repository.

The branch field decides where the layer’s code comes from:

A new branch starts at the commit of the layer you made it from. From Base, that is the commit your project folder is on now. From another layer, it is that layer’s latest commit, so the new layer builds on its work. Changes you have not committed are not in the new layer.

Start the layer’s agents

A new layer’s canvas is a copy of the one you came from. Its notes come along with their text. Its terminals come along as drafts: they are not running yet. A draft terminal says Draft in this layer · right-click → Start to run it here.

1. Right-click a draft terminal.
2. Choose Start in this layer. The agent starts in the layer’s folder.

Figure: A new layer. Its terminals wait as drafts until you start them.

Get a layer ready to run

A fresh worktree has your code but not everything you need to run it. Untracked files such as .env are missing, packages are not installed, and two copies of a server would fight over one port. Cuewire fixes this when it makes a layer. You describe what to do in .cuewire/layers.toml at the top of your repository:

copy = [".env*", "config/local.json"]   # files to copy into each new layer
setup = "npm install"                   # runs once in each new layer
ports = ["web", "api"]                  # ports each layer gets for itself

Every line is optional. Without the file, Cuewire copies the .env files and does nothing else.

Copied files

copy lists files to copy from your project folder into each new layer. The default is [".env*"].

• A name that ends in * matches files at the top of the project, such as .env and .env.local.
• A full path, such as config/local.json, can point into a folder.
• A file that is already in the layer is not replaced.

The setup command

setup runs once in each new layer, through your system’s shell. Use it to install packages or seed a database. It may run for up to 10 minutes. Its output goes to the layer’s setup.log in Cuewire’s state folder.

If the setup command fails, the layer is still made. The canvas says Fix login was created, but its setup failed: … with the reason.

Ports

ports names the ports your project’s servers need. Each layer gets its own numbers, so servers in two layers never clash.

• Cuewire gives each layer a block of ten ports, starting at 41000. The first layer you make gets 41010 and up, the second 41020 and up.
• A port that something else already uses is skipped.
• Two layers never get the same port.

The layer’s terminals get these variables:

Make your servers read PORT or CUEWIRE_PORT_<NAME>. Then each layer runs on its own ports.

A database per layer

If your database can make branches (Neon, for example), each layer can have its own. Add a [database] section:

[database]
create = "neon branches create --name $CUEWIRE_LAYER_BRANCH --output connection-string"
delete = "neon branches delete $CUEWIRE_LAYER_BRANCH"
env = "DATABASE_URL"

• create runs before the setup command. The last line it prints becomes the layer’s DATABASE_URL (or the variable env names). The setup command already sees it.
• delete runs when you archive the layer.
• If create fails, Cuewire says so and skips the setup command.

Note

.cuewire/layers.toml can also run agents in a sandbox. See Sandboxes and safety.

Archive a layer

Archive a layer when its task is done or on hold. Archiving keeps the work and frees the disk space.

1. Stop the agents in the layer.
2. Switch to the layer, click the layer chip and choose Archive Fix login (back to Base).

Cuewire switches back to Base and then:

1. commits anything not yet committed, as WIP: Fix login archived from Cuewire;
2. removes the layer’s folder;
3. runs the delete command of [database], if there is one.

The branch stays, with all the work on it. The layer stays in the menu, marked restore.

Warning

Cuewire refuses to archive a layer while its agents run. It says Stop the agents in this layer before archiving it. Stop them first, so no agent is cut off in the middle of a change.

Restore a layer

1. Click the layer chip.
2. Click the archived layer, marked restore. Cuewire checks its branch out into a folder again.
3. Click the layer in the menu to switch to it.

Restoring does not copy files or run the setup command again. If a folder is already where the layer’s folder goes, Cuewire stops and says a directory is already in the way of this layer.

What’s next

• Review your agents’ work: check a layer’s changes, then commit and open a pull request.
• Files and the editor: see a layer’s files and diffs on the canvas.
• Sandboxes and safety: run a layer’s agents in a container.