Documentation

What are Git Worktrees?

Imagine you're working on a feature in your project, but suddenly need to fix a critical bug. Normally, you'd have to:

• Stash or commit your incomplete work
• Switch branches
• Fix the bug
• Switch back
• Restore your work-in-progress

Git worktrees solve this problem. They let you check out multiple branches simultaneously, each in its own separate directory. Think of it as having multiple copies of your project, each on a different branch, but all sharing the same Git database.

How Lanes Uses Worktrees

When you create a new Lanes session, here's what happens under the hood:

Benefits of Complete Isolation

Opening the Git Changes Viewer

To review changes made in a session:

1. 1

   Click the "Show Git Changes" button in the session's action bar (the diff icon)

2. 2

   A new panel opens showing all file changes between your session branch and the comparison branch

3. 2

   This can be slow when there are many changes.

Understanding the Diff View

The diff viewer shows changes in a unified diff format:

Adding Review Comments

You can add comments to specific lines in the diff to provide feedback:

1. 1

   Click on any line in the diff view to select it

2. 2

   Type your comment in the input field that appears

3. 3

   Press Enter to save the comment

Comments are displayed inline with the code, making it easy to track your feedback as you review.

Submitting Your Review

Once you've added all your comments, you can generate a formatted review to share with your coding agent:

1. 1

   Click the "Submit Review" button at the top of the diff panel

2. 2

   The review is automatically copied to your clipboard in a structured markdown format

3. 3

   Paste the review into your coding agent's terminal or chat

Clipboard Format

The generated review follows a structured markdown format that's easy for AI agents to parse:

# Code Review Comments

## docs/docs.html

**Line 38** (added):
```
+    </script>
```
> Is this really a script tag? It seems misplaced.

**Line 142** (added):
```
+    const user = await getUser();
```
> Consider adding error handling for the getUser() call.

## src/utils/helper.ts

**Line 25** (removed):
```
-    // TODO: Remove this hack
```
> Good cleanup! But make sure the hack was actually fixed, not just the comment removed.

Supported Agents

Selecting an Agent

In the session creation form, click the agent logo at the top to cycle between available agents. The selected agent's logo is displayed inline, and the form adjusts available options accordingly.

Differences Between Agents

How to Attach Files

In the session creation form, you can attach files in two ways:

• Click to browse: Click the attachment area to open a file picker

Upload Progress

Each attached file shows an upload progress indicator. Once uploaded, file contents are processed and ready to be included with your prompt.

How Contents Are Included

When you create the session, file contents are appended to the starting prompt. The agent receives the full text of each file along with the filename, giving it immediate access to the context it needs.

Common Use Cases

Benefits

• Persistence: Sessions survive VS Code restarts and window reloads
• Resilience: Agent continues running even if VS Code crashes
• Scrollback: Full terminal history preserved in tmux

Configuration

Set the terminal mode in VS Code settings:

Prerequisites

Tmux must be installed on your system:

Per-Session Persistence

The terminal mode is stored per session, so each session remembers whether it was created with VS Code or tmux terminals. Changing the global setting only affects new sessions.

Configuration

Add to your VS Code settings:

How It Works

When you create a new session (worktree), Lanes checks if .claude/settings.local.json exists in your base repository. If it does and propagation is enabled, the file is copied or symlinked to <worktree>/.claude/settings.local.json.

Common Use Cases

What are Workflows?

A workflow is like a development playbook that Claude follows step-by-step. Each workflow defines:

Why Use Workflows?

Built-in Workflow Types

Lanes includes four workflow templates out of the box. Each is optimized for a specific type of development work:

How to Start a Workflow Session

When to Use Workflows vs. Ad-Hoc Sessions

YAML Structure Overview

Workflow templates are YAML files. Simple workflows only need name, description, and steps. The agents and loops sections are optional for more complex workflows:

Agents Definition

Agents are specialized roles that execute workflow steps. Each agent has specific capabilities and restrictions.

