Forem: Bilal Haidar

How to Use Claude.ai's Research Toggle Inside Claude Code

Bilal Haidar — Tue, 27 Jan 2026 06:31:06 +0000

The Missing Feature That Changes Everything

If you've been using Claude Code for development, you've probably noticed something frustrating: you can search the web, but you can't access Claude's powerful Research feature.

Web search gives you quick answers in seconds. Research gives you comprehensive, multi-source reports with citations in 5 to 30 minutes. They're not the same thing, and for serious technical decisions, Research is a game changer.

This guide shows you how to bring Research into Claude Code using a clever workaround that spawns a background agent to control your browser.

The Problem: Web Search vs Research

What Web Search Does

When you ask Claude Code to search the web, it:

Runs a single search query
Reads the top 10 results
Summarizes what it finds
Returns an answer in 10 to 30 seconds

This is great for quick lookups like "What's the syntax for Laravel's whereHas?" or "Who maintains this package?"

What Research Does

When you use the Research toggle in Claude.ai, it:

Breaks your question into multiple search strategies
Runs dozens of searches across different angles
Reads full articles, not just snippets
Follows links to related content
Cross-references sources for accuracy
Identifies patterns and contradictions
Synthesizes everything into a comprehensive report
Includes proper citations

This takes 5 to 30 minutes, but the output is dramatically different.

Real World Comparison

Query: "What's new in Laravel 12?"

Web Search Result:

Laravel 12 introduces several new features including improved routing performance and better Eloquent query optimization. The release focuses on developer experience improvements.

Research Result:

A 15+ paragraph report covering:

Complete feature changelog with code examples

Breaking changes from Laravel 11

Step by step migration guide

Performance benchmarks comparing v11 vs v12

Community reception and early adopter feedback

Package compatibility status

Links to 20+ authoritative sources

For architectural decisions, migration planning, or evaluating new technologies, Research is worth the wait.

The Gap

Claude Code has web search built in. But the Research toggle only exists in the Claude.ai web interface. There's no /research command, no API endpoint, no native way to access it from your terminal.

Until now.

The Solution: Background Agents + Chrome Automation

Here's the insight: Claude Code can control your Chrome browser through the Claude in Chrome extension. And Claude.ai runs in Chrome. So we can make Claude Code open Claude.ai, toggle Research, run a query, and extract the results.

But there's a catch. Research takes 5 to 30 minutes. If we run this as a normal task, Claude Code would block and wait, wasting your time.

The solution is background agents. We spawn a dedicated agent that runs the Research automation while your main Claude Code session continues working on other tasks. When Research completes, the results are saved to your project and the agent reports back.

Architecture

┌─────────────────────────────────────┐
│  Your Main Claude Code Session      │
│  (Keep working on other tasks)      │
└──────────────────┬──────────────────┘
                   │ Spawn background agent
                   ▼
┌─────────────────────────────────────┐
│  Background Agent                   │
│  (Dedicated to research task)       │
└──────────────────┬──────────────────┘
                   │ Uses claude --chrome
                   ▼
┌─────────────────────────────────────┐
│  Claude in Chrome Extension         │
│  (Controls your browser)            │
└──────────────────┬──────────────────┘
                   │ Navigates and interacts
                   ▼
┌─────────────────────────────────────┐
│  Claude.ai Research Feature         │
│  (Runs for 5-30 minutes)            │
└──────────────────┬──────────────────┘
                   │ Extracts results
                   ▼
┌─────────────────────────────────────┐
│  ./docs/research/report.md          │
│  (Saved to your project)            │
└─────────────────────────────────────┘

Prerequisites

Before setting this up, you need:

Requirement	Details
Claude Code	Version 2.0.60 or higher (for background agents)
Claude Plan	Pro, Team, Max, or Enterprise (Research requires paid plan)
Chrome	Google Chrome browser (not Brave, Arc, or other Chromium browsers)
Claude in Chrome	The official extension from Anthropic

Install Claude in Chrome Extension

Visit Claude Chrome Extension
Click "Add to Chrome"
Sign in with your Claude account when prompted
Pin the extension to your toolbar (click puzzle icon, then pin)

Critical Fix: The Native Messaging Conflict

If you have both Claude Desktop and Claude Code installed, there's a conflict that prevents claude --chrome from connecting to the browser extension.

Diagnosing the Problem

Run this command:

ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/

If you see both of these files, you have the conflict:

com.anthropic.claude_browser_extension.json      ← Claude Desktop
com.anthropic.claude_code_browser_extension.json ← Claude Code

Chrome connects to the first one (Claude Desktop) and ignores Claude Code.

The Fix

Back up the Claude Desktop configuration:

mv ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json \
   ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json.backup

Then:

Quit Chrome completely (Cmd+Q on Mac, not just closing the window)
Restart Chrome
Open the Claude extension by clicking its icon in the toolbar
Test the connection with claude --chrome

Reverting Later

If you need Claude Desktop's Chrome integration back:

mv ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json.backup \
   ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json

Installing the Research Skill

The Research skill consists of several files that tell Claude Code how to perform the automation.

File Structure

~/.claude/skills/web-research-task/
├── SKILL.md                    # Main skill documentation
├── agent-prompt.md             # Step-by-step instructions for the agent
└── commands/
    └── research-via-web.md     # Slash command definition

Step 1: Create the Directories

mkdir -p ~/.claude/skills/web-research-task/commands

Step 2: Create SKILL.md

Save this as ~/.claude/skills/web-research-task/SKILL.md:

# Claude Web Research Task

## Purpose
This skill enables Claude Code to spawn a dedicated background agent that uses 
Claude in Chrome to access Claude.ai's Research toggle, run deep research 
queries, and return comprehensive results.

IMPORTANT: This task MUST run as a background agent because Research takes 
5 to 30+ minutes. Do NOT skip this step or try to inline it into other workflows.

## Prerequisites

1. Claude in Chrome Extension installed and authenticated
2. Claude Code v2.0.60+ (for background agents)
3. Paid Claude subscription (Pro/Team/Max/Enterprise)
4. Chrome browser running

## How to Invoke

### Option 1: Background Agent (Recommended)

Start Claude Code with Chrome integration:
  claude --chrome

Then spawn the research task:
  Spawn a background agent to research via Claude.ai: "Your query here"

Press Ctrl+Shift+B if not automatically backgrounded.

### Option 2: Slash Command

  /research-via-web "Your query here"

## Workflow Steps

The background agent will:

1. Open new Chrome tab to https://claude.ai
2. Wait for page load
3. Click "Research" toggle (bottom left of chat interface)
4. Enter the research query in the chat input
5. Submit and wait for research to complete (5-30 minutes)
6. Extract the full response including citations
7. Save to file: ./docs/research/[timestamp]-[query-slug].md
8. Return summary to main Claude Code session

## Critical Instructions

When executing this task:

- Run as BACKGROUND AGENT (use run_in_background: true)
- DO NOT attempt to speed this up or skip steps
- WAIT for the Research feature to fully complete
- Poll the page every 30 seconds to check completion status
- Only extract results AFTER seeing the full research output

## Expected Timeline

| Phase | Duration |
|-------|----------|
| Navigate to claude.ai | 5-10 seconds |
| Toggle Research | 2-5 seconds |
| Enter query | 5-10 seconds |
| Research execution | 5-30 minutes |
| Extract results | 10-30 seconds |
| Save to file | 2-5 seconds |

Total: 6 to 35 minutes (mostly waiting for Research)

Step 3: Create agent-prompt.md

Save this as ~/.claude/skills/web-research-task/agent-prompt.md:

# Web Research Agent Instructions

You are a background agent tasked with performing deep research using 
Claude.ai's Research feature via Chrome automation.

## Your Mission

Execute deep research through the Claude.ai web interface and return 
comprehensive results.

## Step-by-Step Execution

### Step 1: Navigate to Claude.ai

Open a new Chrome tab and navigate to https://claude.ai

Wait for the page to fully load. Look for:
- The chat interface
- The model selector
- The input field at the bottom

If you see a login screen, STOP and notify the user.

### Step 2: Start a New Conversation

Click "New chat" to ensure you have a fresh conversation.

### Step 3: Enable Research Toggle

Location: Bottom left of the chat interface, look for "Research" button.

Action: Click the Research toggle to enable it. The button should change 
state (often turns blue or shows as active).

Verification: Confirm Research mode is enabled before proceeding.

### Step 4: Enter the Research Query

Type the research query into the chat input field.

### Step 5: Submit and Monitor

Press Enter or click Send to submit the query.

CRITICAL WAITING PERIOD:
- Research takes 5 to 30+ minutes
- DO NOT interrupt or timeout early
- Poll the page every 30 to 60 seconds to check status

Completion indicators:
- Research progress bar reaches 100%
- "Research complete" message appears
- Final formatted output with citations is visible
- No more loading indicators

### Step 6: Extract Results

Once complete, extract:
1. The full research response text
2. All citations and sources
3. Any structured data or summaries

### Step 7: Save Results

Create the output file with this format:

Filename: YYYYMMDD-HHMMSS-[query-slug].md

Content:
# Research: [Query Title]

**Generated**: [ISO Timestamp]
**Duration**: [Approximate duration]
**Source**: Claude.ai Research Feature
**Query**: [Original query]

---

[FULL RESEARCH CONTENT HERE]

---

## Sources Referenced

[List all citations from the research]

Save location: ./docs/research/

### Step 8: Report Back

Return to the main Claude Code session with:
- Confirmation of completion
- File path where results are saved
- Brief 2-3 sentence summary of key findings

## Important Reminders

1. PATIENCE IS REQUIRED: Research is slow by design. Do not rush.
2. BACKGROUND ONLY: This task must run as a background agent.
3. COMPLETE EXTRACTION: Wait for ALL content before extracting.
4. PRESERVE CITATIONS: Sources are critical; never omit them.

Step 4: Create the Slash Command

Save this as ~/.claude/skills/web-research-task/commands/research-via-web.md:

# /research-via-web

Execute deep research using Claude.ai's Research feature via Chrome automation.

## Usage

  /research-via-web "Your research query here"

## Behavior

This command MUST be run as a background agent. When invoked:

1. Spawns a dedicated background agent
2. Uses Claude in Chrome to navigate to claude.ai
3. Enables the Research toggle
4. Submits the query
5. Waits for full completion (5 to 30 minutes)
6. Extracts and saves results to ./docs/research/

## CRITICAL: Background Execution Required

Research takes significant time. This command runs autonomously while 
you continue other work.

Press Ctrl+Shift+B after invoking to send to background if needed.

## Examples

  /research-via-web "Compare Inertia.js vs Livewire for Laravel SPAs in 2026"

  /research-via-web "Best practices for SQL Server query optimization"

  /research-via-web "SharePoint Framework SPFx performance patterns"

## Output Location

Results saved to: ./docs/research/YYYYMMDD-HHMMSS-query-slug.md

Step 5: Add to Your Project's CLAUDE.md

Add this section to your project's CLAUDE.md file:

## Deep Research via Claude.ai

When deep research is needed (not just web search), spawn a background agent:

  Spawn a background agent for web research: "YOUR QUERY"

Or use the slash command:

  /research-via-web "YOUR QUERY"

This opens Claude.ai via Chrome, toggles Research, runs the query, and 
saves results to ./docs/research/

CRITICAL: This MUST run as background agent. Takes 5 to 30 minutes. 
Do not skip or inline into other workflows.

### When to Use Research vs Web Search

| Use Research | Use Web Search |
|--------------|----------------|
| Complex analysis | Quick fact lookup |
| Multi-source synthesis | Single answer needed |
| Comprehensive reports | During active coding |
| When citations matter | Speed is priority |

Using the Research Skill

Step 1: Start Claude Code with Chrome

claude --chrome

You should see a message indicating the Chrome extension is connected.

Step 2: Verify Connection

Type /chrome in Claude Code to check the connection status. You should see the extension is detected and connected.

Step 3: Run a Research Task

Option A - Natural language:

Spawn a background agent to research via Claude.ai: "What are the latest Laravel 12 features and breaking changes from Laravel 11?"

Option B - Slash command:

/research-via-web "What are the latest Laravel 12 features and breaking changes from Laravel 11?"

Step 4: Send to Background (if needed)

If the task doesn't automatically run in the background, press Ctrl+Shift+B to send it to the background.

Step 5: Continue Working

Your main Claude Code session is free. Continue coding, run other commands, or start another task.

Step 6: Check Status

