# Getting Started with the Web UI

Learn to use Mehrhof through the web interface - no command-line expertise required. This guide walks you through your first task from start to finish.

## What You'll Learn

By the end of this guide, you'll be able to:
- Start the Web UI server
- Create a task from scratch
- Watch the plan and implementation steps
- Review and complete your task
- Navigate key workflow actions with keyboard-friendly controls

## Prerequisites

- Mehrhof installed ([Quickstart](/quickstart.md) if needed)
- An agent CLI configured (Claude recommended, see [AI Agents](/agents/index.md))

For accessibility details, see [Web UI: Accessibility](/web-ui/accessibility.md).

> **Prefer zero terminal?** The [Desktop App](/desktop/index.md) provides everything below without running any commands. Download, launch, and start working.

> **No project yet?** You can start with an empty directory. Just select any folder — Mehrhof will create everything it needs.

---

## Step 1: Start the Server

Run this command once from any directory:

```bash
mehr serve --global --open
```

Your browser opens automatically. That's the only terminal command you need.

### Select Your Project

1. Click **"Open Folder"** in the project selector
2. Navigate to your project directory
3. Click **"Select This Folder"**

The project picker initializes your workspace automatically — no `cd` or `mehr init` required.

> **Already in a project directory?** Run `mehr serve --open` (without `--global`) to skip the project picker and open directly to that project.

### What You'll See

```text
                    ┌───────────┐
                    │ Dashboard │
                    └─────┬─────┘
                          │
      ┌───────────┬───────┼───────┬─────────────┐
      ▼           ▼       ▼       ▼             ▼
┌───────────┐ ┌────────┐ ┌───────┐ ┌──────────┐ ┌──────────┐
│  Active   │ │ Create │ │ Quick │ │   Task   │ │ Settings │
│   Task    │ │  Task  │ │Actions│ │  History │ │          │
└───────────┘ └────────┘ └───────┘ └──────────┘ └──────────┘
```

The dashboard displays several sections: an **Active Task Card**, **Task Creation**, a unified **Tasks** block (with **Recent** and **Queue** views), and **Settings**. A dark mode toggle appears in the top right corner.

| Section              | What It Does                                                              |
|----------------------|---------------------------------------------------------------------------|
| **Active Task**      | Shows your current task (or "No active task")                             |
| **Workflow Diagram** | Visual state machine showing current workflow state and valid transitions |
| **Quick Actions**    | Buttons to continue, undo, redo                                           |
| **Tasks**            | Recent activity view plus queue-based planning tasks                      |
| **Settings**         | Configure agents, providers, and workflow                                 |
| **Dark Mode Toggle** | Switch between light/dark theme (top right)                               |

### Workflow Diagram

At the top of the dashboard, you'll see an interactive workflow diagram that visualizes the current state. It shows states (IDLE → PLANNING → IMPLEMENT → DONE) with arrows indicating valid transitions. The current state is highlighted in color, and the diagram updates automatically as the workflow progresses.

This helps you understand where you are in the workflow and what actions are available.

---

## Step 4: Create Your First Task

Click the **"Create Task"** button in the center of the dashboard.

### The Create Task Dialog

You'll see a dialog with several options:

```text
           ┌────────────────────┐
           │ Create Task Dialog │
           └─────────┬──────────┘
                     │
     ┌───────┬───────┼───────┬──────────────┐
     ▼       ▼       ▼       ▼              ▼
┌────────┐ ┌────────┐ ┌──────┐ ┌─────────────────┐
│ Write  │ │ Upload │ │ From │ │ From Provider   │
│ Task   │ │ File   │ │ URL  │ │                 │
└────────┘ └────────┘ └──────┘ └─────────────────┘
```

The **Create Task** dialog has tabs for **Write Task**, **Upload File**, **From URL**, and **From Provider**. Below the tabs, you'll find a Title field and a Description text area. Action buttons include **Create Task** and **Cancel**.

### Option A: Write a Task (Recommended for First Time)

1. Click the **"Write Task"** tab
2. Enter a title: `Add Health Check Endpoint`
3. Enter the description:

````markdown
Create a `/health` endpoint that:
- Returns HTTP 200 when healthy
- Responds with JSON including:
  - status: "ok"
  - timestamp: current time
  - version: "1.0.0"
````

4. Click **"Create Task"**

### Option B: Upload a File

1. Click the **"Upload File"** tab
2. Drag and drop a `.md` or `.txt` file
3. Click **"Create Task"**

### Option C: From GitHub (or Other Providers)