agents:
  orchestrator:
    description: Plans work and coordinates sub-agents

  implementer:
    description: Writes code to implement features
    

Steps (Main Workflow Sequence)

Steps define the main workflow sequence. They are executed in order from top to bottom.

steps:
  - id: plan
    type: action
    agent: orchestrator
    instructions: |
      Analyze the goal and break it into discrete tasks.

      Consider:
      1. What are the individual features or changes needed?
      2. What are the dependencies between tasks?
      3. What is the optimal order of implementation?

  - id: define_tasks
    type: action
    agent: orchestrator
    instructions: |
      Call workflow_set_tasks('feature_development', tasks) with:
      - id: unique identifier
      - title: concise title
      - description: detailed description

  - id: feature_development
    type: loop
    # References the loop defined above

  - id: final_review
    type: action
    agent: reviewer
    instructions: |
      Review the implementation as a whole...

Step Fields

Loops and Sub-steps

Loops are reusable sub-workflows that execute a sequence of steps for each task in a list. They enable structured iteration over features, fixes, or refactors.

loops:
  feature_development:
    - id: implement
      agent: implementer
      instructions: |
        Implement: {task.title}

        1. Read relevant files to understand context
        2. Plan the implementation approach
        3. Write the code
        4. Verify it compiles

    - id: test
      agent: tester
      instructions: |
        Run tests for: {task.title}

        1. Run the existing test suite
        2. Identify any failing tests
        3. Fix any test failures
        4. Ensure all tests pass
      on_fail: retry

    - id: review
      agent: reviewer
      instructions: |
        Review implementation of: {task.title}

        Check for:
        1. Security vulnerabilities
        2. Proper error handling
        3. Code quality and patterns

    - id: resolution
      instructions: |
        # No agent specified - main Claude handles this
        Address any issues from the review of: {task.title}

Task Variables

Within loop sub-step instructions, you can reference task properties using curly brace syntax:

instructions: |
  Implement: {task.title}

  Task ID for reference: {task.id}

  1. Read relevant files
  2. Implement the feature
  3. Verify it works

Step-by-Step Guide

Custom workflows let you define project-specific development processes. They appear in the "Custom" section of the workflow dropdown.

1. 1

   Define corresponding agents (if needed)

   First thing you will want to do is make sure you have already created all the agents you want to use in your workflow ahead of time. This is because agent names in your workflow must match either inline definitions or external agent files.

   mkdir -p .claude/agents
   # Create .claude/agents/my-agent.md

   Note: Inline agent definitions in the workflow file take precedence over external files.

2. 2

   Start creating a workflow document

   Open the Lanes sidebar → Open the "Workflow" window → Press the '+' icon.

3. 3

   Start creating a workflow document

   If you like, choose a template to start from (feature, bugfix, refactor, or default). This will create a new YAML file in .lanes/workflows/.

4. 4

   Write your workflow

   Edit your the template document, you can use the examples below or use the Workflow Structure page for guidance.

5. 5

   Validate your workflow

   The lanes extension comes with the 'Validate Workflow' command which you cna find in your command palette. This will check your workflow for common errors and help ensure it is correctly formatted.

6. 6

   Use the new Workflow

   The workflow should now appear in the workflow dropdown in the Lanes New Session window. You might need to use the refresh button. Select it to start using your custom workflow for new worktrees.

Simple Workflow Example

For straightforward tasks, you can create a workflow with just steps—no agents or loops required. The main Claude agent handles all steps directly:

# A minimal workflow - just name, description, and steps
name: simple-task
description: Execute a straightforward task

steps:
  - id: analyze
    type: action
    instructions: |
      Analyze the codebase and identify what needs to be done.

  - id: implement
    type: action
    instructions: |
      Implement the required changes.
      Ensure all tests pass.

  - id: verify
    type: action
    instructions: |
      Run tests and verify the implementation.
      Update documentation if needed.

Context Management and Artefact Tracking