To see how your background agent is doing:

/bashes

Or ask:

Show status of background agents

Step 7: Review Results

When complete, the agent saves results to:

./docs/research/YYYYMMDD-HHMMSS-query-slug.md

You can reference this file in your main session:

@docs/research/20260126-143022-laravel-12-features.md

Summarize the key breaking changes I need to handle for migration

Example Workflow

Here's a real workflow for planning a Laravel 11 to 12 migration:

# Start Claude Code with Chrome

claude --chrome

# Spawn research on Laravel 12 changes

> Spawn a background agent to research via Claude.ai: "Complete Laravel 12 migration guide from Laravel 11, including all breaking changes, deprecated features, and new requirements"

# Agent starts in background, you continue working

> Review my routes/web.php for any deprecated patterns

# Check research progress

> /bashes

# 20 minutes later, research completes

# Results saved to ./docs/research/20260126-laravel-12-migration.md

# Use the research in your work

> @docs/research/20260126-laravel-12-migration.md

> Based on this research, create a migration checklist for my project

Troubleshooting

"Browser extension is not connected"

Check if Chrome is running
Check if extension is installed and signed in
Run the native messaging fix (see Critical Fix section above)
Restart Chrome completely (Cmd+Q)
Try claude --chrome again

Research toggle not found

Ensure you have a paid Claude plan (Pro, Team, Max, or Enterprise)
The Research toggle is at the bottom left of the Claude.ai chat interface
Try manually verifying it exists by visiting claude.ai

Task times out

Research can legitimately take 30+ minutes for complex queries
Don't interrupt the process
If it fails, try a more specific query

Agent skips the Research step

Make sure you're running as a background agent
The skill files must be installed correctly
Check that CLAUDE.md includes the instruction to NOT skip Research

Why This Matters

This setup bridges a significant gap in Claude Code's capabilities. For developers making architectural decisions, evaluating technologies, or planning migrations, the difference between a 10-second web search and a 20-minute deep research session is the difference between a guess and an informed decision.

The background agent approach means you don't have to choose between thoroughness and productivity. Start the research, continue your work, and integrate the findings when they're ready.

It's Claude helping Claude help you.

Credits

Original idea by @EleanorKonik. This article formalizes her concept into a working implementation.

The Task Tool: Claude Code's Agent Orchestration System

Bilal Haidar — Tue, 27 Jan 2026 06:20:00 +0000

Introduction
What is the Task Tool?
How It Works
Available Agent Types
Background vs Foreground Execution
When to Use Which Agent
Practical Examples
Managing Background Tasks
Best Practices
Common Patterns
Troubleshooting

Introduction

The Task tool is Claude Code's most powerful feature for handling complex, multi-step operations. Think of it as Claude's ability to spawn specialized "colleagues" - autonomous sub-agents that can work independently while you continue with other tasks.

Key Insight: Claude Code isn't just one AI - it's a system that can orchestrate multiple AI agents, each with specialized skills and tools, working in parallel or sequence to accomplish complex goals.

What is the Task Tool?

The Task tool is a function that allows Claude to:

Spawn sub-agents: Create separate Claude instances with specialized capabilities
Delegate work: Assign specific tasks with detailed instructions
Run autonomously: Sub-agents work independently until task completion
Execute in background: Long-running tasks don't block your workflow
Return results: Completed work is reported back to the main session

Architecture

Main Claude Session (You interact here)
    ↓
    ├─→ Task Tool invocation
    │       ↓
    │   Sub-Agent (Specialized Claude instance)
    │       ├─→ Has own context & memory
    │       ├─→ Access to specific tools
    │       ├─→ Works autonomously
    │       └─→ Returns results when done
    │
    └─→ You continue working (if background)

How It Works

Basic Invocation

When Claude calls the Task tool:

<invoke name="Task">
  <parameter name="subagent_type">general-purpose</parameter>
  <parameter name="description">Short task description</parameter>
  <parameter name="prompt">Detailed instructions for the sub-agent</parameter>
  <parameter name="run_in_background">true</parameter>
  <parameter name="model">haiku</parameter> <!-- Optional: use faster model -->
</invoke>

What Happens

Agent Creation: New Claude instance spawned with specified type
Context Loading: Agent receives the prompt with all necessary instructions
Autonomous Execution: Agent uses its available tools to complete the task
Result Reporting: Agent returns findings/outputs to main session
Cleanup: Agent terminates after completion

Key Parameters

Parameter	Required	Description
`subagent_type`	✅ Yes	Which specialized agent to use
`description`	✅ Yes	3-5 word summary of task
`prompt`	✅ Yes	Detailed instructions for agent
`run_in_background`	❌ No	Run async (true) or blocking (false)
`model`	❌ No	`sonnet` (default), `opus`, or `haiku`
`resume`	❌ No	Resume a previous agent by ID

Available Agent Types

1. General-Purpose Agent

Tools Available: All tools (Read, Write, Edit, Grep, Glob, Bash, WebFetch, WebSearch, etc.)

Best For:

Complex research tasks
Multi-step file operations
Web scraping and analysis
Tasks requiring multiple tool types
Open-ended exploration

Example Use Cases:

- "Search the codebase for all API endpoints and document them"
- "Research best practices for implementing OAuth 2.0"
- "Find all TODO comments and create GitHub issues"
- "Analyze dependencies and identify outdated packages"

When Claude Uses It:

You ask for research that requires multiple searches
Complex codebase analysis spanning many files
Tasks that need both web research and code inspection

2. Explore Agent

Tools Available: Glob, Grep, LS, Read, NotebookRead, WebFetch, WebSearch (NO Edit/Write)

Best For:

Fast codebase exploration
Finding files by patterns
Searching code for keywords
Answering "where/how" questions about code
Read-only analysis

Thoroughness Levels:

quick: Basic searches, first match priority
medium: Moderate exploration, multiple locations
very thorough: Comprehensive analysis, all possibilities

Example Use Cases:

- "Where are errors from the client handled?"
- "What is the codebase structure?"
- "Find all files that use the Authentication service"
- "How does the payment processing flow work?"

When Claude Uses It:

You ask exploratory questions about the codebase
Need to understand architecture or flow
Searching for patterns across many files
Read-only investigation needed

Performance: Faster than general-purpose for search tasks because it has fewer tools to consider.

3. Plan Agent

Tools Available: All tools EXCEPT Task, ExitPlanMode, Edit, Write, NotebookEdit

Best For:

Designing implementation strategies
Creating step-by-step plans
Identifying critical files before coding
Considering architectural trade-offs
Planning complex features

Workflow:

Agent explores codebase
Analyzes existing patterns
Designs implementation approach
Returns detailed plan for approval
Main Claude executes plan after approval

Example Use Cases:

- "Plan implementation of user authentication"
- "Design a strategy for migrating to a new database"
- "Create a refactoring plan for the API layer"
- "Plan how to add real-time notifications"

When Claude Uses It:

Tasks require architectural decisions
Multiple valid implementation approaches exist
Large-scale changes affecting many files
User explicitly enters "plan mode"

4. Bash Agent

Tools Available: Bash only

Best For:

Git operations
Command execution
Terminal tasks
Running scripts
System operations

Example Use Cases:

- "Run git operations to create a feature branch"
- "Execute npm install and build"
- "Run database migrations"
- "Clean up temporary files"

When Claude Uses It:

Git-heavy workflows
Command-line only operations
No file reading/editing needed

5. Feature Development Agents

code-reviewer

Best For: PR reviews, bug detection, security analysis, code quality

code-explorer

Best For: Deep feature analysis, tracing execution paths, understanding dependencies

code-architect

Best For: Feature architecture design, implementation blueprints, build sequences

6. Specialized Plugin Agents

statusline-setup: Configure Claude Code status line
claude-code-guide: Answer questions about Claude Code features
agent-sdk-dev: Verify Agent SDK applications
plugin-dev: Plugin creation and validation
code-simplifier: Refactor code for clarity
laravel-simplifier: PHP/Laravel specific refactoring

Background vs Foreground Execution

Foreground (Default)

Behavior:

Blocks main session until completion
You wait for results before continuing
Claude pauses until agent finishes

Use When:

Task takes <30 seconds
You need results immediately to continue
Task is prerequisite for next steps

Example:

"Search for all API endpoints" (blocks for 10 seconds, returns results, you continue)

Background (`run_in_background: true`)

Behavior:

Agent runs asynchronously
You can continue with other work
Notification when complete
Output saved to file

Use When:

Task takes >1 minute
You don't need results immediately
Task is independent of current work
Long-running operations (builds, tests, research)

Example:

"Run comprehensive test suite" (launches in background, you continue coding, notified when done)

How to Request Background Execution

Option 1: Natural language

"Spawn a background agent to run web research for Laravel packages"

Option 2: Keyboard shortcut

Press Ctrl+Shift+B when invoking a task

Option 3: Explicit instruction

"Run this as a background task: analyze the entire codebase for security issues"

When to Use Which Agent

Decision Tree

Do you need to WRITE or EDIT code?
├─ YES → general-purpose or feature-dev agents
└─ NO → Continue...

Is it codebase EXPLORATION?
├─ YES → Explore agent
└─ NO → Continue...

Is it PLANNING before implementation?
├─ YES → Plan agent
└─ NO → Continue...

Is it ONLY bash commands?
├─ YES → Bash agent
└─ NO → general-purpose agent

Quick Reference

Task Type	Agent	Background?
Find files/patterns	Explore	No (fast)
Answer code questions	Explore	No (fast)
Web research	general-purpose	YES
Multi-file refactor	general-purpose	Maybe
Plan feature	Plan	No
Run tests	Bash	YES
Build project	Bash	YES
Code review	code-reviewer	Maybe
Security audit	code-reviewer	YES

Practical Examples

Example 1: Codebase Exploration

User Request: "Where is authentication handled?"

Claude's Decision:

<invoke name="Task">
  <parameter name="subagent_type">Explore</parameter>
  <parameter name="description">Find authentication handling</parameter>
  <parameter name="prompt">
    Search the codebase to find where authentication is handled.
    Look for:
    - Auth middleware
    - Login controllers
    - Authentication services
    - JWT/session handling

    Return file paths and brief descriptions.
  </parameter>
</invoke>

Why Explore?: Read-only search, no edits needed, fast results.

Example 2: Deep Web Research

User Request: "/research-via-web 'Laravel latest packages'"

Claude's Decision:

<invoke name="Task">
  <parameter name="subagent_type">general-purpose</parameter>
  <parameter name="description">Research Laravel packages</parameter>
  <parameter name="run_in_background">true</parameter>
  <parameter name="prompt">
    Use Claude in Chrome to access claude.ai Research feature.

    Steps:
    1. Navigate to claude.ai
    2. Enable Research toggle
    3. Submit query: "Laravel latest packages 2026"
    4. Wait 5-30 minutes for completion
    5. Extract full results with citations
    6. Save to ./docs/research/[timestamp]-laravel-packages.md

    Return summary when complete.
  </parameter>
</invoke>

Why general-purpose + background?:

Needs browser automation tools
Takes 5-30 minutes
Complex multi-step workflow
User can continue working

Example 3: Feature Planning

User Request: "Add dark mode to the application"

Claude's Decision:

<invoke name="Task">
  <parameter name="subagent_type">Plan</parameter>
  <parameter name="description">Plan dark mode implementation</parameter>
  <parameter name="prompt">
    Design an implementation plan for adding dark mode.

    Explore:
    - Current styling approach (CSS/Tailwind/CSS-in-JS)
    - Existing theme infrastructure
    - Components that need updates

    Plan:
    - Theme toggle component
    - State management approach
    - CSS variable strategy
    - Component modifications needed

    Return step-by-step implementation plan.
  </parameter>
</invoke>

Why Plan?: Architectural decision, multiple approaches possible, user should approve before implementation.

Example 4: Running Tests

User Request: "Run the test suite"

Claude's Decision:

<invoke name="Task">
  <parameter name="subagent_type">Bash</parameter>
  <parameter name="description">Run test suite</parameter>
  <parameter name="run_in_background">true</parameter>
  <parameter name="prompt">
    Execute the test suite:

    1. Run: npm test (or appropriate test command)
    2. Capture full output
    3. Report:
       - Pass/fail summary
       - Failed test details
       - Coverage metrics if available
  </parameter>
</invoke>

Why Bash + background?:

Command-line only
May take several minutes
User doesn't need to wait

Example 5: Security Review