1. Click **"From Provider"**
2. Select "GitHub"
3. Enter issue number (e.g., `123`)
4. Click **"Create Task"**

---

## Understanding the Workflow: Plan, Implement, Review

Mehrhof works in three distinct phases. This separation gives you control over each step — you can review the plan before any code is written.

```text
┌──────────────┐     ┌─────────────┐     ┌────────────────────┐     ┌──────────────────┐
│ Task Created │ ──▶ │ 1. Plan     │ ──▶ │ Specs Created      │ ──▶ │ 2. Implement     │
└──────────────┘     └─────────────┘     └────────────────────┘     └────────┬─────────┘
                                                                             │
                                                                             ▼
┌────────┐     ┌─────────────────┐     ┌─────────────┐     ┌──────────────────────────┐
│ Finish │ ◀── │ Quality Checks  │ ◀── │ 3. Review   │ ◀── │ Code Written             │
└────────┘     └─────────────────┘     └─────────────┘     └──────────────────────────┘
```

### The Planning Phase (Plan Mode)

When you click **"Plan"**, the AI analyzes your task and creates detailed specifications — think of it as a blueprint before building.

**What happens:**
- AI reads your task description
- Analyzes your existing codebase
- Creates specification files with implementation details
- May ask clarifying questions if something is unclear

**What you get:**
- One or more specification files (e.g., `specification-1.md`)
- A detailed plan the AI will follow during implementation
- Opportunity to review and adjust before code is written

**Why this matters:**
- You can review the plan before any code changes
- Catch misunderstandings early
- Iterate on the approach without touching code

### The Implementation Phase

When you click **"Implement"**, the AI executes the specifications:

**What happens:**
- AI reads all specification files
- Creates or modifies code files
- Writes tests
- Follows the plan from the planning phase

### The Review Phase

When you click **"Review"**, Mehrhof runs quality checks:

**What happens:**
- Runs automated tests (if configured)
- Checks code quality
- Reports any issues found

### Iterative Planning

You can run planning multiple times to build on existing specifications:

1. Click **"Plan"** → Creates `specification-1.md`
2. Review the spec
3. Add a note: "Also add error handling"
4. Click **"Plan"** again → Creates `specification-2.md`

Both specifications will be used during implementation.

---

## Step 5: Watch the Planning Phase

After creating your task, you'll see it appear in the **Active Task** card.

```text
┌────────────┐     ┌──────────────┐     ┌────────────────┐     ┌─────────────────────────┐     ┌────────────────────┐
│ Idle State │ ──▶ │ Click 'Plan' │ ──▶ │ Planning State │ ──▶ │ AI Generates Specs      │ ──▶ │ Ready to Implement │
└────────────┘     └──────────────┘     └────────────────┘     └─────────────────────────┘     └────────────────────┘
```

The **Active Task** card shows the task title, state indicator (● Idle), git branch name, action buttons (**Plan**, **Implement**, **Review**, **Finish**, **Continue**), and metrics (cost, sessions, checkpoint position).

1. Click the **"Plan"** button
2. Watch as the AI analyzes your requirements
3. The **Agent Output** section shows real-time progress
4. When complete, you'll see generated specifications

### Understanding the States

| State            | What's Happening              | What You Can Do                    |
|------------------|-------------------------------|------------------------------------|
| **Idle**         | Task created, waiting for you | Click Plan, Implement, or Continue |
| **Planning**     | AI is creating a plan         | Watch the output                   |
| **Implementing** | AI is writing code            | Watch the output                   |
| **Reviewing**    | Code review is running        | Check results                      |
| **Waiting**      | AI has a question             | Answer in the Questions section    |
| **Done**         | Task completed                | Finish or review changes           |

---

## Step 6: Review the Plan

After planning completes, you can review what the AI created:

1. Scroll to the **Specifications** section
2. Read through the implementation plan
3. If you want to change something, add a note

### Adding a Note (Optional)

Click the **"Add Note"** button and enter any clarifications:

```
Use our existing HTTP router pattern from main.go
```

This note will be included when the AI implements the task.

The **Specifications** section displays spec file names (e.g., `specification-1.md`) with expandable content showing the implementation plan, overview, and files to create. Action buttons include **Add Note** and **View Full Content**.

---

## Step 7: Implement

When you're happy with the plan, click the **"Implement"** button.

