> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ahmadawais/gwtree/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get your first worktree running in minutes with practical examples

## Create your first worktree

Navigate to any git repository and create a worktree:

<Steps>
  <Step title="Interactive mode">
    Run `gwt` without arguments for an interactive prompt:

    ```bash theme={null}
    gwt
    ```

    You'll be guided through:

    1. **Name** — Enter name for both worktree and branch (press ESC to set separately)
    2. **Stash/Switch** — Handle uncommitted changes and switch to main
    3. **Pull** — Fetch latest changes from remote

    <Tip>
      Press ESC during name input to set worktree and branch names separately.
    </Tip>
  </Step>

  <Step title="Quick mode">
    Pass a name directly to skip prompts:

    ```bash theme={null}
    gwt feature-login
    ```

    This creates:

    * Worktree: `repo-feature-login/`
    * Branch: `feature-login`

    The CLI shows each command as it runs:

    ```bash theme={null}
    │
    │  ◆  Prune  git worktree prune
    │  └  removes stale refs
    │
    │  ◆  Create  git worktree add -b "feature-login" .../repo-feature-login "main"
    │  └  /Users/you/projects/repo-feature-login
    │
    │  ◆  Install  pnpm install
    │  └  installs dependencies
    │
    │  ◆  Open  code .../repo-feature-login
    │  └  opens in editor
    │
    └  Done  cd ../repo-feature-login
    ```
  </Step>

  <Step title="Navigate to worktree">
    Change to your new worktree directory:

    ```bash theme={null}
    cd ../repo-feature-login
    ```

    Your editor should already be open with the new worktree.
  </Step>
</Steps>

## Multi-agent parallel development

The real power of GWTree is creating multiple worktrees for parallel AI agent development:

```bash theme={null}
# Create 3 worktrees instantly
gwt auth api dashboard -x
```

This creates three isolated worktrees:

<CodeGroup>
  ```bash Worktree 1: auth theme={null}
  repo-auth/
  └── branch: auth
  ```

  ```bash Worktree 2: api theme={null}
  repo-api/
  └── branch: api
  ```

  ```bash Worktree 3: dashboard theme={null}
  repo-dashboard/
  └── branch: dashboard
  ```
</CodeGroup>

<Note>
  The `-x` flag (or `--no-editor`) skips opening editors — perfect for batch creation.
</Note>

Now run different AI agents in each worktree:

* **Claude Code** in `repo-auth/`
* **Command Code** in `repo-api/`
* **Cursor** in `repo-dashboard/`

## Fast mode with defaults

Skip all prompts using your saved config:

```bash theme={null}
gwt feature-login -y
```

The `-y` or `--yes` flag uses saved defaults for stash, pull, and editor preferences.

## List worktrees

See all worktrees for the current repo:

```bash theme={null}
gwt ls
# or
gwt list
```

Output:

```bash theme={null}
╔═╗╦ ╦╔╦╗
║ ╦║║║ ║
╚═╝╚╩╝ ╩

Worktrees for repo
│
│  ◆  auth
│  └  /Users/you/projects/repo-auth
│
│  ◆  api
│  └  /Users/you/projects/repo-api
│
│  ◆  dashboard
│  └  /Users/you/projects/repo-dashboard
│
└  3 worktrees
```

## Check status

See the status of all worktrees:

```bash theme={null}
gwt status
# or
gwt st
```

Shows for each worktree:

* Changed files
* Commits ahead/behind main
* Merge readiness
* Line additions/deletions

```bash theme={null}
Status for repo
│
│  ◆  auth  +127 -43
│  └  2 changed, 3 ahead
│
│  ◆  api  +89 -12
│  └  ready to merge (2 commits ahead)
│
│  ◆  dashboard
│  └  ✓ merged
│
└  1 ready to merge, 1 in progress, 1 merged
```

## Merge and cleanup

When a feature is complete, merge it back to main:

```bash theme={null}
gwt merge api
```

This automatically:

1. Switches to main branch
2. Merges the feature branch
3. Removes the worktree
4. Deletes the branch

<Warning>
  Make sure all changes are committed before merging. The command will fail if there are uncommitted changes.
</Warning>

## Clean merged worktrees

Remove all worktrees that have been merged to main:

```bash theme={null}
gwt clean
# or
gwt c
```

Remove all worktrees (merged or not):

```bash theme={null}
gwt clean --all
# or
gwt c -a
```

## Remove specific worktrees

Interactive search and remove:

```bash theme={null}
gwt rm
# or
gwt remove
```

Use fuzzy search to find and remove worktrees:

```bash theme={null}
? Search worktree: › api

  ❯ api repo-api
    /Users/you/projects/repo-api

? Remove repo-api? › (Y/n)
```

## Essential commands

| Command            | Description                   |
| ------------------ | ----------------------------- |
| `gwt`              | Create worktree (interactive) |
| `gwt <name>`       | Quick create with name        |
| `gwt a b c`        | Batch create multiple         |
| `gwt <name> -y`    | Fast mode, skip prompts       |
| `gwt <name> -x`    | Skip opening editor           |
| `gwt ls`           | List all worktrees            |
| `gwt status`       | Show status dashboard         |
| `gwt merge <name>` | Merge and cleanup             |
| `gwt clean`        | Remove merged worktrees       |
| `gwt rm`           | Interactive remove            |
| `gwt config`       | Open config file              |

## Package manager detection

GWTree automatically detects your package manager:

* `pnpm-lock.yaml` → uses `pnpm install`
* `bun.lockb` → uses `bun install`
* `yarn.lock` → uses `yarn install`
* `package-lock.json` → uses `npm install`
* `package.json` only → defaults to `pnpm install`

<Tip>
  Set `installDeps: false` in config to disable automatic dependency installation.
</Tip>

## What's next?

You're ready to use GWTree for parallel AI agent development! Here are some tips:

<CardGroup cols={2}>
  <Card title="Workflow tip" icon="lightbulb">
    Use `gwt status` frequently to track progress across all worktrees
  </Card>

  <Card title="Clean habit" icon="sparkles">
    Run `gwt clean` regularly to remove merged worktrees
  </Card>

  <Card title="Fast creation" icon="bolt">
    Use `-x` flag for batch creation: `gwt a b c -x`
  </Card>

  <Card title="Configuration" icon="gear">
    Customize editor and install preferences with `gwt config`
  </Card>
</CardGroup>