User Request: "Review this PR for security issues"

Claude's Decision:

<invoke name="Task">
  <parameter name="subagent_type">code-reviewer</parameter>
  <parameter name="description">Security review PR #123</parameter>
  <parameter name="prompt">
    Review PR #123 for security vulnerabilities:

    Check for:
    - SQL injection risks
    - XSS vulnerabilities
    - Authentication bypasses
    - Insecure dependencies
    - Exposed secrets

    Use confidence-based filtering - only report high-priority issues.
  </parameter>
</invoke>

Why code-reviewer?: Specialized for security analysis, confidence filtering, review workflows.

Managing Background Tasks

View All Tasks

/tasks

Or:

Show status of all background agents

Output:

Background Tasks:
- ac88940: Research Laravel packages (running, 18 min)
- ac88941: Run test suite (completed, 3 min ago)

Check Task Progress

Option 1: Read output file

Read /private/tmp/claude/-Users-you-project/tasks/ac88940.output

Option 2: Tail live output

tail -f /private/tmp/claude/-Users-you-project/tasks/ac88940.output

Option 3: Wait for notification

(Claude automatically notifies you when complete)

Kill a Task

Kill background task ac88940

Or use the KillShell tool if it's a Bash background task.

Resume a Task

If a task was interrupted or you want to continue work:

<invoke name="Task">
  <parameter name="subagent_type">general-purpose</parameter>
  <parameter name="resume">ac88940</parameter>
  <parameter name="prompt">Continue from where you left off...</parameter>
</invoke>

Use Case: Agent hit rate limits, network issues, or you want to add follow-up instructions.

Best Practices

1. Choose the Right Agent

❌ Don't: Use general-purpose for simple searches

"Find the User model" → general-purpose agent (overkill)

✅ Do: Use Explore for read-only searches

"Find the User model" → Explore agent (faster, appropriate)

2. Be Specific in Prompts

❌ Don't: Vague instructions

"Research authentication"

✅ Do: Detailed, structured prompts

"Research OAuth 2.0 implementation best practices for Laravel.
Include:
- Authorization code flow setup
- Token storage strategies
- Security considerations
- Popular Laravel packages
Provide code examples and cite sources."

3. Use Background for Long Tasks

❌ Don't: Block for minutes

"Run full test suite" → foreground (you wait 5 minutes)

✅ Do: Background long operations

"Run full test suite in background" → continue working, notified when done

Rule of Thumb: If task takes >30 seconds, run in background.

4. Model Selection

Sonnet (default): Best quality, moderate speed

Complex tasks, code generation, architectural decisions

Haiku: Fast, cost-effective

Simple searches, quick analysis, repetitive tasks

Opus: Maximum capability (rarely needed)

Extremely complex reasoning, critical decisions

Example:

<parameter name="model">haiku</parameter>  <!-- For quick file search -->

5. Don't Nest Tasks Unnecessarily

❌ Don't: Task within task within task

Main → Task → Sub-Task → Sub-Sub-Task (complexity explosion)

✅ Do: Flatten when possible

Main → Task with comprehensive instructions

Exception: Legitimate parallel work (e.g., Plan agent explores, then reports to main Claude who executes).

6. Provide Context

Agents don't automatically see your full conversation history. Give them what they need:

❌ Don't:

"Fix the bug we discussed earlier"  (agent has no idea)

✅ Do:

"Fix the bug in src/api/users.js:45 where user.name is undefined.
Error: Cannot read property 'name' of undefined.
This happens when the API returns null for deleted users.
Add null check before accessing properties."

Common Patterns

Pattern 1: Explore → Plan → Execute

User: "Add user authentication"

Step 1: Explore agent
  → Understand current auth infrastructure
  → Find related files
  → Identify patterns

Step 2: Plan agent
  → Design implementation strategy
  → Return plan for approval

Step 3: Main Claude
  → Execute approved plan
  → Write code
  → Run tests

Pattern 2: Parallel Background Tasks

User: "Prepare for deployment"

Launch simultaneously:
- Background Task 1: Run test suite
- Background Task 2: Build production assets
- Background Task 3: Run security audit
- Background Task 4: Update dependencies

All complete → Review results → Deploy

Pattern 3: Research → Implement

User: "Implement rate limiting"

Step 1: general-purpose agent (background)
  → Research rate limiting strategies
  → Find Laravel packages
  → Best practices documentation

Step 2: Main Claude (after research completes)
  → Review research findings
  → Choose approach with user
  → Implement solution

Pattern 4: Iterative Exploration

User: "How does the payment flow work?"

Step 1: Explore agent
  → Find PaymentController
  → Returns initial findings

Step 2: Explore agent (resume or new)
  → "Now trace what happens in PaymentService"
  → Returns service details

Step 3: Explore agent
  → "Check the webhook handlers"
  → Complete picture emerges

Troubleshooting

Issue: Task Takes Too Long

Symptoms: Background task running for hours

Solutions:

Check output file: tail -f /path/to/task.output
Look for stuck browser operations, infinite loops, or waiting
Kill and relaunch with refined prompt
Use faster model (haiku) if appropriate

Issue: Task Fails Immediately

Symptoms: Error returned right away

Common Causes:

Missing required parameters
Invalid agent type
Malformed prompt
Tool access restrictions

Solution: Check error message, verify agent has needed tools

Issue: Agent Can't Find Files

Symptoms: "No files found" despite files existing

Solutions:

Verify working directory in prompt
Check file paths are correct
Use absolute paths instead of relative
Try different search patterns (glob vs grep)

Issue: Background Task Not Notifying

Symptoms: Task completes but you don't see results

Solutions:

Manually read output file
Check /tasks for completion status
Verify run_in_background: true was set
Look in task output directory

Issue: Out of Context/Tokens

Symptoms: Agent fails with context limit error

Solutions:

Break task into smaller sub-tasks
Use more specific search parameters
Limit file reads to essential sections
Use haiku model for smaller context

Advanced Techniques

Technique 1: Chained Agents

Run agents sequentially where each builds on previous:

Agent 1 (Explore): Find all API endpoints → saves to api-list.md
Agent 2 (general-purpose): Read api-list.md, generate OpenAPI spec
Agent 3 (code-reviewer): Review OpenAPI spec for completeness

Technique 2: Parallel Research

Launch multiple research agents simultaneously:

Background Agent 1: Research authentication methods
Background Agent 2: Research authorization patterns
Background Agent 3: Research session management

All complete → Synthesize findings → Choose approach

Technique 3: Recursive Exploration

Agent explores, finds new areas, spawns new agents:

Explore Agent: "Map the application architecture"
  → Finds frontend/, backend/, mobile/
  → Reports back

Main Claude spawns 3 new Explore agents:
  → Agent A: Explore frontend/
  → Agent B: Explore backend/
  → Agent C: Explore mobile/

All report back → Main Claude synthesizes complete map

Technique 4: Progressive Refinement

Use agent results to refine next agent's instructions:

Agent 1: "Find authentication code"
  → Returns 50 files

Agent 2: "Focus on JWT implementation in these 10 files: [list]"
  → Returns detailed JWT analysis

Agent 3: "Check these 3 security concerns in the JWT code: [specifics]"
  → Returns security audit

Conclusion

The Task tool transforms Claude Code from a helpful assistant into an orchestration system for autonomous AI agents. By understanding:

Which agent to use (Explore for searching, general-purpose for complex work, Plan for architecture)
When to use background (tasks >30 seconds, independent work)
How to write effective prompts (specific, structured, with context)
Managing task lifecycle (viewing, monitoring, killing, resuming)

You can tackle increasingly complex workflows while maintaining productivity.

Key Takeaway: Don't think of Claude Code as a single AI - think of it as a team of specialized AIs you can deploy in parallel to accomplish sophisticated goals.

Further Reading:

Claude Code documentation: https://claude.com/code
Agent SDK for building custom agents
Plugin development for extending agent capabilities

How to Properly Deprecate API Endpoints in Laravel

Bilal Haidar — Fri, 09 Jan 2026 10:01:29 +0000

API evolution is inevitable. As your application grows, you'll need to phase out old endpoints while maintaining backward compatibility. But what happens when you need to deprecate only one HTTP method of an endpoint while keeping others active?

In this post, I'll show you how to handle a common scenario: deprecating a GET request while keeping the POST request active on the same route, using the same controller.

The Problem

Imagine you have this route setup:

  // modules/Products/Routes/api.php
  Route::get('/products/{id}/export', ProductExportController::class)->name('export');
  Route::post('/products/{id}/export', ProductExportController::class)->name('export');

Both routes use the same controller, but you want to deprecate the GET method while keeping POST active. Simply adding deprecation headers in the controller would affect both methods.

Why Proper Deprecation Matters

Before diving into solutions, let's understand why this matters:

Client Communication: Consumers need advance notice to migrate
Standards Compliance: HTTP has standard headers for deprecation (Deprecation, Sunset)
Monitoring: Track which clients still use deprecated endpoints
Graceful Migration: Avoid breaking production systems

Solution 1: Separate Legacy Controller (Recommended)

The cleanest approach is to create a dedicated controller for the deprecated endpoint that delegates to the main controller while adding deprecation headers.

Step 1: Create the Legacy Controller

  // app/Http/Controllers/ProductExportLegacyController.php
  <?php

  namespace App\Http\Controllers;

  use Illuminate\Http\Request;

  class ProductExportLegacyController
  {
      public function __invoke(Request $request, $id)
      {
          // Delegate to the main controller
          $response = app(ProductExportController::class)($request, $id);

          // Add deprecation headers
          return $response
              ->header('Deprecation', 'true')
              ->header('Sunset', 'Sat, 01 Jun 2026 00:00:00 GMT')
              ->header('X-API-Warn', 'This endpoint is deprecated. Use POST /products/{id}/export instead');
      }
  }

Step 2: Update Your Routes

  // Deprecated GET endpoint
  Route::get('/products/{id}/export', ProductExportLegacyController::class)
      ->name('exportLegacy'); // DEPRECATED - Use POST instead

  // Active POST endpoint
  Route::post('/products/{id}/export', ProductExportController::class)
      ->name('export');

Advantages

✅ Clear separation of concerns
✅ Easy to remove when deprecation period ends
✅ No conditional logic in main controller
✅ Self-documenting code

Solution 2: Method-Aware Middleware

If you prefer middleware, create one that checks the HTTP method before adding headers.

Step 1: Create the Middleware

  php artisan make:middleware DeprecateGetMethod

  // app/Http/Middleware/DeprecateGetMethod.php
  <?php

  namespace App\Http\Middleware;

  use Closure;
  use Illuminate\Http\Request;

  class DeprecateGetMethod
  {
      public function handle(Request $request, Closure $next, ?string $sunset = null, ?string $message = null)
      {
          $response = $next($request);

          if ($request->isMethod('GET')) {
              $response->headers->set('Deprecation', 'true');
              $response->headers->set('Sunset', $sunset ?? now()->addMonths(6)->toRfc7231String());

              if ($message) {
                  $response->headers->set('X-API-Warn', $message);
              }
          }

          return $response;
      }
  }

Step 2: Register the Middleware

  // bootstrap/app.php or app/Http/Kernel.php
  protected $middlewareAliases = [
      // ... other middleware
      'deprecate.get' => \App\Http\Middleware\DeprecateGetMethod::class,
  ];

Step 3: Apply to Route

  Route::get('/products/{id}/export', ProductExportController::class)
      ->name('exportLegacy')
      ->middleware('deprecate.get:2026-06-01,Use POST method instead');

  Route::post('/products/{id}/export', ProductExportController::class)
      ->name('export');

Advantages

✅ Reusable across multiple routes
✅ Parameterized sunset date and message
✅ Clean route definitions

Solution 3: Generic Deprecation Middleware

For maximum flexibility, create a middleware that works with any HTTP method.

// app/Http/Middleware/DeprecateEndpoint.php
  <?php

  namespace App\Http\Middleware;

  use Closure;
  use Illuminate\Http\Request;

  class DeprecateEndpoint
  {
      public function handle(Request $request, Closure $next, ?string $methods = null, ?string $sunset = null, ?string $replacement = null)
      {
          $response = $next($request);

          // If no methods specified, deprecate all
          // If methods specified, only deprecate those methods
          $deprecatedMethods = $methods ? explode(',', strtoupper($methods)) : ['*'];

          if ($deprecatedMethods === ['*'] || in_array($request->method(), $deprecatedMethods)) {
              $response->headers->set('Deprecation', 'true');
              $response->headers->set('Sunset', $sunset ?? now()->addMonths(6)->toRfc7231String());

              if ($replacement) {
                  $response->headers->set('Link', "<{$replacement}>; rel=\"alternate\"");
              }
          }

          return $response;
      }
  }