For larger features, you can use context: clear to give Claude a fresh context window between planning and implementation. Combine this with artefacts: true to preserve important work across the reset:

name: feature-with-context-reset
description: Large feature development with context management

steps:
  - id: brainstorming
    type: action
    instructions: |
      Use brainstorming skill to explore the problem space.

  - id: writing-plans
    type: action
    artefacts: true  # Track created plan files
    instructions: |
      Create detailed implementation plans.
      Use "/writing-plans" skill from superpower to start.

  - id: implementation
    type: action
    context: clear  # Fresh context for implementation
    instructions: |
      Implement the features based on the plans.
      Use "/subagent-driven-development" skill to start.
      # Artefacts from previous step are available here

Complete Annotated Example (with Agents and Loops)

For complex workflows that need specialized agents and iteration over tasks, here's a complete template with detailed annotations:

# ==============================================================================
# WORKFLOW TEMPLATE: Custom Feature Development
# ==============================================================================

# Required: Unique name for this workflow
name: custom-dev-workflow

# Required: Description shown in workflow selector
description: Custom workflow for our team's feature development process

# ==============================================================================
# AGENTS: Define specialized roles with tool permissions
# ==============================================================================
agents:
  # Planning agent - can read code but not modify it
  planner:
    description: Analyzes requirements and breaks down work

  # Implementation agent - can write code but not commit
  coder:
    description: Implements features according to plan

  # Test agent - can run tests and fix test code
  tester:
    description: Runs tests and fixes failures

  # Review agent - read-only, provides feedback
  reviewer:
    description: Reviews code quality and security

# ==============================================================================
# LOOPS: Reusable sub-workflows that iterate over tasks
# ==============================================================================
loops:
  # This loop executes for each task in the task list
  build_feature:
    # Sub-step 1: Implement the feature
    - id: code
      agent: coder
      instructions: |
        Implement: {task.title}

        Steps:
        1. Read relevant files to understand context
        2. Plan your implementation approach
        3. Write the code
        4. Verify it compiles without errors

        Do NOT run tests - that's handled in the next step.

    # Sub-step 2: Test the implementation
    - id: test
      agent: tester
      instructions: |
        Test the implementation of: {task.title}

        1. Run the full test suite
        2. Identify any failing tests
        3. Fix test failures
        4. Ensure all tests pass
        5. Report test results
      on_fail: retry  # Retry if tests fail

    # Sub-step 3: Review the code
    - id: review
      agent: reviewer
      instructions: |
        Review the implementation of: {task.title}

        Check for:
        1. Security vulnerabilities
        2. Proper error handling
        3. Code quality and maintainability
        4. Adherence to project patterns
        5. Edge cases and potential bugs

        Provide specific feedback on any issues found.

    # Sub-step 4: Address review feedback (no agent = main Claude)
    - id: fix_issues
      instructions: |
        Review feedback for: {task.title}

        1. Read the reviewer's feedback
        2. If there are critical issues, fix them
        3. If there are minor suggestions, note them for future work
        4. Mark the task as complete

# ==============================================================================
# STEPS: Main workflow sequence (executed in order)
# ==============================================================================
steps:
  # Step 1: ACTION type - single operation by planner agent
  - id: analyze
    type: action
    agent: planner
    instructions: |
      Analyze the user's goal and break it into discrete tasks.

      Consider:
      1. What features or changes are needed?
      2. What are the dependencies between tasks?
      3. What is the optimal implementation order?

      Document your analysis clearly.

  # Step 2: ACTION type - planner defines the task list
  - id: create_tasks
    type: action
    agent: planner
    instructions: |
      Create a task list based on your analysis.

      For each task, define:
      - id: unique-identifier (e.g., 'add-login', 'fix-validation')
      - title: Clear, concise title (e.g., 'Add login form')
      - description: Detailed requirements

      Call workflow_set_tasks('build_feature', tasks) when ready.

  # Step 3: LOOP type - references the 'build_feature' loop above
  # This will execute all sub-steps for each task
  - id: build_feature
    type: loop

  # Step 4: ACTION type - final review of all changes
  - id: final_review
    type: action
    agent: reviewer
    instructions: |
      Review the complete implementation.

      Check:
      1. Consistency across all changes
      2. Integration between features
      3. Overall code quality
      4. Any missed requirements from the original goal

      Provide a summary of the implementation quality.

  # Step 5: ACTION type - finalize and prepare for commit
  - id: finalize
    type: action
    instructions: |
      # No agent specified - main Claude handles this
      Finalize the implementation.

      1. Review the final review feedback
      2. Address any critical issues
      3. Run final tests
      4. Prepare a summary of what was accomplished
      5. The workflow will complete and you can commit

