# Working in parallel 

You can run multiple AI agents simultaneously on separate Gadget environments to explore different approaches, work on independent features, or delegate tasks without interfering with one another.

## Why this works 

[Gadget environments](https://docs.gadget.dev/guides/environments) are fully isolated, independently hosted instances. Each development environment is a sandboxed copy of your app with its own database, API, and runtime. There is nothing to install or provision locally. Running [`ggt env create`](https://docs.gadget.dev/reference/ggt#ggt-env) gives an agent its own fully managed Gadget infrastructure in seconds, cloned from your existing environment.

Gadget development environments are unlimited, so you can spin up as many parallel environments as you need without worrying about port conflicts, shared state, or local resource limits. Each agent gets a live development environment to build and test against. If your app depends on [environment variables](https://docs.gadget.dev/guides/development-tools/environment-variables) or connected applications, copy the required variables and complete any per-environment setup before handing the workspace to an agent. When the work is done, [`ggt env delete`](https://docs.gadget.dev/reference/ggt#ggt-env) tears the environment down just as quickly.

## How it works 

Each parallel agent gets its own:

*   **Local workspace**: An isolated copy of your codebase on disk. This can be a git worktree, a separate repo clone, or another workspace layout that fits your team.
*   **Gadget environment**: A separate cloud sandbox where the agent can run and test changes independently.

Changes from each agent stay isolated until you are ready to review and merge them.

## Choosing a local workspace strategy 

You need one local workspace per agent. Common options include:

*   **Git worktrees**: Fast to create, share one git repository, and work well when you want several branches checked out at once. See the [git worktree docs](https://git-scm.com/docs/git-worktree).
*   **Separate repo clones**: Simple and familiar if you prefer complete filesystem separation for each agent.

You can automate either approach with setup scripts that create the workspace, create a Gadget environment, import variables, and hand the result to an agent.

The rest of this guide uses git worktrees, but the same `ggt` environment workflow applies to any separate local workspace.

## Prerequisites 

*   `ggt` [installed and authenticated](https://docs.gadget.dev/guides/development-tools/cli)
*   Your Gadget app synced locally using `ggt dev`
*   Git [initialized in your project directory](https://docs.gadget.dev/guides/source-control)

## Example setup with git worktrees 

### 1\. Create a local workspace 

From your main app directory, create a new worktree for the agent:

```bash
git worktree add ../agent-feature
cd ../agent-feature
```

This creates a new directory with a new branch checked out from your current `HEAD`. Because the directory name is `agent-feature`, git uses that same name for the new branch. If you prefer separate clones instead of worktrees, create that clone here and continue with the same `ggt` steps below.

### 2\. Create a new Gadget environment 

Create a dedicated Gadget environment for the workspace:

```bash
ggt env create agent-feature --use
```

The `--use` flag updates the workspace's `.gadget/sync.json` so subsequent `ggt` commands in this directory target the new environment automatically.

If you are creating environments from an automated script, pass `--app` explicitly:

```bash
ggt env create agent-feature --app my-app --use
```

### 3\. Copy environment variables 

Copy environment variables from your development environment to the new one. `--include-values` copies non-secret values, but secret values are not copied:

```bash
ggt var import --from development --all --include-values
```

Secret variables cannot be read back once set, so `ggt var import --include-values` does not copy them. Set any required secrets manually after importing: `ggt var set MY_SECRET=value --secret`

### 4\. Push your local code to the new environment 

```bash
ggt push --force
```

The `--force` flag discards any remote changes and replaces the environment with your local files. Since this is a freshly created environment, this is safe.

### 5\. Start `ggt dev` 

If your agent needs to test code changes against the running Gadget environment, start `ggt dev` in the workspace directory:

```bash
ggt dev
```

`ggt dev` runs until you stop it. While it is running, changes made locally and changes made in the cloud development environment are synced automatically.

### 6\. Start your agent 

Open Claude Code, Codex, or your AI coding tool of choice in the workspace directory. The agent will develop against the new environment without affecting the other agent workspaces or environments you are using.

## Running multiple agents 

Repeat the setup for each additional agent:

```bash
# From your main app directory
git worktree add ../agent-feature-2
cd ../agent-feature-2
ggt env create agent-feature-2 --use
ggt var import --from development --all --include-values
ggt push --force
```

If you do this often, wrap these commands in a setup script or use a tool that manages worktrees and agent workspaces for you. For example, tools like Codex or OpenCode provide with scripted workspace setup, and other agent platforms can automate worktree creation before handing the workspace off to an agent.

Each workspace and environment is fully independent. Agents cannot interfere with each other.

## Reviewing and merging changes 

Once an agent has completed its work, review the changes in that workspace and then follow your team's normal process for opening pull requests, running tests, reviewing code, merging changes, and shipping updates.

If multiple agents worked on overlapping files, resolve conflicts using the same workflow you use for any other branch or pull request.

## Cleaning up 

Remove the workspace and delete the Gadget environment when finished:

```bash
# Delete the Gadget environment
ggt env delete agent-feature --force

# Remove the git worktree
git worktree remove ../agent-feature
```

## Tips 

*   **Name environments clearly**: Use descriptive names like `agent-checkout-redesign` or `codex-auth-fix` to track what each environment is for.
*   **Keep names aligned**: Using the same name for the workspace, git branch, and Gadget environment makes it much easier to review, clean up, and understand which agent owns which changes.
*   **Check variable keys**: Run [`ggt var list`](https://docs.gadget.dev/reference/ggt#ggt-var) in the new workspace to verify the environment has the variables it needs before starting your agent.
*   **Automate the setup**: The `ggt env create`, `ggt var import`, and `ggt push` commands are straightforward to wrap in shell scripts or init scripts. You can build these scripts yourself or have a coding agent such as Codex generate them so new worktrees and Gadget environments can be created consistently.