```text
┌────────────┐     ┌──────────────────┐     ┌────────────────┐     ┌─────────────────────┐     ┌──────────────────┐
│ Plan Ready │ ──▶ │ Click Implement  │ ──▶ │ AI Writes Code │ ──▶ │ Files Created/Mod.  │ ──▶ │ Ready for Review │
└────────────┘     └──────────────────┘     └────────────────┘     └─────────────────────┘     └──────────────────┘
```

Watch as the AI:
- Reads your specifications
- Analyzes your existing code
- Creates new files
- Modifies existing files
- Writes tests

### Real-Time Progress

The **Agent Output** section streams everything the AI does:

```
Analyzing codebase...
Reading specification 1...
Created: internal/health/handler.go
Modified: cmd/server/main.go
Created: internal/health/handler_test.go
```

The **Agent Output** panel shows live streaming updates with status indicators (checkmarks for completed actions, arrows for in-progress actions). It displays what the AI is analyzing, creating, and modifying in real-time.

---

## Step 8: Review Changes

After implementation completes, review what changed:

1. Scroll to **File Changes** section
2. See which files were created or modified
3. Click on files to see the actual changes (diff view)

The **File Changes** section lists files with status indicators (Created, Modified) and line counts. Click any file to expand and see the diff, showing the specific code changes made.

### Not Happy With Something?

Use **Undo** to go back:

1. Click the **"Undo"** button
2. Add a note explaining what to fix
3. Click **"Implement"** again

```text
                                    Yes ──▶ ┌──────────────┐
                               ┌────────────│ Click Finish │
┌────────────────┐     ┌───────┴──┐         └──────────────┘
│ Review Changes │ ──▶ │  Happy?  │
└────────────────┘     └───────┬──┘         ┌────────────┐     ┌──────────┐     ┌───────────────────┐
                               └────────────│ Click Undo │ ──▶ │ Add Note │ ──▶ │ Implement Again   │
                                    No ──▶  └────────────┘     └──────────┘     └───────────────────┘
```

---

## Step 9: Finish

When you're satisfied with the changes, click **"Finish"**.

This will:
- Run any quality checks (tests, linting)
- Merge your changes to the main branch
- Clean up the task branch
- Mark the task as complete

The **Finish Task** confirmation dialog shows the task name, status, a summary of changes (files created, modified, deleted, test status), and explains what happens next (quality checks, merge, branch cleanup, task completion). Action buttons include **Cancel** and **Confirm Finish**.

---

## What Each Button Does

Quick reference for the main dashboard buttons:

| Button        | What It Does                            | When to Use                            |
|---------------|-----------------------------------------|----------------------------------------|
| **Continue**  | Auto-runs the next logical step         | When you want to speed through         |
| **Plan**      | Generates implementation specifications | After creating a task                  |
| **Implement** | Writes code based on specifications     | After planning completes               |
| **Review**    | Runs automated code review              | After implementing                     |
| **Finish**    | Completes and merges the task           | When you're happy with changes         |
| **Undo**      | Goes back one checkpoint                | When something goes wrong              |
| **Redo**      | Goes forward one checkpoint             | After undoing, if you change your mind |
| **Abandon**   | Discards the task entirely              | When you want to cancel                |

---

## Common First-Time Questions

**Q: Do I need to keep the terminal open?**
A: Yes, the server runs in that terminal. Closing it stops the web UI.

**Q: Can I use the Web UI on another computer?**
A: Yes, but you'll need to set up authentication. See [Remote Access](remote-access.md).

**Q: What if the AI makes a mistake?**
A: Use the **Undo** button, add a note explaining what went wrong, and implement again.

**Q: Can I switch between CLI and Web UI?**
A: Absolutely! They're fully compatible. You can start a task in the browser and continue from the terminal (or vice versa).

**Q: Where are my files stored?**
A: Your code stays in your project directory. Task data (specs, sessions) is stored in `~/.valksor/mehrhof/` to keep your project clean.

**Q: How do I stop the server?**
A: Press `Ctrl+C` in the terminal where the server is running.

---

## Also Available via CLI

Prefer working from the terminal? See [Getting Started with the CLI](/guides/first-task.md) for the command-line workflow.

---

## Next Steps

After completing your first task:

- [**Creating Tasks**](creating-tasks.md) - Learn different task creation workflows
- [**Planning**](planning.md) - Deep dive into the planning phase
- [**Implementing**](implementing.md) - Understanding code generation
- [**Settings**](settings.md) - Configure agents, providers, and workflow
- [**Web UI vs CLI**](/guides/web-ui-vs-cli.md) - Understand when to use each interface
- [**Task Providers**](/providers/index.md) - Connect to GitHub, Jira, Linear, and more