Best Practices for Custom Workflows

Validation and Debugging

Lanes validates workflow templates when they're loaded. Common validation errors:

What is MCP?

The Model Context Protocol (MCP) is Anthropic's open protocol that enables AI assistants to securely connect to data sources and tools. It provides a standardized way to extend Claude with custom capabilities while maintaining security and control.

The Lanes MCP server is a specialized MCP implementation that gives Claude fine-grained control over workflow execution:

• Workflow State Management: Tracks current position in workflow, step outputs, and task progress
• Session Management: Allows Claude to request creation of new Lanes sessions programmatically
• Context Preservation: Maintains history across steps so agents can reference earlier work

Architecture

When you start a workflow session, Lanes automatically spins up an MCP server process that communicates with Claude via stdio:

┌─────────────────────────────────────────────────────────┐
│                    VS Code Extension                    │
│                                                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Start Workflow Session                          │  │
│  └──────────────────┬───────────────────────────────┘  │
│                     │                                   │
│                     ▼                                   │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Spawn MCP Server Process                        │  │
│  │  node server.js --worktree <path> --workflow-path│  │
│  └──────────────────┬───────────────────────────────┘  │
│                     │                                   │
│                     ▼                                   │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Generate .claude/mcp.json config                │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                      │
                      ▼ stdio transport
┌─────────────────────────────────────────────────────────┐
│                   MCP Server Process                    │
│                                                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Workflow State Machine                          │  │
│  │  - Current step/sub-step                         │  │
│  │  - Task iteration                                │  │
│  │  - Step outputs history                          │  │
│  └──────────────────────────────────────────────────┘  │
│                     │                                   │
│                     ▼                                   │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Tool Handlers                                   │  │
│  │  - workflow_start                                │  │
│  │  - workflow_set_tasks                            │  │
│  │  - workflow_status                               │  │
│  │  - workflow_advance                              │  │
│  │  - workflow_context                              │  │
│  │  - session_create                                │  │
│  │  - session_clear                                 │  │
│  └──────────────────────────────────────────────────┘  │
│                     │                                   │
│                     ▼                                   │
│  ┌──────────────────────────────────────────────────┐  │
│  │  File System Persistence                         │  │
│  │  - workflow-state.json (state)                   │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                      │
                      ▼ MCP protocol
┌─────────────────────────────────────────────────────────┐
│                    Claude Code                          │
│                                                         │
│  Calls MCP tools to navigate workflow steps             │
└─────────────────────────────────────────────────────────┘

The MCP server runs in the background for the lifetime of the session. Claude can call the MCP tools at any time to query or update workflow state.

MCP Tools Reference

The Lanes MCP server exposes six tools that Claude uses to control workflow execution:

{
  "status": "active",
  "step": {
    "id": "plan",
    "type": "action",
    "agent": "orchestrator",
    "instructions": "Analyze the goal and break it into..."
  },
  "progress": {
    "currentStepIndex": 0,
    "totalSteps": 5,
    "stepsCompleted": 0
  },
  "summary": "Add user authentication"
}

{
  "id": string,            // Unique identifier
  "title": string,         // Human-readable title
  "description"?: string   // Optional detailed description
}

{
  "success": true,
  "tasksSet": 3
}