Usage:

  // Deprecate only GET and DELETE methods
  Route::match(['get', 'delete'], '/products/{id}/export', ProductExportController::class)
      ->middleware('deprecated:GET|DELETE,2026-06-01,/api/v2/products/{id}/export');

Understanding Deprecation Headers

Let's break down the HTTP headers we're using:

Deprecation: true

Standard: https://datatracker.ietf.org/doc/draft-ietf-httpapi-deprecation-header/09/
Purpose: Indicates the endpoint is deprecated
Client Action: Log warnings, alert developers

Sunset:

Standard: https://datatracker.ietf.org/doc/html/rfc8594
Format: RFC 7231 date (e.g., Sat, 01 Jun 2026 00:00:00 GMT)
Purpose: When the endpoint will be removed
Client Action: Plan migration before this date

X-API-Warn:

Standard: Custom (common practice)
Purpose: Human-readable deprecation message
Client Action: Display to developers

Link: ; rel="alternate"

Standard: https://datatracker.ietf.org/doc/html/rfc8288
Purpose: Points to replacement endpoint
Client Action: Use this URL instead

Best Practices

1. Document Everywhere

 /**
   * @deprecated This GET endpoint is obsolete as of v2.5.0
   * Will be removed in v3.0.0 (June 2026)
   * Use POST /products/{id}/export instead
   */
  Route::get('/products/{id}/export', ProductExportLegacyController::class)
      ->name('exportLegacy');

2. Log Deprecated Usage

Track who's still using deprecated endpoints:

  public function __invoke(Request $request, $id)
  {
      Log::warning('Deprecated GET /products/export endpoint used', [
          'product_id' => $id,
          'client_ip' => $request->ip(),
          'user_agent' => $request->userAgent(),
      ]);

      // ... rest of controller
  }

3. Communicate the Change

Update API documentation
Send email notifications to API consumers
Add changelog entries
Update OpenAPI/Swagger specs

4. Set Realistic Sunset Dates

Give clients enough time to migrate:

Minor changes: 3-6 months
Major changes: 6-12 months
Breaking changes: 12+ months

5. Version Your API

Consider versioned routes for major changes:

  // Old version (deprecated)
  Route::prefix('v1')->group(function () {
      Route::get('/products/{id}/export', ProductExportLegacyController::class);
  });

  // New version
  Route::prefix('v2')->group(function () {
      Route::post('/products/{id}/export', ProductExportController::class);
  });

Monitoring Deprecated Endpoints

Create a simple monitoring system:

// app/Http/Middleware/TrackDeprecatedUsage.php
  public function handle(Request $request, Closure $next)
  {
      $response = $next($request);

      if ($response->headers->has('Deprecation')) {
          event(new DeprecatedEndpointAccessed(
              endpoint: $request->path(),
              method: $request->method(),
              user: $request->user(),
              ip: $request->ip(),
          ));
      }

      return $response;
  }

Then create a dashboard or report:

 // Track usage over time
  DB::table('deprecated_endpoint_usage')
      ->select('endpoint', DB::raw('count(*) as hits'))
      ->where('accessed_at', '>', now()->subDays(30))
      ->groupBy('endpoint')
      ->get();

The Removal Process

When the sunset date arrives:

1. Final Warning Period (1-2 weeks before)

  public function __invoke(Request $request, $id)
  {
      Log::critical('FINAL WARNING: Deprecated endpoint will be removed in 2 weeks', [
          'endpoint' => $request->path(),
          'removal_date' => '2026-06-01',
      ]);

      // ... rest of controller
  }

2. Graceful Removal

  // Return 410 Gone instead of 404 Not Found
  Route::get('/products/{id}/export', function () {
      return response()->json([
          'message' => 'This endpoint was removed on June 1, 2026',
          'replacement' => 'POST /products/{id}/export',
          'documentation' => 'https://docs.example.com/api/v2/products',
      ], 410);
  })->name('exportRemoved');

3. Complete Removal

After a grace period (e.g., 3-6 months), remove the route entirely.

Conclusion

Deprecating specific HTTP methods on shared endpoints requires thoughtful implementation. The separate controller approach offers the best balance of clarity and maintainability, while middleware solutions provide reusability across your API.

Remember:
✅ Use standard HTTP headers
✅ Provide clear migration paths
✅ Give adequate notice
✅ Monitor usage
✅ Document everything

Your API consumers will thank you for the smooth transition!

Supercharge Your AI Coding Workflow: A Complete Guide to Git Worktrees with Claude Code

Bilal Haidar — Thu, 08 Jan 2026 11:59:09 +0000

In the age of AI assisted development, our workflows are evolving rapidly. Tools like Claude Code are transforming how we write, refactor, and debug code. But with this power comes a new challenge: how do we safely let an AI agent make substantial changes to our codebase while maintaining control and continuing our own work? Enter Git worktrees, a powerful yet underutilized feature that pairs exceptionally well with AI coding assistants.

This guide will take you from worktree basics to advanced workflows specifically designed for AI assisted development. Whether you're a seasoned developer or just starting to integrate AI into your workflow, you'll find practical strategies to boost your productivity while maintaining code quality.

What Are Git Worktrees?

Git worktrees allow you to have multiple working directories attached to the same repository simultaneously. Think of them as parallel universes for your codebase, each checked out to a different branch, but all sharing the same Git history and object database.

Unlike cloning a repository multiple times (which duplicates everything), worktrees are lightweight. They share the .git directory with your main working copy, meaning:

No duplicate repository data eating up disk space
All worktrees stay synchronized with the same remote
Commits made in any worktree are immediately visible to all others
Branch operations in one worktree affect the shared repository

The Traditional Problem

Before worktrees, if you needed to work on multiple branches simultaneously, you had limited options:

Stash and switch: Constantly stashing your work, switching branches, then unstashing. This is error prone and disruptive.
Multiple clones: Cloning the repository multiple times. This wastes disk space and creates synchronization headaches.
Just deal with it: Finishing one task completely before starting another. This kills productivity when you're blocked or need to context switch.

The Worktree Solution

Worktrees eliminate these compromises. You can have your main branch checked out in one directory, your feature/authentication branch in another, and a bugfix/login-error branch in a third, all simultaneously accessible and all sharing the same repository.

my-project/                    # Main worktree (main branch)
my-project-feature-auth/       # Worktree for authentication feature
my-project-bugfix-login/       # Worktree for login bugfix

Each directory is a fully functional working copy. You can open them in separate IDE windows, run different dev servers, and switch between them instantly by simply changing directories.

Git Worktree Commands: The Complete Reference

Before diving into AI specific workflows, let's master the worktree commands you'll use daily.

Creating Worktrees

Create a worktree for an existing branch:

git worktree add ../my-project-feature ../path/to/worktree branch-name

Create a worktree with a new branch:

git worktree add -b new-branch-name ../path/to/worktree

Create a worktree based on a specific commit or tag:

git worktree add ../path/to/worktree commit-hash
git worktree add ../path/to/worktree v1.2.3

Create a detached HEAD worktree (useful for exploration):

git worktree add --detach ../path/to/worktree HEAD

Listing Worktrees

View all worktrees:

git worktree list

This outputs something like:

/home/user/projects/my-app           abc1234 [main]
/home/user/projects/my-app-feature   def5678 [feature/new-ui]
/home/user/projects/my-app-bugfix    ghi9012 [bugfix/login]

Get detailed information:

git worktree list --porcelain

Removing Worktrees

Remove a worktree (the safe way):

git worktree remove ../path/to/worktree

Force remove (if there are uncommitted changes):

git worktree remove --force ../path/to/worktree

Clean up stale worktree references:

If you manually delete a worktree directory, Git still tracks it. Clean up with:

git worktree prune

Moving and Repairing Worktrees

Move a worktree to a new location:

git worktree move ../old/path ../new/path

Repair worktree references after moving the main repository:

git worktree repair

Locking Worktrees

Prevent a worktree from being pruned (useful for worktrees on removable drives):

git worktree lock ../path/to/worktree
git worktree lock --reason "On external backup drive" ../path/to/worktree
git worktree unlock ../path/to/worktree

Why Worktrees Are Perfect for AI Assisted Development

Now let's explore why worktrees and AI coding assistants are a match made in developer heaven.

The AI Agent Challenge

When you're using an AI coding tool like Claude Code, you're essentially giving an intelligent agent access to modify your files. This creates unique challenges:

Concurrent work: While the AI is refactoring your authentication module, you might want to continue working on the UI. Without worktrees, you're blocked.
Experimentation safety: AI suggestions might be brilliant or they might break everything. You need a safe space to evaluate them.
Context preservation: If the AI's changes don't work out, reverting shouldn't disrupt your other work.
Multiple AI tasks: You might want to run multiple AI assisted tasks in parallel, each exploring different approaches.

The Worktree Advantage

Worktrees solve all these problems elegantly:

Isolation: AI changes happen in a separate directory. Your main work is untouched.
Parallelism: Run multiple AI tasks simultaneously in different worktrees.
Easy comparison: Diff between worktrees to evaluate AI suggestions against your original code.
Zero risk experimentation: Delete a worktree and its branch if the AI's approach doesn't pan out.
Continuous productivity: Keep working in your main worktree while AI processes in another.

Setting Up a Worktree Based AI Workflow

Let's build a practical workflow from the ground up.

Project Structure

I recommend organizing your worktrees in a consistent pattern. Here's a structure that works well:

~/projects/
├── my-app/                      # Main worktree (main/develop branch)
├── my-app-ai-refactor/          # AI working on refactoring task
├── my-app-ai-feature/           # AI implementing new feature
└── my-app-ai-experiment/        # AI exploring experimental approach

Why Use Helper Scripts?

While you can create and remove worktrees manually with Git commands, helper scripts provide several important benefits when working with AI assistants:

Consistency: When you're creating multiple worktrees throughout the day for different AI tasks, it's easy to make typos or forget your naming convention. Scripts enforce a consistent pattern every time.

Reduced cognitive load: Instead of remembering the exact syntax for worktree commands, branch naming patterns, and directory paths, you just run one command with a task name.

Error prevention: The scripts include validation to prevent common mistakes like forgetting to specify a task name or accidentally deleting the wrong worktree.

Onboarding: If you work on a team, scripts make it easy for everyone to follow the same workflow without memorizing commands.

Documentation: The scripts themselves serve as documentation for your workflow. New team members can read them to understand the process.

Where to Save Your Scripts

You have several options for where to store these scripts:

Option 1: In your project repository (recommended for team workflows)

my-project/
├── scripts/
│   ├── create-ai-worktree.sh
│   └── cleanup-ai-worktree.sh
├── src/
└── ...

Option 2: In your home directory (recommended for personal use across projects)

~/bin/
├── create-ai-worktree.sh
└── cleanup-ai-worktree.sh

If using ~/bin/, make sure it's in your PATH by adding this to your .bashrc or .zshrc:

export PATH="$HOME/bin:$PATH"

Option 3: As Git aliases (covered later in the Advanced section)

The Creation Script

This script automates the creation of a new worktree specifically for AI assisted tasks:

#!/bin/bash
# create-ai-worktree.sh
#
# Purpose: Creates a new Git worktree with a standardized naming convention
#          for AI assisted development tasks.
#
# Usage: ./create-ai-worktree.sh <task-name>
# Example: ./create-ai-worktree.sh refactor-auth

# Get the project name from the Git repository root directory name
PROJECT_NAME=$(basename $(git rev-parse --show-toplevel))

# Get the task name from the first argument
TASK_NAME=$1

# Build standardized names for the branch and worktree directory
BRANCH_NAME="ai/${TASK_NAME}"
WORKTREE_PATH="../${PROJECT_NAME}-ai-${TASK_NAME}"

# Validate that a task name was provided
if [ -z "$TASK_NAME" ]; then
    echo "Usage: create-ai-worktree.sh <task-name>"
    echo ""
    echo "Examples:"
    echo "  create-ai-worktree.sh payment-integration"
    echo "  create-ai-worktree.sh refactor-auth"
    echo "  create-ai-worktree.sh bug-fix-login"
    exit 1
fi

