# Getting Started with Legionnaire

This tutorial walks you through your first Legionnaire workflow. By the end, you'll have created a parent worktree with multiple children and understand how to navigate and manage them.

## What You'll Build

You'll create a development setup for a feature called "user-dashboard" with three parallel work items:
- API endpoints
- Frontend components
- Integration tests

## Prerequisites

- Git repository with at least one commit
- tmux installed and available
- Legionnaire installed (`uv add legionnaire` or `pip install legionnaire`)
- Recommended: [Configure tmux for pane splits](../how-to/configure-tmux.md) so new panes open in the correct directory

## Step 1: Navigate to Your Repository

Open a terminal and navigate to your git repository:

```bash
cd /path/to/your/project
```

Verify you're in a git repository:

```bash
git status
```

You should see normal git status output, not an error.

## Step 2: Initialize the Parent

Create a new parent worktree for your feature work:

```bash
legion init user-dashboard
```

You'll see output like:

```
Initialized parent 'user-dashboard' with 0 children
```

This creates:
- A new git worktree at `../your-project_worktrees/user-dashboard/parent`
- A new branch called `user-dashboard/parent`
- A tmux session named `user-dashboard`

## Step 3: Add Children for Parallel Work

Now add children for the three work items:

```bash
legion init user-dashboard api-endpoints frontend-components integration-tests
```

Output:

```
Initialized parent 'user-dashboard' with 3 children
```

Each child gets:
- Its own git worktree
- Its own branch based on the parent's HEAD
- A tmux window in the parent's session
- An LLM agent (Claude by default)

## Step 4: View What Was Created

List the parent and its children:

```bash
legion list user-dashboard
```

You'll see something like:

```
Parent: user-dashboard
  Branch: user-dashboard/parent
  Worktree: /path/to/project_worktrees/user-dashboard/parent
  Session: managed

Children:
  api-endpoints
    user-dashboard/api-endpoints | window=yes | agent=running
  frontend-components
    user-dashboard/frontend-components | window=yes | agent=running
  integration-tests
    user-dashboard/integration-tests | window=yes | agent=running
```

## Step 5: Attach to the tmux Session

Connect to your tmux session to see the windows:

```bash
tmux attach -t user-dashboard
```

You'll see:
- Window 0: `parent` (red)
- Window 1: `api-endpoints` (blue)
- Window 2: `frontend-components` (cyan)
- Window 3: `integration-tests` (green)

Navigate between windows with `Ctrl+b` followed by window number (0-3).

## Step 6: Work in Parallel

Each child window has its own:
- Working directory (the child's worktree)
- Git branch
- Running LLM agent

You can switch between windows and give each agent different tasks. Changes in one worktree don't affect the others.

## Step 7: Clean Up When Done

When you're finished, remove everything:

```bash
# First detach from tmux: Ctrl+b, then d

# Remove a specific child
legion remove user-dashboard api-endpoints

# Or remove everything
legion remove user-dashboard --force
```

## Summary

You've learned how to:

- Initialize a parent worktree with `legion init`
- Add children for parallel work
- List and inspect your setup with `legion list`
- Navigate tmux windows
- Clean up with `legion remove`

## Next Steps

- [Configure tmux](../how-to/configure-tmux.md) for optimal pane splitting behavior
- Learn more about [managing children](../how-to/manage-children.md)
- Understand the [architecture](../explanation/architecture.md)
- See the full [CLI reference](../reference/cli.md)