workflow_set_tasks("feature_development", [
  {
    id: "login-form",
    title: "Create login form",
    description: "Build login form with email and password"
  },
  {
    id: "auth-api",
    title: "Implement auth API",
    description: "Create API endpoint for authentication"
  }
])

{
  "status": "active",
  "step": {
    "id": "feature_development",
    "type": "loop",
    "subStep": {
      "id": "implement",
      "agent": "implementer",
      "instructions": "Implement: Create login form..."
    }
  },
  "task": {
    "id": "login-form",
    "title": "Create login form",
    "index": 0,
    "total": 2
  },
  "progress": {
    "currentStepIndex": 2,
    "totalSteps": 5,
    "stepsCompleted": 1
  }
}

{
  "status": "active",
  "step": {
    "id": "feature_development",
    "type": "loop",
    "subStep": {
      "id": "test",
      "agent": "tester",
      "instructions": "Run tests for: Create login form..."
    }
  },
  "task": {
    "id": "login-form",
    "title": "Create login form",
    "index": 0,
    "total": 2
  },
  "progress": { ... }
}

{
  "plan": "Analyzed requirements. Identified 2 tasks: login-form, auth-api",
  "define_tasks": "Created task list with 2 tasks",
  "feature_development.login-form.implement": "Implemented login form with...",
  "feature_development.login-form.test": "All tests passing",
  "feature_development.login-form.review": "Code looks good, no issues"
}

{
  "success": true,
  "configPath": ".lanes/pending-sessions/fix-auth-bug-1736454321.json"
}

session_create(
  "fix-auth-bug",
  "main",
  "Fix authentication timeout issue",
  "bugfix"
)

{
  "success": true,
  "message": "Session context cleared"
}

session_clear()

Workflow State Persistence

The MCP server persists workflow state to workflow-state.json in the worktree root after every state change. This enables:

• Resume capability: If Claude crashes or loses context, calling workflow_start again restores to the current position
• Context preservation: All step outputs are stored and accessible via workflow_context
• Progress tracking: Current step, task progress, and completion status are persisted

{
  "status": "active",
  "currentStepIndex": 2,
  "currentSubStepIndex": 1,
  "currentTaskIndex": 0,
  "stepOutputs": {
    "plan": "Analyzed requirements...",
    "define_tasks": "Created task list...",
    "feature_development.login-form.implement": "Implemented login form..."
  },
  "loopTasks": {
    "feature_development": [
      {
        "id": "login-form",
        "title": "Create login form",
        "description": "Build login form with email and password",
        "status": "in_progress"
      },
      {
        "id": "auth-api",
        "title": "Implement auth API",
        "description": "Create API endpoint for authentication",
        "status": "pending"
      }
    ]
  },
  "summary": "Add user authentication"
}

Example Usage Flow

Here's how Claude uses the MCP tools to execute a typical workflow:

Claude calls: workflow_set_tasks("feature_development", [
  { id: "login-form", title: "Create login form", ... },
  { id: "auth-api", title: "Implement auth API", ... }
])

MCP Configuration

The Lanes MCP server is automatically configured when you create a workflow session. The VS Code extension:

1. Spawns the MCP server process with the workflow path and worktree path
2. Generates a .claude/mcp.json config file in the worktree
3. Passes the config to Claude Code via the --mcp-config flag

{
  "mcpServers": {
    "lanes-workflow": {
      "command": "node",
      "args": [
        "/path/to/lanes/dist/mcp/server.js",
        "--worktree", "/path/to/worktree",
        "--workflow-path", "/path/to/workflow.yaml"
      ]
    }
  }
}

The MCP server runs in the background for the lifetime of the session. It's automatically stopped when the session is closed.

Reporting Issues

Found a bug? Please report it through our issue tracker with as much detail as possible.

Issue Template

Suggesting Features

Have an idea for improving Lanes? We'd love to hear it! Please provide a clear description of the problem you're trying to solve.

Feature Request Template

Quick Links