# Check if the branch already exists
if git show-ref --verify --quiet "refs/heads/${BRANCH_NAME}"; then
    echo "Error: Branch '${BRANCH_NAME}' already exists."
    echo "Either delete it first or choose a different task name."
    exit 1
fi

# Create the new branch and worktree simultaneously
git worktree add -b "$BRANCH_NAME" "$WORKTREE_PATH"

# Provide helpful output
echo ""
echo "=========================================="
echo "AI Worktree Created Successfully!"
echo "=========================================="
echo ""
echo "Worktree location: $WORKTREE_PATH"
echo "Branch name:       $BRANCH_NAME"
echo ""
echo "Next steps:"
echo "  1. cd $WORKTREE_PATH"
echo "  2. Install dependencies (composer install, npm install, etc.)"
echo "  3. Launch Claude Code: claude"
echo ""
echo "When finished:"
echo "  cleanup-ai-worktree.sh $TASK_NAME"

The Cleanup Script

This companion script safely removes a worktree and its associated branch when you're done:

#!/bin/bash
# cleanup-ai-worktree.sh
#
# Purpose: Safely removes an AI worktree and its associated branch.
#          Includes confirmation to prevent accidental deletion.
#
# Usage: ./cleanup-ai-worktree.sh <task-name>
# Example: ./cleanup-ai-worktree.sh refactor-auth

PROJECT_NAME=$(basename $(git rev-parse --show-toplevel))
TASK_NAME=$1
BRANCH_NAME="ai/${TASK_NAME}"
WORKTREE_PATH="../${PROJECT_NAME}-ai-${TASK_NAME}"

# Validate that a task name was provided
if [ -z "$TASK_NAME" ]; then
    echo "Usage: cleanup-ai-worktree.sh <task-name>"
    echo ""
    echo "Current AI worktrees:"
    git worktree list | grep "\-ai\-"
    exit 1
fi

# Check if the worktree exists
if [ ! -d "$WORKTREE_PATH" ]; then
    echo "Error: Worktree not found at $WORKTREE_PATH"
    echo ""
    echo "Current worktrees:"
    git worktree list
    exit 1
fi

# Show what will be deleted and ask for confirmation
echo "This will remove:"
echo "  Worktree: $WORKTREE_PATH"
echo "  Branch:   $BRANCH_NAME"
echo ""

# Check for uncommitted changes
cd "$WORKTREE_PATH"
if [ -n "$(git status --porcelain)" ]; then
    echo "WARNING: This worktree has uncommitted changes!"
    git status --short
    echo ""
fi
cd - > /dev/null

read -p "Are you sure you want to continue? (y/n) " -n 1 -r
echo ""

if [[ $REPLY =~ ^[Yy]$ ]]; then
    # Remove the worktree
    git worktree remove "$WORKTREE_PATH" --force

    # Remove the branch
    git branch -D "$BRANCH_NAME"

    echo ""
    echo "Successfully cleaned up: $TASK_NAME"
else
    echo "Cleanup cancelled."
fi

Installing and Using the Scripts

Follow these steps to set up the scripts on your system:

Step 1: Create the scripts

Create a bin directory in your home folder if it doesn't exist:

mkdir -p ~/bin

Create the creation script:

nano ~/bin/create-ai-worktree.sh
# Paste the script content, save and exit (Ctrl+X, Y, Enter)

Create the cleanup script:

nano ~/bin/cleanup-ai-worktree.sh
# Paste the script content, save and exit

Step 2: Make them executable

chmod +x ~/bin/create-ai-worktree.sh
chmod +x ~/bin/cleanup-ai-worktree.sh

Step 3: Add to your PATH (if not already done)

Add this line to your ~/.bashrc or ~/.zshrc:

export PATH="$HOME/bin:$PATH"

Then reload your shell configuration:

source ~/.bashrc  # or source ~/.zshrc

Step 4: Use them in any Git repository

# Navigate to any project
cd ~/projects/my-laravel-app

# Create an AI worktree for a payment feature
create-ai-worktree.sh payment-processing

# Output:
# ==========================================
# AI Worktree Created Successfully!
# ==========================================
#
# Worktree location: ../my-laravel-app-ai-payment-processing
# Branch name:       ai/payment-processing
# ...

# Navigate to the new worktree
cd ../my-laravel-app-ai-payment-processing

# Do your AI assisted work...

# When done, return to main project and clean up
cd ../my-laravel-app
cleanup-ai-worktree.sh payment-processing

Practical Example: Complete Workflow

Here's a real world example showing the scripts in action:

# You're working on your Laravel project
cd ~/projects/invoice-app
git status
# On branch main, everything clean

# You want Claude Code to implement a PDF export feature
create-ai-worktree.sh pdf-export

# Output shows the worktree was created at ../invoice-app-ai-pdf-export

# Move to the AI worktree
cd ../invoice-app-ai-pdf-export

# Install dependencies (worktrees don't share node_modules or vendor)
composer install
npm install

# Start Claude Code and give it the task
claude

# ... Claude Code implements the PDF export feature ...
# ... You review the changes, run tests, make adjustments ...

# Happy with the result? Commit and merge
git add .
git commit -m "feat: implement PDF export for invoices"

# Return to main project
cd ../invoice-app

# Merge the AI's work
git merge ai/pdf-export

# Clean up the worktree and branch
cleanup-ai-worktree.sh pdf-export

# Done! The PDF export feature is now in your main branch

This workflow keeps your main development environment clean, lets you experiment freely, and makes it trivial to discard failed experiments or merge successful ones.

Real World Workflow: AI Assisted Feature Development

Let's walk through a complete example of using worktrees with Claude Code to implement a new feature.

Scenario

You're building a Laravel application and need to implement a new payment processing feature. You want Claude Code to scaffold the initial implementation while you continue working on unrelated bug fixes.

Step 1: Create the AI Worktree

From your main project directory:

# Create a worktree for the AI to work in
git worktree add -b feature/payment-processing ../my-app-ai-payments

# Verify it was created
git worktree list

Step 2: Set Up the AI Environment

Navigate to the new worktree and ensure it's ready:

cd ../my-app-ai-payments

# Install dependencies (they're not shared between worktrees)
composer install
npm install

# Copy environment file if needed
cp .env.example .env
php artisan key:generate

Step 3: Launch Claude Code in the AI Worktree

Open Claude Code in the AI worktree directory:

claude

Now give Claude Code your task:

I need you to implement a payment processing system for this Laravel application. 

Requirements:
* Create a PaymentService class that integrates with Stripe
* Add a PaymentController with endpoints for creating and confirming payments
* Create the necessary migrations for storing payment records
* Add appropriate form requests for validation
* Write feature tests for the payment flow

Please implement this step by step, creating each component and explaining your decisions.

Step 4: Continue Your Own Work

While Claude Code works in the payment worktree, switch back to your main worktree:

cd ../my-app

Continue your bug fixes, completely unaffected by whatever Claude Code is doing in the other directory.

Step 5: Review AI Changes

Once Claude Code completes its task, review what it created:

# See what files were changed/created
cd ../my-app-ai-payments
git status

# Review the diff
git diff main

# Or compare specific files
diff ../my-app/app/Services/ ./app/Services/

Step 6: Test in Isolation

Run tests in the AI worktree to validate the implementation:

cd ../my-app-ai-payments
php artisan test --filter=Payment

Step 7: Merge or Iterate

If you're satisfied with the AI's work:

# Switch to main worktree
cd ../my-app

# Merge the AI's branch
git merge feature/payment-processing

# Clean up
git worktree remove ../my-app-ai-payments
git branch -d feature/payment-processing

If you need changes, either:

Return to the AI worktree and continue prompting Claude Code
Make manual adjustments in the AI worktree before merging
Discard and start fresh with a new approach

Advanced Workflow: Parallel AI Exploration

Sometimes you want the AI to explore multiple approaches simultaneously. Worktrees make this trivial.

The Multi Path Strategy

# Create three worktrees for different approaches
git worktree add -b ai/payments-stripe ../my-app-ai-stripe
git worktree add -b ai/payments-square ../my-app-ai-square
git worktree add -b ai/payments-braintree ../my-app-ai-braintree

Open Claude Code in each worktree with different prompts:

Stripe worktree: "Implement payment processing using Stripe's Payment Intents API..."

Square worktree: "Implement payment processing using Square's Web Payments SDK..."

Braintree worktree: "Implement payment processing using Braintree's Drop-in UI..."

Comparing Results

After all three implementations are complete:

# Compare code structure
diff -r ../my-app-ai-stripe/app/Services ../my-app-ai-square/app/Services

# Compare test coverage
cd ../my-app-ai-stripe && php artisan test --coverage
cd ../my-app-ai-square && php artisan test --coverage
cd ../my-app-ai-braintree && php artisan test --coverage

Selecting the Winner

Once you've evaluated all approaches:

# Merge your preferred implementation
cd ../my-app
git merge ai/payments-stripe

# Clean up all AI worktrees
git worktree remove ../my-app-ai-stripe
git worktree remove ../my-app-ai-square
git worktree remove ../my-app-ai-braintree

# Remove branches
git branch -D ai/payments-stripe ai/payments-square ai/payments-braintree

Best Practices for AI Worktree Workflows

Naming Conventions

Establish clear naming patterns:

Worktree directories: {project}-ai-{task} or {project}-{branch-type}-{description}
Branch names: ai/{task-name} or ai/{date}/{task-name}

This makes it easy to identify AI related work and clean up when done.

Commit Hygiene in AI Worktrees

Instruct your AI to commit frequently with meaningful messages:

As you implement this feature, please commit your changes at logical 
checkpoints with clear commit messages that explain what was done and why. 
Use conventional commit format (feat:, fix:, refactor:, etc.).

This gives you granular control when reviewing and the ability to cherry pick specific changes.

Regular Cleanup

AI experimentation can leave orphaned worktrees. Schedule regular cleanup:

# List all worktrees
git worktree list

# Prune any that were manually deleted
git worktree prune

# Remove stale AI branches
git branch --list 'ai/*' | xargs -n 1 git branch -d

Environment Variables and Secrets

Never let AI worktrees contain real credentials:

Use .env.example files with placeholder values
Create a specific .env.ai template for AI worktrees
Add AI worktree patterns to .gitignore if they might contain sensitive data

# .gitignore
.env
.env.ai
**/my-app-ai-*/.env

IDE Configuration

If you use VS Code, create a workspace file to manage multiple worktrees:

{
    "folders": [
        {
            "name": "Main Development",
            "path": "./my-app"
        },
        {
            "name": "AI: Payment Feature",
            "path": "./my-app-ai-payments"
        },
        {
            "name": "AI: Refactoring",
            "path": "./my-app-ai-refactor"
        }
    ],
    "settings": {
        "files.exclude": {
            "**/node_modules": true,
            "**/vendor": true
        }
    }
}

Troubleshooting Common Issues

"fatal: 'branch-name' is already checked out"

Git prevents the same branch from being checked out in multiple worktrees. Solutions:

# Create a new branch instead
git worktree add -b new-branch-name ../path

# Or detach HEAD in the blocking worktree first
cd ../blocking-worktree
git checkout --detach

Worktree Shows Outdated Code

If your AI worktree doesn't reflect recent commits from another worktree:

cd ../ai-worktree
git fetch origin
git rebase origin/main  # or merge, depending on your preference

Dependencies Not Working

Each worktree needs its own installed dependencies:

# Laravel
composer install
npm install

# SPFx
npm install

# ASP.NET Core
dotnet restore

Large Repository, Slow Worktree Creation

For very large repositories, worktree creation can be slow. Use sparse checkout:

git worktree add --no-checkout ../sparse-worktree branch-name
cd ../sparse-worktree
git sparse-checkout init --cone
git sparse-checkout set src/relevant-folder

Integrating with Your Development Workflow

Git Aliases for Common Operations

Add these to your .gitconfig:

[alias]
    # List worktrees with better formatting
    wt = worktree list

    # Create AI worktree quickly
    wt-ai = "!f() { git worktree add -b ai/$1 ../$(basename $(pwd))-ai-$1; }; f"

    # Remove AI worktree and branch
    wt-ai-rm = "!f() { git worktree remove ../$(basename $(pwd))-ai-$1 && git branch -D ai/$1; }; f"

    # Prune and clean
    wt-clean = "!git worktree prune && git branch --list 'ai/*' --merged | xargs -r git branch -d"

Usage:

git wt-ai payments      # Creates worktree and ai/payments branch
git wt-ai-rm payments   # Removes both
git wt-clean            # Prune stale worktrees and merged AI branches

Shell Functions for Complex Workflows

Add to your .bashrc or .zshrc:

# Start an AI assisted task
ai_task() {
    local task_name=$1
    local project_name=$(basename $(git rev-parse --show-toplevel))
    local worktree_path="../${project_name}-ai-${task_name}"

    git worktree add -b "ai/${task_name}" "$worktree_path"
    cd "$worktree_path"

    # Auto detect and install dependencies
    [ -f "composer.json" ] && composer install
    [ -f "package.json" ] && npm install
    [ -f "*.csproj" ] && dotnet restore

    echo "Ready! Opening Claude Code..."
    claude
}

# Quick cleanup
ai_cleanup() {
    local task_name=$1
    local project_name=$(basename $(git rev-parse --show-toplevel 2>/dev/null || echo $(basename $(pwd)) | sed 's/-ai-.*//'))
    local worktree_path="../${project_name}-ai-${task_name}"

    git worktree remove "$worktree_path" 2>/dev/null
    git branch -D "ai/${task_name}" 2>/dev/null
    echo "Cleaned up ai/${task_name}"
}

Conclusion

Git worktrees transform how we can work with AI coding assistants. By providing isolated, parallel working environments, they enable us to:

Let AI agents work autonomously without blocking our own progress
Experiment with multiple AI generated solutions simultaneously
Maintain clean separation between human and AI contributions
Safely evaluate and iterate on AI suggestions before merging

The investment in learning worktrees pays dividends every time you use an AI coding tool. The commands become second nature quickly, and the workflow improvements are substantial.

As AI assisted development continues to evolve, workflows like these will become increasingly important. The developers who master the tooling around AI integration will be the ones who extract the most value from these powerful assistants.

Start small: next time you have a task suitable for Claude Code, create a dedicated worktree. Experience the freedom of parallel development firsthand. Once you do, you'll wonder how you ever worked without it.

Have questions or want to share your own AI plus worktree workflows? Drop a comment below or reach out on social media. Happy coding!

Running Laravel Sail with Podman on macOS: A Step-by-Step Guide

Bilal Haidar — Mon, 22 Dec 2025 10:51:02 +0000

Laravel Sail is an excellent Docker-based development environment, but macOS users may want to switch from Docker to Podman, especially if using rootless Podman for security. In this guide, I’ll show you how to run Sail with Podman, step by step, and highlight common pitfalls with solutions.

Step 1: Install Podman and Set Up a Machine

Install Podman via Homebrew:

brew install podman

Create and start a Podman machine (a lightweight Linux VM):

podman machine init
podman machine start

Check the connection:

podman info

Issue: Initially, Podman may fail to connect, showing Cannot connect to Podman. Please verify your connection.
Solution: Use the correct identity key to SSH into the Podman machine. Test with:
ssh -i ~/.local/share/containers/podman/machine/machine -p <port> core@127.0.0.1

Step 2: Check Podman Socket and Connections

List Podman system connections:

podman system connection list

Ensure the default machine is set correctly. The socket path will be something like:

ssh://core@127.0.0.1:51011/run/user/501/podman/podman.sock

Issue: Docker commands may fail with Host key verification failed or Permission denied.
Solution: Add the Podman machine key to your SSH known_hosts or use the -i identity option.

Tip: To avoid specifying the SSH connection every time, you can export the environment variables permanently in your shell configuration (~/.zshrc or ~/.bashrc):
export DOCKER_HOST=ssh://core@127.0.0.1:51011
export DOCKER_SSH_KEY=/Users/{Replace with your User Account}/.local/share/containers/podman/machine/machine
This allows Sail and Docker CLI commands to automatically use your Podman machine.

Step 3: Configure Laravel Sail for Podman

Sail uses docker-compose under the hood. Create a .env file in your Laravel project:

APP_PORT=8080
VITE_PORT=5173
FORWARD_DB_PORT=4006
FORWARD_MAILHOG_PORT=2008
FORWARD_MAILHOG_DASHBOARD_PORT=2009
FORWARD_MEILISEARCH_PORT=6008
FORWARD_REDIS_PORT=6009

Issue: Rootless Podman cannot bind ports below 1024.
Solution: Make sure all ports in .env are ≥1024 (e.g., VITE_PORT=5173, APP_PORT=8080).

Step 4: Override the Docker Compose File

Create docker-compose.override.yml in your project root:

version: '3'
services:
  laravel.test:
    ports:
      - '${APP_PORT:-8080}:80'
      - '${VITE_PORT:-5173}:${VITE_PORT:-5173}'

This ensures Sail reads the correct ports from .env.

Step 5: Bring Down Old Containers

Before starting Sail with Podman, remove any existing containers:

./vendor/bin/sail down -v

Issue: Cached containers may still try to bind old ports (like 1007).
Solution: The -v flag removes volumes and forces Sail to reload the updated .env and override files.

Step 6: Start Sail

Start Sail as usual:

./vendor/bin/sail up -d

Verify the ports:

docker-compose ps

You should see something like:

0.0.0.0:8080->80/tcp
0.0.0.0:5173->5173/tcp

Now your Laravel app and Vite dev server run on safe, unprivileged ports with rootless Podman.

Step 7: Common Issues and Fixes

Issue	Error	Solution
Cannot connect to Podman	`Cannot connect to Podman socket`	Ensure machine is started and SSH connection works with `-i` identity key
Host key verification	`Host key verification failed`	Add Podman machine key to `~/.ssh/known_hosts` or use `ssh -i ...`
Rootless port binding	`rootlessport cannot expose privileged port 1007`	Make sure all ports ≥1024 in `.env` (`APP_PORT`, `VITE_PORT`)
Cached containers	Containers still try old ports	Run `./vendor/bin/sail down -v` to remove old containers and volumes

Step 8: Success!

Your Laravel Sail setup now runs completely on Podman, without needing Docker Desktop, using rootless ports, and with all services (MySQL, Redis, Meilisearch, Mailhog, Vite) running correctly.

This workflow ensures Podman compatibility on macOS, addresses common pitfalls with rootless port restrictions, and guarantees Laravel Sail runs smoothly in a Docker-free environment.

🧩 Mastering the Manager Pattern in Laravel — Build Pluggable, Scalable Architectures

Bilal Haidar — Mon, 27 Oct 2025 11:29:18 +0000

One of the most powerful, yet least discussed, features in Laravel’s design is its Manager pattern.

It’s what gives Laravel its flexibility to easily switch between different drivers like Redis, File, S3, Mailgun, or Database queues — all through configuration.

Let’s break down how it works, why it’s elegant, and how you can use it in your own applications.

🧠 What’s a Manager?
A Manager is a class that knows how to build and manage multiple “drivers”, each implementing a common interface but doing things differently.

Example from Laravel’s core:
CacheManager handles file, redis, database
MailManager handles smtp, mailgun, sendmail
QueueManager handles sync, database, redis

All of these extend Illuminate\Support\Manager, which gives them methods like:

$manager->driver('redis');
$manager->driver('file');

The framework caches drivers, manages dependencies, and lets you easily switch by changing .env — no code changes needed.

🧩 Real Example — PaymentManager
Imagine your app supports multiple payment gateways — Stripe, PayPal, and AppSumo.

Instead of cluttering your code with conditionals, create a clean PaymentManager to handle them.

Step 1: Create your PaymentManager

namespace App\Managers;


use Illuminate\Support\Manager;

class PaymentManager extends Manager
{
    protected function createStripeDriver()
    {
        return new \App\Services\Payments\StripeService();
    }

    protected function createPaypalDriver()
    {
        return new \App\Services\Payments\PaypalService();
    }

    protected function createAppsumoDriver()
    {
        return new \App\Services\Payments\AppsumoService();
    }

    public function getDefaultDriver()
    {
        return config('app.payment_driver', 'stripe');
    }
}

Each createXDriver() method builds a specific driver.
Laravel will call the correct one automatically based on the name you pass to driver().

Step 2: Example Drivers

namespace App\Services\Payments;

interface PaymentContract
{
    public function charge($user, $amount);
}

class StripeService implements PaymentContract
{
    public function charge($user, $amount)
    {
        // Stripe API logic
    }
}

class PaypalService implements PaymentContract
{
    public function charge($user, $amount)
    {
        // PayPal API logic
    }
}

Each driver follows the same interface (PaymentContract).

Step 3: Using the Manager

$paymentManager = app(App\Managers\PaymentManager::class);
$payment = $paymentManager->driver(config('app.payment_driver'));
$payment->charge($user, 100);

Now, you can easily switch between payment providers by editing your .env:

PAYMENT_DRIVER=paypal

No code changes required. Your architecture remains clean, scalable, and maintainable.

⚙️ Why This Pattern Rocks
✅ Config-driven: No conditionals, just configuration
✅ Extensible: Add new drivers anytime
✅ Testable: Mock a driver in your tests easily
✅ Proven: It's used across Laravel’s core services

🧩 Bonus — When to Use a Manager
Use this pattern when you have:

Multiple implementations of the same interface (e.g., notifications, analytics, storage)
Dynamic runtime switching (e.g., per-tenant configuration)
Need for test isolation and maintainable abstractions

🧠 Final Thoughts
The Manager pattern is part of what makes Laravel both beautiful and enterprise-ready.

Once you understand it, you can architect systems that are modular, testable, and scalable, just like Laravel itself.

💥 Supercharge your Laravel API calls with Http::pool()

Bilal Haidar — Tue, 21 Oct 2025 06:24:54 +0000

Did you know you can send multiple HTTP requests in parallel in Laravel, instead of one after another?

That’s what Http::pool() does. It’s built on top of Guzzle and can massively boost performance when fetching data from several APIs at once.

🧠 The idea

Normally, you might do this:

$response1 = Http::get('https://api.example.com/users');
$response2 = Http::get('https://api.example.com/posts');
$response3 = Http::get('https://api.example.com/comments');

Each waits for the previous one.
If each takes 1 second → total ≈ 3 seconds.

With Http::pool(), Laravel runs them all at once — so the total time ≈ the longest single request (around 1 second here).

🧩 Example

use Illuminate\Support\Facades\Http;

$responses = Http::pool(fn ($pool) => [
    $pool->as('users')->get('https://api.example.com/users'),
    $pool->as('posts')->get('https://api.example.com/posts'),
    $pool->as('comments')->get('https://api.example.com/comments'),
]);

$users = $responses['users'];
$posts = $responses['posts'];
$comments = $responses['comments'];

$usersData = $users->json();

⚙️ How it works

The pool() method accepts a closure.
Inside, you define multiple requests.
Laravel runs them concurrently using Guzzle promises.
Returns an array of responses (each is a standard Response instance).

🧩 Dynamic example

$urls = [
    'https://api.example.com/products/1',
    'https://api.example.com/products/2',
    'https://api.example.com/products/3',
];

$responses = Http::pool(fn ($pool) =>
    collect($urls)->map(fn($url) => $pool->get($url))->all()
);

foreach ($responses as $response) {
    dump($response->json());
}

🛠 When to use it

✅ Fetch data from multiple APIs simultaneously
✅ Speed up microservice calls
✅ Reduce latency in dashboards or data aggregators

📚 Laravel Docs

💬 Have you used Http::pool()before?
Share your favorite use case or performance boost story 👇

Laravel #WebDevelopment #FullStackDev #Performance #PHP #LaravelTips

Essential Composer CLI Commands Cheat Sheet

Bilal Haidar — Fri, 03 Oct 2025 19:37:45 +0000

Composer is the dependency manager for PHP that helps you manage packages and libraries in your projects.

Below is a handy list of commonly used Composer CLI commands with one-line explanations to keep as a quick reference.

Installation and Updates

composer self-update → Updates Composer itself to the latest version.
composer diagnose → Checks your system for common issues with Composer setup.

Project Setup

composer init → Starts an interactive session to create a composer.json file.
composer create-project vendor/package [dir] → Creates a new project from a package (e.g., Laravel, Symfony).

Dependencies Management

composer install → Installs dependencies listed in composer.lock (or composer.json if no lock file exists).
composer update → Updates all dependencies to the latest versions according to composer.json.
composer require vendor/package → Installs and adds a package to your project.
composer remove vendor/package → Removes a package and updates composer.json.

Autoloading

composer dump-autoload → Regenerates the autoloader for faster class loading.
composer dump-autoload -o → Optimizes autoloader by converting PSR-0/4 autoloading rules into a class map.

Information & Debugging

composer show → Lists all installed packages in the current project.
composer show vendor/package → Shows detailed information about a specific package.
composer outdated → Displays packages that have updates available.
composer why vendor/package → Shows which package requires a given dependency.
composer why-not vendor/package → Explains why a package cannot be installed or updated.

Scripts & Custom Commands

composer run-script script-name → Runs a script defined in composer.json.
composer test → Shortcut to run the test script defined in your composer.json.
Global Usage
composer global require vendor/package → Installs a package globally (available system-wide).
composer global show → Lists globally installed Composer packages.

Cache & Config

composer clear-cache → Clears Composer’s cache.
composer config key value → Sets a configuration option (local or global).
composer config --list → Shows all current Composer configuration settings.

Version Control

composer install --no-dev → Installs only production dependencies.
composer install --dev → Installs development dependencies.
composer update --lock → Updates only the composer.lock file without changing dependencies.

Handy Flags

--no-scripts → Skips running scripts defined in composer.json.
--no-progress → Hides progress display for CI/CD pipelines.
--dry-run → Simulates a command without executing it.

Learn how to deploy a Nuxt3 App with SSR on Laravel Forge

Bilal Haidar — Mon, 31 Mar 2025 18:55:21 +0000

Bilal Haidar

Mar 31 '25

Deploying a Nuxt 3 App with SSR on Laravel Forge

#nextjs #laravelforge #ssr

Comments

3 min read

Deploying a Nuxt 3 App with SSR on Laravel Forge

Bilal Haidar — Mon, 31 Mar 2025 18:51:42 +0000

Deploying a Nuxt 3 application with Server-Side Rendering (SSR) on Laravel Forge requires specific configurations to ensure that Nuxt is properly served. This guide provides a step-by-step walkthrough to deploy your Nuxt 3 SSR app on Forge, configure Nginx, and manage Nuxt processes using PM2.

Step 1: Prepare Your Nuxt 3 App for Deployment

Before deploying, ensure your Nuxt app is properly configured for SSR. Update your nuxt.config.js file:

export default defineNuxtConfig({
  ssr: true, // Enable Server-Side Rendering
  nitro: {
    prerender: {
      crawlLinks: false, // Prevent Nitro from crawling and generating routes
      routes: [], // No pre-rendered routes
    },
  },
  // ... other config here
})

Why this matters?

When SSR is enabled, Nuxt does not serve static files from /dist.
Instead, the SSR application is served from .output/public/server.
This means all requests are handled dynamically by Nuxt.
We need PM2 to manage the Nuxt server, ensuring it runs continuously.

Step 2: Create a New Static App on Laravel Forge

Log in to your Laravel Forge account.
Create a new site and select Static App as the site type.
Add your domain (e.g., yourdomain.com).
Assign an SSL certificate (Let's Encrypt or manually).
Once SSL is active, edit the Nginx configuration file.

Editing Nginx Configuration on Forge

Rather than editing the Nginx config directly on the server, follow these steps:

Navigate to your site on Forge.
Locate the Edit Files dropdown on the top-right side of the page.
Select Edit Nginx Configuration.
Replace the existing configuration with the following, ensuring you replace:
- YOUR_DOMAIN_NAME with your actual domain.
- YOUR_DOMAIN_FOLDER with the correct site directory.
- Keep the SSL ID values assigned by Forge for your certificate.

Example:

# FORGE CONFIG (DO NOT REMOVE!)
include forge-conf/YOUR_DOMAIN_FOLDER/before/*;

map $sent_http_content_type $expires {
    "text/html"                 epoch;
    "text/html; charset=utf-8"  epoch;
    default                     off;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name YOUR_DOMAIN_NAME;

    # FORGE SSL (DO NOT REMOVE!)
    ssl_certificate /etc/nginx/ssl/YOUR_DOMAIN_NAME/YOUR_SSL_ID/server.crt;
    ssl_certificate_key /etc/nginx/ssl/YOUR_DOMAIN_NAME/YOUR_SSL_ID/server.key;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;
    ssl_dhparam /etc/nginx/dhparams.pem;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-XSS-Protection "1; mode=block";
    add_header X-Content-Type-Options "nosniff";

    charset utf-8;

    gzip            on;
    gzip_types      text/plain application/xml text/css application/javascript;
    gzip_min_length 1000;

    # FORGE CONFIG (DO NOT REMOVE!)
    include forge-conf/YOUR_DOMAIN_FOLDER/server/*;

    location / {
        expires $expires;

        proxy_set_header Host               $host;
        proxy_set_header X-Real-IP          $remote_addr;
        proxy_set_header X-Forwarded-For    $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto  $scheme;
        proxy_redirect              off;
        proxy_read_timeout          1m;
        proxy_connect_timeout       1m;
        proxy_pass                  http://127.0.0.1:3000; # Set the address of the Node.js server
    }

    access_log off;
    error_log  /var/log/nginx/YOUR_DOMAIN_NAME-error.log error;

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

# FORGE CONFIG (DO NOT REMOVE!)
include forge-conf/YOUR_DOMAIN_FOLDER/after/*;

After saving changes in Forge, restart Nginx by clicking Apply Changes.

Step 3: Set Up Deployment Script on Forge

Navigate to your site on Laravel Forge and go to the Deployment tab. Update the deployment script with the following:

#!/bin/bash
cd /home/forge/YOUR_DOMAIN_NAME

# Pull latest changes
git pull origin $FORGE_SITE_BRANCH

# Clean installation files
rm -rf node_modules
rm package-lock.json

# Install dependencies with platform-specific flags
export ROLLUP_SKIP_NODE_CHECK=true
npm install --platform=linux --arch=x64

# Build for SSR
npm run build

# Restart Nuxt using PM2
pm2 delete nuxt-app || true  # Ensure old process is removed
pm2 start .output/server/index.mjs --name "nuxt-app"

# Save PM2 process so it persists after a reboot
pm2 save

# Restart PHP-FPM (if needed for other Laravel services)
( flock -w 10 9 || exit 1
    echo 'Restarting FPM...'; sudo -S service $FORGE_PHP_FPM reload ) 9>/tmp/fpmlock

Click Save and then Deploy Now to start the process.

Step 4: Finalizing Your Deployment

Ensure that your Web Directory in Laravel Forge is set to:

/public

Manually restart all services to ensure everything is working:

sudo service nginx restart
pm2 restart nuxt-app

Open your domain in the browser (https://yourdomain.com) and check that the app is loading correctly.
Monitor logs if there are any issues:

tail -f /var/log/nginx/YOUR_DOMAIN_NAME-error.log
pm2 logs nuxt-app

Conclusion

By following these steps, you have successfully deployed a Nuxt 3 SSR application on Laravel Forge. This setup ensures:

Nuxt 3 runs in server-side rendering mode.
Nginx properly proxies requests to the Nuxt SSR server.
PM2 keeps the Nuxt process running reliably.

This guide should serve as a complete reference for anyone deploying Nuxt 3 SSR on Laravel Forge. 🚀

Implementing Infinite Scrolling with Laravel, Inertia.js v2.0, and Vue 3

Bilal Haidar — Wed, 11 Dec 2024 12:21:48 +0000

In this comprehensive guide, we'll explore how to implement infinite scrolling in a Laravel application using Inertia.js v2.0 and Vue 3. We'll cover both the frontend and backend implementation, with special attention to handling full page refreshes and maintaining scroll position.

Understanding the Components
Frontend Implementation
Backend Implementation
Real-World Example: Blog Posts with Categories
Best Practices and Considerations

Understanding the Components

The infinite scrolling implementation relies on three main components:

Inertia.js v2.0's WhenVisible Component: This component handles the intersection observer logic to detect when we need to load more content.
Laravel's Pagination: Handles the server-side pagination logic.
Vue 3's Composition API: Manages our frontend state and reactivity.

Frontend Implementation

Let's start with a Vue component that implements infinite scrolling for a blog posts listing:

<script setup>
import { computed } from 'vue'
import { usePage, WhenVisible } from '@inertiajs/vue3'
import LoadingSpinner from '@/components/LoadingSpinner.vue'
import BlogPostCard from '@/components/BlogPostCard.vue'

const page = usePage()

const hasFeaturePost = computed(() => !!page.props.featuredPost)
const categoryName = computed(() => page.props.category?.name)
</script>

<template>
    <div class="bg-gray-50">
        <!-- Featured Post Section -->
        <div
            v-if="hasFeaturePost"
            class="container"
        >
            <div class="py-8 text-center">
                <h2 class="mb-4 text-3xl font-bold">
                    Featured Post: {{ page.props.featuredPost.title }}
                </h2>
            </div>
        </div>

        <!-- Posts Grid -->
        <div class="max-w-7xl px-4 py-8 mx-auto sm:px-6 lg:px-8">
            <h1 class="text-2xl font-bold mb-6">
                {{ categoryName ? `Posts in ${categoryName}` : 'All Posts' }}
            </h1>

            <div class="grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3">
                <div
                    v-for="post in page.props.posts"
                    :key="post.id"
                    class="relative flex flex-col"
                >
                    <blog-post-card :post="post" />
                </div>

                <!-- Infinite Scroll Handler -->
                <WhenVisible
                    :always="page.props.postsPagination?.current_page < page.props.postsPagination?.last_page"
                    :params="{
                        data: {
                            page: page.props.postsPagination.current_page + 1,
                        },
                        only: ['posts', 'postsPagination'],
                    }"
                >
                    <div
                        v-if="page.props.postsPagination?.current_page >= page.props.postsPagination?.last_page"
                        class="text-center py-6 text-gray-600 col-span-1 md:col-span-2 lg:col-span-3"
                    >
                        You've reached the end!
                    </div>
                    <div
                        v-else
                        class="col-span-1 md:col-span-2 lg:col-span-3"
                    >
                        <loading-spinner />
                    </div>
                </WhenVisible>
            </div>
        </div>
    </div>
</template>

Key Frontend Features

WhenVisible Component: This component from Inertia.js v2.0 automatically triggers a request when the element becomes visible in the viewport.
Pagination Parameters:

:params="{
    data: {
        page: page.props.postsPagination.current_page + 1,
    },
    only: ['posts', 'postsPagination'],
}"

data: Specifies the next page to load
only: Optimizes the request by only fetching required data

Loading States: The component handles both loading and end-of-content states elegantly.

Backend Implementation

Here's the Laravel controller implementation that handles both regular pagination and full-page load scenarios:

<?php

namespace App\Http\Controllers;

use App\Models\Post;
use App\Models\Category;
use Illuminate\Pagination\LengthAwarePaginator;
use Inertia\Inertia;

class BlogController extends Controller
{
    public function index(?Category $category = null)
    {
        return Inertia::render('Blog/Index', [
            'category' => $category,
            'featuredPost' => $this->getFeaturedPost(),
            'posts' => $this->getPaginatedPosts($category),
            'postsPagination' => $this->getPaginatedPosts($category)?->toArray(),
        ]);
    }

    protected function getPaginatedPosts(?Category $category): ?LengthAwarePaginator
    {
        $currentPage = request()->input('page', 1);
        $perPage = request()->input('per_page', 12);

        $query = Post::query()
            ->with(['author', 'category'])
            ->published();

        if ($category) {
            $query->where('category_id', $category->id);
        }

        // Apply any additional filters
        if (request()->has('sort')) {
            $query->orderBy(request()->input('sort'), request()->input('direction', 'desc'));
        } else {
            $query->latest();
        }

        // Handle full page load vs. infinite scroll request
        if (!request()->header('X-Inertia')) {
            // Full page load - fetch all pages up to current
            $allResults = collect();

            for ($page = 1; $page <= $currentPage; $page++) {
                $pageResults = $query->paginate($perPage, ['*'], 'page', $page);
                $allResults = $allResults->concat($pageResults->items());
            }

            return new LengthAwarePaginator(
                $allResults,
                Post::query()
                    ->published()
                    ->when($category, fn($q) => $q->where('category_id', $category->id))
                    ->count(),
                $perPage,
                $currentPage
            );
        }

        return $query->paginate($perPage);
    }

    protected function getFeaturedPost()
    {
        return Post::query()
            ->with(['author', 'category'])
            ->published()
            ->featured()
            ->latest()
            ->first();
    }
}

Key Backend Features

Pagination Handling:

if (!request()->header('X-Inertia')) {
    // Full page load logic
} else {
    // Regular pagination for infinite scroll
}

Full Page Load: When a user refreshes or directly visits a page, we fetch all previous pages to maintain the correct scroll position:

for ($page = 1; $page <= $currentPage; $page++) {
    $pageResults = $query->paginate($perPage, ['*'], 'page', $page);
    $allResults = $allResults->concat($pageResults->items());
}

Efficient Querying: The implementation includes relationship eager loading and scoped queries:

$query = Post::query()
    ->with(['author', 'category'])
    ->published();

Conclusion

Implementing infinite scrolling with Laravel and Inertia.js v2.0 provides a smooth user experience while maintaining good performance and SEO practices. The combination of Vue 3's Composition API and Inertia.js's WhenVisible component makes it easy to implement and maintain.

Remember to:

Test the implementation thoroughly, especially for edge cases
Monitor performance metrics
Consider implementing a fallback for users with JavaScript disabled
Keep accessibility in mind when implementing infinite scroll

This implementation can be adapted for various use cases beyond blog posts, such as product listings, image galleries, or any other content that benefits from infinite scrolling.

Additional Resources

Understanding Laravel Cashier's Core Traits: A Deep Dive

Bilal Haidar — Thu, 28 Nov 2024 18:45:07 +0000

Laravel Cashier provides several powerful traits that handle Stripe integrations. Today, we'll explore three core traits and their public methods: ManagesSubscriptions, ManagesCustomer, and ManagesInvoices. Understanding these traits is crucial for implementing subscription-based billing in your Laravel applications.

ManagesSubscriptions Trait

Subscription Creation and Management

newSubscription($type, $prices = [])

Creates new subscription builder instance. Type defines the subscription name (e.g., 'default'), and prices can be single ID or array.

Trial Management

onTrial($type = 'default', $price = null)

No parameters: Checks ONLY generic (model-level) trial
With $type: Checks subscription-specific trial
With both: Checks if specific price is on trial
Returns boolean

hasExpiredTrial($type = 'default', $price = null)

No parameters: Checks generic trial expiration
With $type: Checks specific subscription trial expiration
With both: Verifies specific price trial expiration
Returns boolean

onGenericTrial()

Checks model-level trial status
Returns true if trial_ends_at exists and is future
No parameters needed

scopeOnGenericTrial($query)

Scope to filter customers on generic trial
Used in query builder
Requires query builder instance

hasExpiredGenericTrial()

Checks if model-level trial has expired
Returns true if trial_ends_at exists and is past
No parameters needed

scopeHasExpiredGenericTrial($query)

Scope to filter customers with expired generic trials
Used in query builder
Requires query builder instance

trialEndsAt($type = 'default')

No parameters: Returns generic trial end date if on generic trial
With $type: Returns subscription-specific trial end date
Returns Carbon instance or null

Subscription Status Checking

subscribed($type = 'default', $price = null)

Just $type: Checks valid subscription existence
With $price: Checks specific price subscription
Returns boolean

subscription($type = 'default')

Gets subscription by type
Returns Subscription model or null

subscriptions()

Gets all subscriptions
Returns HasMany relationship
No parameters needed

hasIncompletePayment($type = 'default')

Checks for incomplete payment on subscription
Returns boolean

subscribedToProduct($products, $type = 'default')

$products: Single product ID or array
$type: Subscription type to check
Returns boolean
Checks if subscribed to ANY of given products

subscribedToPrice($prices, $type = 'default')

$prices: Single price ID or array
$type: Subscription type to check
Returns boolean
Checks if subscribed to ANY of given prices

onProduct($product)

Checks for valid subscription with specific product
Returns boolean
More specific than subscribedToProduct

onPrice($price)

Checks for valid subscription with specific price
Returns boolean
More specific than subscribedToPrice

taxRates()

Gets tax rates for subscription
Returns array
Empty by default, meant to be overridden

priceTaxRates()

Gets tax rates for individual subscription items
Returns array
Empty by default, meant to be overridden

ManagesCustomer Trait

Customer Identification

stripeId()

Returns Stripe customer ID or null
No parameters needed
Returns string|null

hasStripeId()

Checks if customer has Stripe ID
Returns boolean
No parameters needed

Customer Creation and Management

createAsStripeCustomer(array $options = [])

Creates new Stripe customer
Options affect customer metadata, email, name, etc.
Throws exception if customer already exists
Returns Stripe Customer object

updateStripeCustomer(array $options = [])

Updates existing Stripe customer
Options determine what gets updated
Returns updated Stripe Customer object
Requires existing customer

createOrGetStripeCustomer(array $options = [])

Gets existing customer or creates new one
Options affect creation if needed
Returns Stripe Customer object
More forgiving than createAsStripeCustomer

updateOrCreateStripeCustomer(array $options = [])

Updates existing or creates new customer
Options affect both update and creation
Returns Stripe Customer object
Combines update and create functionality

syncStripeCustomerDetails()

Syncs local details to Stripe
Returns Stripe Customer object
Uses model attributes for sync

syncOrCreateStripeCustomer(array $options = [])

Syncs if exists or creates new customer
Options affect creation if needed
Returns Stripe Customer object

asStripeCustomer(array $expand = [])

Gets Stripe customer object
Expand parameter determines related data
Returns Stripe Customer object
Requires existing customer

Customer Attributes

stripeName()

Gets name for Stripe sync
Returns string|null
Default returns $this->name

stripeEmail()

Gets email for Stripe sync
Returns string|null
Default returns $this->email

stripePhone()

Gets phone for Stripe sync
Returns string|null
Default returns $this->phone

stripeAddress()

Gets address for Stripe sync
Returns array|null
Empty by default

stripePreferredLocales()

Gets preferred locales for Stripe
Returns array
Empty by default

stripeMetadata()

Gets metadata for Stripe
Returns array
Empty by default

Discount Management

discount()

Gets active customer discount
Returns Discount object or null
No parameters needed

applyCoupon($coupon)

Applies coupon to customer
Void return
Requires coupon ID

applyPromotionCode($promotionCodeId)

Applies promotion code to customer
Void return
Requires promotion code ID

findPromotionCode($code, array $options = [])

Finds promotion code
Returns PromotionCode object or null
Options affect search

findActivePromotionCode($code, array $options = [])

Finds active promotion code
Returns PromotionCode object or null
Options affect search

Balance Management

balance()

Gets formatted customer balance
Returns string
No parameters needed

rawBalance()

Gets raw customer balance
Returns integer
No parameters needed

balanceTransactions($limit = 10, array $options = [])

Gets customer balance transactions
Returns Collection
Limit affects returned count

creditBalance($amount, $description = null, array $options = [])

Credits customer balance
Returns CustomerBalanceTransaction
Amount is required

debitBalance($amount, $description = null, array $options = [])

Debits customer balance
Returns CustomerBalanceTransaction
Amount is required

applyBalance($amount, $description = null, array $options = [])

Applies balance adjustment
Returns CustomerBalanceTransaction
Amount is required

Tax Management

taxIds(array $options = [])

Gets customer tax IDs
Returns Collection
Options affect retrieval

createTaxId($type, $value)

Creates new tax ID
Returns Stripe TaxId
Both parameters required

deleteTaxId($id)

Deletes tax ID
Void return
Requires tax ID

findTaxId($id)

Finds specific tax ID
Returns Stripe TaxId or null
Requires tax ID

Tax Status Checking

isNotTaxExempt()

Checks if customer is not tax exempt
Returns boolean
No parameters needed

isTaxExempt()

Checks if customer is tax exempt
Returns boolean
No parameters needed

reverseChargeApplies()

Checks if reverse charge applies
Returns boolean
No parameters needed

Billing Portal

billingPortalUrl($returnUrl = null, array $options = [])

Gets Stripe billing portal URL
Returns string
ReturnUrl optional

redirectToBillingPortal($returnUrl = null, array $options = [])

Redirects to Stripe billing portal
Returns RedirectResponse
ReturnUrl optional

ManagesInvoices Trait

Invoice Items

tab($description, $amount, array $options = [])

Adds invoice item
Returns Stripe InvoiceItem
Description and amount required

tabPrice($price, $quantity = 1, array $options = [])

Adds price-based item
Returns Stripe InvoiceItem
Price ID required

Invoice Creation

invoiceFor($description, $amount, array $tabOptions = [], array $invoiceOptions = [])

Creates immediate invoice
Returns Invoice object
Description and amount required

invoicePrice($price, $quantity = 1, array $tabOptions = [], array $invoiceOptions = [])

Creates price-based invoice
Returns Invoice object
Price ID required

invoice(array $options = [])

Generates invoice
Returns Invoice object
Options affect creation

createInvoice(array $options = [])

Creates Stripe invoice
Returns Invoice object
Options affect creation

Invoice Retrieval

upcomingInvoice(array $options = [])

Gets upcoming invoice
Returns Invoice object or null
Options affect preview

findInvoice($id)

Finds specific invoice
Returns Invoice object or null
Requires invoice ID

findInvoiceOrFail($id)

Finds invoice or throws exception
Returns Invoice object
Requires invoice ID
Throws NotFoundHttpException or AccessDeniedHttpException

downloadInvoice($id, array $data = [], $filename = null)

Gets invoice PDF
Returns Response
ID required, filename optional

invoices($includePending = false, array $parameters = [])

Gets all invoices
Returns Collection
Parameters affect filtering

invoicesIncludingPending(array $parameters = [])

Gets all invoices including pending
Returns Collection
Shorthand for invoices(true)

cursorPaginateInvoices($perPage = 24, array $parameters = [], $cursorName = 'cursor', $cursor = null)

Gets paginated invoices
Returns CursorPaginator
Multiple parameters affect pagination

Key Observations

Parameter Sensitivity: Methods often have different behaviors based on parameter presence.
Return Types: Methods consistently return specific types (boolean, objects, collections).
Default Values: Many parameters have reasonable defaults but can be overridden.
Trait Interdependence: Methods often rely on other trait methods.
Stripe Integration: Most methods interact with Stripe's API either directly or indirectly.

Best Practices

Always check parameter requirements for desired behavior.
Handle potential exceptions, especially for *OrFail methods.
Use proper type hinting when extending these traits.
Test different parameter combinations thoroughly.
Consider caching frequent calls to reduce API requests.

Conclusion

These traits form the backbone of Laravel Cashier's functionality. Understanding the full scope of available methods and their parameter behaviors is crucial for proper implementation. Always consult the official documentation alongside this reference for the most up-to-date information.

Forem: Bilal Haidar

How to Use Claude.ai's Research Toggle Inside Claude Code

The Missing Feature That Changes Everything

The Problem: Web Search vs Research

What Web Search Does

What Research Does

Real World Comparison

The Gap

The Solution: Background Agents + Chrome Automation

Architecture

Prerequisites

Install Claude in Chrome Extension

Critical Fix: The Native Messaging Conflict

Diagnosing the Problem

The Fix

Reverting Later

Installing the Research Skill

File Structure

Step 1: Create the Directories

Step 2: Create SKILL.md

Step 3: Create agent-prompt.md

Step 4: Create the Slash Command

Step 5: Add to Your Project's CLAUDE.md

Using the Research Skill

Step 1: Start Claude Code with Chrome

Step 2: Verify Connection

Step 3: Run a Research Task

Step 4: Send to Background (if needed)

Step 5: Continue Working

Step 6: Check Status

Step 7: Review Results

Example Workflow

Troubleshooting

"Browser extension is not connected"

Research toggle not found

Task times out

Agent skips the Research step

Why This Matters

Credits

The Task Tool: Claude Code's Agent Orchestration System

Table of Contents

Introduction

What is the Task Tool?

Architecture

How It Works

Basic Invocation

What Happens

Key Parameters

Available Agent Types

1. General-Purpose Agent

2. Explore Agent

3. Plan Agent

4. Bash Agent

5. Feature Development Agents

code-reviewer

code-explorer

code-architect

6. Specialized Plugin Agents

Background vs Foreground Execution

Foreground (Default)

Background (run_in_background: true)

How to Request Background Execution

When to Use Which Agent

Decision Tree

Quick Reference

Practical Examples

Example 1: Codebase Exploration

Example 2: Deep Web Research

Example 3: Feature Planning

Example 4: Running Tests

Example 5: Security Review

Managing Background Tasks

View All Tasks

Check Task Progress

Kill a Task

Resume a Task

Best Practices

1. Choose the Right Agent

2. Be Specific in Prompts

3. Use Background for Long Tasks

Background (`run_in_background: true`)