Laravel Worktree

https://github.com/mozex/laravel-worktree
Admin
Create and tear down isolated Laravel git worktrees, each with its own databases, .env and site, on...
Tokens:153,904
Snippets:917
Trust Score:8.5
License:MIT
Update:7 minutes ago
Show doc for...
Tokens:
Raw
### Cursor worktrees.json setup command

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Add this JSON to `.cursor/worktrees.json` so Cursor runs the adopt command in each worktree it creates. The `--no-secure` flag leaves HTTPS to your `site.secure` setting. Cursor stops setup after 300 seconds and starts its agent anyway; adopt rewrites `.env` before installing dependencies, so a stopped setup doesn't leave the worktree on your main database.

```json
{
  "setup-worktree": [
    "php worktree-adopt.php --tool=cursor --no-secure"
  ]
}
```

--------------------------------

### worktree:adopt usage examples

Source: https://github.com/mozex/laravel-worktree

Two usage examples: one provisions a worktree created by Cursor with a custom name and tool, and another runs the adopt script from a tool's setup script with the `--clone` flag.

```bash
# Provision a worktree Cursor made, named "agent"
php artisan worktree:adopt ../agent-worktrees/blog-3f2a --name=agent --tool=cursor
```

```bash
# From a tool's setup script (published via vendor:publish --tag=worktree-adopt):
php worktree-adopt.php --clone
```

--------------------------------

### Worktree setup output table

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Example output from `php artisan worktree:setup` showing the worktree path, branch, URL, database, and test database. The URL row only appears when the site driver served the worktree.

```text
Worktree ready.
+---------------+------------------------------------------+
| Path          | /Users/you/Sites/blog-feature-login      |
| Branch        | feature/login                            |
| URL           | https://blog-feature-login.test          |
| Database      | blog_feature_login                       |
| Test database | blog_feature_login_testing               |
+---------------+------------------------------------------+
```

--------------------------------

### Install agent setup for Conductor

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Run this artisan command to set up the Conductor tool. It writes `.conductor/settings.local.toml` and publishes `worktree-adopt.php` if missing. Options like `--clone`, `--no-clone`, `--seed`, `--no-migrate`, `--no-database`, `--no-install`, and `--tool` are passed to adopt.

```bash
php artisan worktree:install-agent conductor
```

--------------------------------

### Codex local environment setup script

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Set this as your project's setup script in the ChatGPT desktop app's Local environments settings. Codex copies files listed in `.worktreeinclude` before running the script and waits for it before the chat starts. Worktrees start on a detached HEAD in a directory named after your repository, so adopt names each by a short hash of its path.

```bash
php worktree-adopt.php --tool=codex --no-secure
```

--------------------------------

### Run worktree-adopt.php with --clone option

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Executes the published `worktree-adopt.php` script as the tool's setup command. The `--clone` option is passed through to `worktree:adopt`. Commit and push the script because a new worktree only contains what's committed on the branch it starts from.

```bash
php worktree-adopt.php --clone
```

--------------------------------

### worktree:setup command example

Source: https://github.com/mozex/laravel-worktree

Creates a worktree for the given branch. On success, prints a summary table with path, branch, URL, and database names; with --print-path, outputs only the path to stdout. Fails with exit code 1 if not run from the main repository or if the branch/database name is refused.

```bash
$ php artisan worktree:setup feature/login
Worktree ready.
+---------------+------------------------------------------+
| Path          | /Users/you/Sites/blog-feature-login      |
| Branch        | feature/login                            |
| URL           | https://blog-feature-login.test          |
| Database      | blog_feature_login                       |
| Test database | blog_feature_login_testing               |
+---------------+------------------------------------------+
```

--------------------------------

### worktree:install-agent

Source: https://github.com/mozex/laravel-worktree

Sets up a tool that makes git worktrees so each one gets its own databases, .env and site. The command accepts an agent argument and various options to customize the setup.

```APIDOC
## worktree:install-agent

### Description
Sets up a tool that makes git worktrees so each one gets its own databases, `.env` and site. The command accepts an agent argument and various options to customize the setup.

### Signature
```
worktree:install-agent
    {agent : The tool to set up: claude, git, conductor, paradev, cursor, codex, zed or devin}
    {--base= : The branch new worktrees start from (Claude Code only; default: the configured base branch, else the branch checked out here)}
    {--secure : Leave HTTPS to site.secure, as setup does, instead of serving each worktree over http}
    {--no-database : Skip creating databases and patching PHPUnit}
    {--no-migrate : Skip migrating the application database}
    {--no-install : Skip installing or copying dependencies, plus the migrations and steps that need them}
    {--seed : Seed the application database after migrating}
    {--clone : Copy the data of the main repository into the worktree databases}
    {--no-clone : Start from empty databases even when cloning is configured}
    {--timeout=1800 : Seconds Claude Code gives each hook before stopping it (Claude Code only)}
```

### Arguments / options

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `agent` | argument | yes | — | One of `claude`, `git`, `conductor`, `paradev`, `cursor`, `codex`, `zed`, `devin`. Anything else fails. |
| `--base` | string | no | configured `base_branch`, else the branch checked out | Base branch for worktrees Claude Code creates. Must resolve to a branch/commit (`git rev-parse --verify`), else `FAILURE`. |
| `--secure` | flag | no | — | Leave HTTPS to `site.secure` instead of passing `--no-secure`. |
| `--timeout` | int | no | `1800` | Seconds each Claude hook may run (min 1). |
| `--no-database` / `--no-migrate` / `--no-install` / `--seed` / `--clone` / `--no-clone` | flags | no | — | Passed on to setup/adopt (`profile()`). |

### Per-agent behavior

| Agent | What the installer does |
|-------|-------------------------|
| `claude` | Writes `WorktreeCreate` and `WorktreeRemove` hooks into `.claude/settings.local.json` (exec form: `PHP_BINARY -d display_errors=stderr {artisan} worktree:hook claude create --base=... --no-secure ...`). Refuses when shared `.claude/settings.json` or the local file already holds foreign hooks (`foreignEvents()`). Adds `/.claude/settings.local.json` to `git info/exclude` so it's ignored in every worktree; warns about stale `.worktreeinclude`. |
| `git` | Writes a `post-checkout` hook (sh) into the repo's own git hooks directory (refused when `core.hooksPath` points outside the git dir). The hook adopts only new worktrees' checkouts (first arg all `0` = new worktree, `$3 == 1` = branch checkout), skips `LARAVEL_WORKTREE_SKIP_ADOPT`, and runs `worktree:adopt --tool=git --unless-set-up ...`. A hook with other content is left alone; the commands are printed instead. |
| `conductor` | Publishes `worktree-adopt.php` and writes `.conductor/settings.local.toml` (`[scripts] setup = "php worktree-adopt.php --tool=conductor --no-secure ..."`), replacing only a file this command wrote before (marker comment). |
| `paradev` | Publishes the shim and adds the command to the `setup` list of `.superset/config.local.json` (after the repository's own setup). Refused when a `.superset/config.toml` exists (Paradev then reads no JSON). |
| `cursor` | Prints the lines for `.cursor/worktrees.json` (`{"setup-worktree": [...]}`). |
| `codex` | Prints the setup script for the ChatGPT desktop app's local environment. |
| `zed` | Prints a task for `.zed/tasks.json` (`create_worktree` hook). |
| `devin` | Prints a hook for `.devin/hooks.json` (`post_setup_worktree`), or `.windsurf/hooks.json` when only that one exists. |
```

--------------------------------

### Usage examples for worktree:install-agent

Source: https://github.com/mozex/laravel-worktree

Shows how to invoke the artisan command for different agents. Use --timeout=300 for Claude, and omit it for git and paradev. The command installs the specified agent into the worktree.

```bash
php artisan worktree:install-agent claude --timeout=300
php artisan worktree:install-agent git
php artisan worktree:install-agent paradev
```

--------------------------------

### install

Source: https://github.com/mozex/laravel-worktree

Appends a command to the setup list. For list-form setup, appends after the repository's own setup; for object-form, appends to the 'after' list. Replaces a previous command of this package's.

```APIDOC
## install

### Description
Appends a command to the setup list. For list-form setup, appends after the repository's own setup; for object-form, appends to the 'after' list. Replaces a previous command of this package's.

### Signature
```php
public function install(string $command): void
```

### Parameters
- **$command** (string) - Required - The command to append.
```

--------------------------------

### DatabaseManager usage example

Source: https://github.com/mozex/laravel-worktree

Shows how to instantiate DatabaseManager with a MySQL connection config and create, check existence, and drop a database.

```php
use Mozex\Worktree\Support\DatabaseManager;

$manager = new DatabaseManager(Config::get('database.connections.mysql'));
$manager->create('blog_feature_login');
$manager->exists('blog_feature_login'); // true
$manager->drop('blog_feature_login');
```

--------------------------------

### Path resolution order in PathCommand

Source: https://github.com/mozex/laravel-worktree

First match wins: recorded registry entry, registered git checkout, or computed setup path.

```php
$this->line($this->recordedPath($source, $branch)      // registry entry with this name (adopted worktrees)
    ?? $this->registeredPath($source, $branch)         // where git has the branch checked out
    ?? $this->worktreeFor($source, $branch)->path());  // where setup would put it
```

--------------------------------

### Publish worktree-adopt.php with vendor:publish --tag=worktree-adopt

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Publishes a small script (`worktree-adopt.php`) to the project root. This script finds the main checkout via git and runs `php artisan worktree:adopt` for the worktree it was started in, passing on any options you add. Use it as the tool's setup command.

```bash
php artisan vendor:publish --tag=worktree-adopt
```

--------------------------------

### Run worktree:install to publish config/worktree.php

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Publishes config/worktree.php where you configure the site driver, worktree location, database naming, and post-setup steps. If the config already exists, the command leaves it unchanged.

```bash
php artisan worktree:install
```

--------------------------------

### Configure multiple database connections with test databases

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Lists connections to isolate. Each entry names the env key because Laravel resolves env() at boot and the config holds the value, not the variable. Setup creates databases, rewrites env keys, and writes test databases into PHPUnit files. Give each connection a distinct name; setup stops if any worktree name matches a main database or if two connections land on the same server with the same name.

```php
'database' => [
    'connections' => [
        [
            'connection' => null,
            'env' => 'DB_DATABASE',
            'name' => '{slug}',
            'test' => ['env' => 'DB_DATABASE', 'name' => '{slug}_testing'],
        ],
        [
            'connection' => 'analytics',           // the name from config/database.php
            'env' => 'ANALYTICS_DB_DATABASE',      // this connection's .env key
            'name' => '{slug}_analytics',
            'test' => ['env' => 'ANALYTICS_DB_DATABASE', 'name' => '{slug}_analytics_testing'],
        ],
    ],
],
```

--------------------------------

### steps: Run provisioning commands after dependencies

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Configure the 'steps' block to run commands after dependencies are provisioned. The default steps build assets and link storage. Note that npm ci is used instead of npm install to avoid modifying package-lock.json; if your project lacks a committed lockfile, switch to npm install and add a name to package.json.

```php
'steps' => [
    'npm run build --if-present',
    'php artisan storage:link',
],
```

--------------------------------

### Worktree::make() usage example

Source: https://github.com/mozex/laravel-worktree

Shows how to create a Worktree instance using Worktree::make() and access derived properties: host(), path(), and database(). The example uses a sample config and demonstrates naming conventions.

```php
use Mozex\Worktree\Worktree;

$worktree = Worktree::make('/Users/you/Sites/blog', 'feature/login', $config);

echo $worktree->host();      // blog-feature-login.test
echo $worktree->path();      // /Users/you/Sites/blog/../blog-feature-login
echo $worktree->database('{slug}'); // blog_feature_login
```

--------------------------------

### worktree:prune usage examples

Source: https://github.com/mozex/laravel-worktree

Three usage examples: list gone worktrees, clean them up with `--force`, and find/confirm-remove unclaimed databases with `--orphans --force`.

```bash
php artisan worktree:prune                  # list gone worktrees
```

```bash
php artisan worktree:prune --force          # clean them up
```

```bash
php artisan worktree:prune --orphans --force  # find and confirm-remove unclaimed databases
```

--------------------------------

### EnvFile usage example

Source: https://github.com/mozex/laravel-worktree

Shows how to load a .env file, set a database name, remap a hostname, and save the changes to a target file.

```php
$env = EnvFile::fromFile($worktree.'/.env');
$env->set('DB_DATABASE', 'blog_feature_login');
$env->remapHost('blog.test', 'blog-feature-login.test');
$env->save($target);
```

--------------------------------

### Usage Example

Source: https://github.com/mozex/laravel-worktree

Example of using ParadevConfig to install a command and save the config.

```APIDOC
## Usage Example

### Description
Example of using ParadevConfig to install a command and save the config.

### Code
```php
use Mozex\Worktree\Support\ParadevConfig;

$config = ParadevConfig::fromFile($source.'/.superset/config.local.json');

if ($config === null) {
    return self::FAILURE; // not shaped the way Paradev reads it — left alone
}

$config->install('php worktree-adopt.php --tool=paradev --no-secure');

if (! $config->save($source.'/.superset/config.local.json')) {
    return self::FAILURE;
}
```
```

--------------------------------

### CommandDriver example usage config

Source: https://github.com/mozex/laravel-worktree

Example configuration using the command driver with nginx-helper commands. The serve command adds a site, check lists sites, and unserve removes a site. This demonstrates how to configure the driver for a CLI-based server.

```php
'site' => [
    'driver' => 'command',
    'drivers' => [
        'command' => [
            'serve' => ['nginx-helper', 'add', '{site}'],
            'check' => ['nginx-helper', 'list'],
            'unserve' => ['nginx-helper', 'remove', '{site}'],
        ],
    ],
],
```

--------------------------------

### ParadevConfig usage example

Source: https://github.com/mozex/laravel-worktree

Shows how to load, install a command, and save the Paradev config. Returns FAILURE if the config is null or save fails.

```php
use Mozex\Worktree\Support\ParadevConfig;

$config = ParadevConfig::fromFile($source.'/.superset/config.local.json');

if ($config === null) {
    return self::FAILURE; // not shaped the way Paradev reads it — left alone
}

$config->install('php worktree-adopt.php --tool=paradev --no-secure');

if (! $config->save($source.'/.superset/config.local.json')) {
    return self::FAILURE;
}
```

--------------------------------

### worktree:setup

Source: https://github.com/mozex/laravel-worktree

Creates an isolated git worktree for a branch and provisions it with site, .env, databases, dependencies, migrations, and steps. Must be run from the main repository.

```APIDOC
## [COMMAND] worktree:setup

### Description
Creates an isolated git worktree for a branch (creating the branch when needed) and provisions it: site, .env, databases, dependencies, migrations, steps.

### Signature
```
worktree:setup
    {branch? : The branch to work on (auto-generated when omitted)}
    {--base= : Base branch used when creating a new branch}
    {--no-database : Skip creating databases and patching PHPUnit}
    {--no-migrate : Skip migrating the application database}
    {--no-install : Skip installing or copying dependencies, plus the migrations and steps that need them}
    {--seed : Seed the application database after migrating}
    {--clone : Copy the data of the main repository into the worktree databases}
    {--no-clone : Start from empty databases even when cloning is configured}
    {--print-path : Print only the resolved worktree path (status goes to stderr), for shell integration}
```

### Arguments / Options

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `branch` | argument | no | auto-generated `feature/auto-{ymd-His}` | Branch to work on. Existing branches are checked out as-is; a branch that already has a worktree is resumed. Normalized by `cleanBranch()` (strips surrounding quotes/whitespace). |
| `--base` | string | no | `worktree.base_branch` (default `main`) | Base branch for a *new* branch. |
| `--no-database` | flag | no | — | Skip database creation and PHPUnit patching. |
| `--no-migrate` | flag | no | — | Create databases but skip migrations. |
| `--no-install` | flag | no | — | Skip dependency provisioning plus migrations and steps. |
| `--seed` | flag | no | `worktree.database.seed` | Seed after migrating. |
| `--clone` | flag | no | `worktree.database.clone.enabled` | Start from a copy of the main database. |
| `--no-clone` | flag | no | — | Start empty even when cloning is configured. |
| `--print-path` | flag | no | — | Route all human output to stderr; print only the worktree path on stdout. |

### Behavior
- Fails with `self::FAILURE` when the base path is not a git repository or is a linked worktree.
- On success prints a table and returns `self::SUCCESS`; with `--print-path` the last line on stdout is the path.
- Safe to re-run: an existing worktree for the branch is resumed rather than refused.

### Example
```bash
path=$(php artisan worktree:setup feature/login --print-path)
cd "$path"
```

```

--------------------------------

### worktree:setup command signature

Source: https://github.com/mozex/laravel-worktree

Defines the command-line interface for the worktree:setup command, including all arguments and options. Use this to understand the available flags and their purposes when invoking the command.

```bash
worktree:setup
    {branch? : The branch to work on (auto-generated when omitted)}
    {--base= : Base branch used when creating a new branch}
    {--no-database : Skip creating databases and patching PHPUnit}
    {--no-migrate : Skip migrating the application database}
    {--no-install : Skip installing or copying dependencies, plus the migrations and steps that need them}
    {--seed : Seed the application database after migrating}
    {--clone : Copy the data of the main repository into the worktree databases}
    {--no-clone : Start from empty databases even when cloning is configured}
    {--print-path : Print only the resolved worktree path (status goes to stderr), for shell integration}
```

--------------------------------

### ClaudeSettings usage example

Source: https://github.com/mozex/laravel-worktree

Shows how to load settings, check for foreign events, install handlers, and save. Refuses if foreign events exist.

```php
use Mozex\Worktree\Support\ClaudeSettings;

$settings = ClaudeSettings::fromFile($source.'/.claude/settings.local.json');

if ($settings === null || $settings->foreignEvents() !== []) {
    // refuse: an existing hook would double up
}

$settings->install([
    'WorktreeCreate' => ['type' => 'command', 'command' => PHP_BINARY, 'args' => [...], 'timeout' => 1800],
    'WorktreeRemove' => ['type' => 'command', 'command' => PHP_BINARY, 'args' => [...], 'timeout' => 1800],
]);

$settings->save($source.'/.claude/settings.local.json');
```

--------------------------------

### worktree:setup

Source: https://github.com/mozex/laravel-worktree

Creates a new Git worktree for the given branch, optionally setting up databases, migrations, and dependencies. Supports resumable setup and can print the final worktree path to stdout.

```APIDOC
## [ARTISAN] worktree:setup

### Description
Creates a new Git worktree for the given branch, optionally setting up databases, migrations, and dependencies. Supports resumable setup and can print the final worktree path to stdout.

### Method
Artisan command

### Endpoint
`php artisan worktree:setup [branch] [options]`

### Parameters
#### Arguments
- **branch** (string) - Optional - Branch to work on. Defaults to `feature/auto-{ymd-His}`. Existing branches are checked out as-is; setup is resumable.

#### Options
- **--base=** (string) - Optional - Base branch for a new branch. Defaults to `base_branch` config (`main`).
- **--no-database** (flag) - Optional - Skip databases and PHPUnit patching.
- **--no-migrate** (flag) - Optional - Create databases, skip migrations.
- **--no-install** (flag) - Optional - Skip dependency provisioning, migrations, steps.
- **--seed** (flag) - Optional - Seed after migrating. Defaults to `database.seed` config.
- **--clone** (flag) - Optional - Copy main database data. Defaults to `database.clone.enabled` config.
- **--no-clone** (flag) - Optional - Empty databases even when cloning is configured.
- **--print-path** (flag) - Optional - Status → stderr; final worktree path (only) → stdout.

### Response
#### Success Response (exit 0)
- Summary table with columns: `Path`, `Branch`, `URL`, `Database(s)`, `Test database(s)`.
- With `--print-path`: `{path}\n` on stdout.

#### Failure Responses (exit 1)
- Not a repo / linked worktree / refused name / refused database name → exit `1` with message.

### Request Example
```
$ php artisan worktree:setup feature/login
Worktree ready.
+---------------+------------------------------------------+
| Path          | /Users/you/Sites/blog-feature-login      |
| Branch        | feature/login                            |
| URL           | https://blog-feature-login.test          |
| Database      | blog_feature_login                       |
| Test database | blog_feature_login_testing               |
+---------------+------------------------------------------+
```
```

--------------------------------

### Database template expansion examples

Source: https://github.com/mozex/laravel-worktree

Shows expanding database name templates for a slug and a testing variant.

```php
$worktree->database('{slug}');        // blog_feature_login
$worktree->database('{slug}_testing'); // blog_feature_login_testing
```

--------------------------------

### PhpunitConfig usage example

Source: https://github.com/mozex/laravel-worktree

Shows how to load a phpunit.xml file, set an environment variable, and save the changes. Note that provisioning runs git update-index --skip-worktree on the file afterwards to avoid dirtying the worktree.

```php
$config = PhpunitConfig::fromFile($path.'/phpunit.xml');
$config->setEnv('DB_DATABASE', 'blog_feature_login_testing');
$config->save($path);
```

--------------------------------

### Example error handling in consumer code

Source: https://github.com/mozex/laravel-worktree

Shows how to instantiate DatabaseCloner and handle a failed cloneServer call. If cloneServer returns false, the Postgres source is busy and a pg_dump fallback is needed; the code throws WorktreeException::cloneSourceBusy when tools are missing.

```php
use Mozex\Worktree\Exceptions\WorktreeException;
use Mozex\Worktree\Support\DatabaseCloner;
use Mozex\Worktree\Support\DatabaseManager;

$manager = new DatabaseManager($config);
$cloner = new DatabaseCloner($manager, ['jobs', 'sessions']);

if (! $cloner->cloneServer('blog', 'blog_feature_login')) {
    // Postgres source busy — needs pg_dump fallback (done by ProvisionCommand:
    // throws WorktreeException::cloneSourceBusy when the tools are missing).
    throw WorktreeException::cloneSourceBusy('blog');
}
```

--------------------------------

### Run worktree:list to show worktrees

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Displays every worktree of the repository, along with the URL and database each one was provisioned with. The Tool column shows what made each worktree: `setup`, `adopt` (or the tool that made it, such as `--tool=cursor`), or `claude` for one Claude Code's hook made. A worktree with no record shows `-`.

```bash
php artisan worktree:list
```

--------------------------------

### AdoptCommand protected methods

Source: https://github.com/mozex/laravel-worktree

Lists the protected methods of `AdoptCommand` that handle site settings, worktree listing, move detection, branch setup, naming, and tool detection.

```php
protected function siteSettings(): SiteSettings
protected function listedWorktree(array $entries, string $path): ?array
protected function movedFrom(Registry $registry, string $path, string $porcelain): ?string
protected function setupBranch(string $source, string $path, ?string $branch, ?array $record): ?string
protected function adoptedWorktree(string $source, string $path, ?array $record, ?string $toolName): Worktree
protected function toolWorktree(string $path): ?array
```

--------------------------------

### Registry usage example

Source: https://github.com/mozex/laravel-worktree

Loads the registry from the git common dir, adds a worktree entry, and saves it. Catches WorktreeException to report and continue without registry.

```php
use Mozex\Worktree\Support\Registry;

try {
    $registry = Registry::fromFile($gitCommonDir.'/laravel-worktree/registry.json');
    $registry->put(['path' => '/wt', 'name' => 'agent', 'site' => 'blog-agent', 'branch' => null,
        'tool' => 'adopt', 'driver' => 'valet', 'secure' => false, 'host' => 'blog-agent.test',
        'url' => 'http://blog-agent.test', 'databases' => [], 'files' => [],
        'created' => date('c'), 'provisioned' => null]);
    $registry->save($file);
} catch (WorktreeException $e) {
    // registry is bookkeeping: commands warn and carry on without it
    report($e);
}
```

--------------------------------

### Devin Desktop post_setup_worktree hook in .devin/hooks.json

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Configures Devin Desktop's post_setup_worktree hook to run the adoption command in each worktree it makes. Devin reads the older .windsurf/hooks.json only while .devin/hooks.json is missing, so the installer prints the hook for whichever file your project already uses.

```json
{
  "hooks": {
    "post_setup_worktree": [
      {
        "command": "php worktree-adopt.php --tool=devin --no-secure",
        "show_output": true
      }
    ]
  }
}
```

--------------------------------

### Expand example with extra token

Source: https://github.com/mozex/laravel-worktree

Shows expanding a template with an extra 'value' token, producing e.g. 'blog_feature_login-cache-'.

```php
$worktree->expand('{slug}-cache-', ['value' => 'redis-cache']);
// e.g. 'blog_feature_login-cache-'
```

--------------------------------

### Usage from a custom driver

Source: https://github.com/mozex/laravel-worktree

Example of instantiating ProcessSiteRunner with base_path(), .env keys from EnvFile, a 60-second timeout, a hint, and a warning closure that writes to STDERR. Then runs a command and checks the result for null or failure.

```php
use Mozex\Worktree\Contracts\SiteRunner;

$runner = new ProcessSiteRunner(
    base_path(),
    array_fill_keys(EnvFile::fromFile(base_path('.env'))->keys(), false),
    60,
    'It may be waiting on a dialog.',
    fn (string $message) => fwrite(STDERR, $message.PHP_EOL),
);

$result = $runner->run(['mycli', 'serve', $site]);
if ($result === null) {
    // timed out or skipped — already warned
} elseif (! $result->successful()) {
    // ran and failed — judge here
}
```

--------------------------------

### Install Claude Code worktree hooks

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Run this artisan command to install WorktreeCreate and WorktreeRemove hooks into `.claude/settings.local.json`. The installer adds the file to `.git/info/exclude` and warns if it is committed. It refuses to run if either hook already exists. Options like `--base`, `--secure`, `--clone`, `--no-clone`, `--seed`, `--no-migrate`, `--no-database`, `--no-install`, and `--timeout` can be passed and are written into the hook. Re-run the installer to change options or after changing PHP version or project location.

```bash
php artisan worktree:install-agent claude
```

--------------------------------

### List worktrees with php artisan worktree:list

Source: https://github.com/mozex/laravel-worktree/blob/main/resources/boost/skills/laravel-worktree/SKILL.md

Use to see each worktree's branch, path, origin (setup, adopt, or tool), URL, and recorded database names. Helpful before teardown or to find a URL.

```bash
php artisan worktree:list
```

--------------------------------

### Create a worktree with a branch name

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Run `php artisan worktree:setup feature/login` to create a worktree for the given branch. The command outputs a summary table with the worktree path, branch, URL, database, and test database. The URL row only appears when the site driver served the worktree.

```bash
php artisan worktree:setup feature/login
```

--------------------------------

### Install git post-checkout hook with artisan worktree:install-agent git

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Installs a post-checkout hook into your repository's own git directory (.git/hooks) so any tool that uses git worktree add, or you yourself, can have worktrees adopted automatically. The hook runs only when git worktree add checks out a new worktree; switching branches, checking out files, and actions in your main checkout or another repository do not run adopt. A rerun replaces the whole hook file, and the installer warns when it finds Conductor's or Paradev's settings.

```bash
php artisan worktree:install-agent git
```

--------------------------------

### Configure host.site template for worktree site names

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Sets the site name template for worktrees. The 'site' key uses placeholders like {name}, {repo}, {branch}, and {slug} to generate the host. This example serves each worktree under the main site's host using the branch and repository name.

```php
'host' => [
    'template' => '{repo}-{branch}',
    'site' => '{branch}.{repo}',
],
```

--------------------------------

### Clone database for a worktree with --clone flag

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Use this artisan command to create a new worktree branch and clone the main database into it. The clone copies each connection's database and runs 'migrate' instead of 'migrate:fresh'. Test databases are never cloned, and running setup again on the same branch clones again, replacing the worktree's data.

```bash
php artisan worktree:setup feature/login --clone
```

--------------------------------

### EnvKit command driver configuration

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Example configuration for the 'command' driver using EnvKit on Windows or macOS. Uses string commands; note that strings don't go through a shell, so quotes don't group arguments. EnvKit names a site after its folder, so site names with capitals or underscores may not match.

```php
'command' => [
    'serve' => 'envkit sites-link {path}',
    'unserve' => 'envkit sites-remove {name}',
],
```

--------------------------------

### Yerd command driver configuration

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Example configuration for the 'command' driver using Yerd on macOS or Linux. Includes serve, secure, check, unsecure, and unserve commands. The check command passes when its output names the site, alone or followed by .{tld}.

```php
'site' => [
    'driver' => 'command',

    'drivers' => [
        'command' => [
            'serve' => ['yerd', 'link', '{name}', '{path}'],
            'secure' => ['yerd', 'secure', '{name}'],
            'check' => ['yerd', 'sites'],
            'unsecure' => ['yerd', 'unsecure', '{name}'],
            'unserve' => ['yerd', 'unlink', '{name}'],
        ],
    ],
],
```

--------------------------------

### Example output of worktree:list

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Example table output from `php artisan worktree:list`. The URL column shows `-` when the site driver serves nothing. The Database column only appears when a connection has a database the package named: a server database (MySQL, MariaDB, or PostgreSQL), or the SQLite file it places next to a main database kept outside the repository.

```text
 ---------------- -------------------------------------- ------- ---------------------------------- ---------------------
  Branch           Path                                   Tool    URL                                Database
 ---------------- -------------------------------------- ------- ---------------------------------- ---------------------
  feature/login    /Users/you/Sites/blog-feature-login    setup   https://blog-feature-login.test    blog_feature_login
  feature/search   /Users/you/Sites/blog-feature-search   setup   https://blog-feature-search.test   blog_feature_search
 ---------------- -------------------------------------- ------- ---------------------------------- ---------------------
```

--------------------------------

### worktree:install-agent

Source: https://github.com/mozex/laravel-worktree

Sets up an agent tool for the worktree. It accepts an agent name and various options to configure the setup, such as base branch, security, timeout, and forwarding flags to setup/adopt.

```APIDOC
## worktree:install-agent

### Description
Sets up an agent tool for the worktree. It accepts an agent name and various options to configure the setup, such as base branch, security, timeout, and forwarding flags to setup/adopt.

### Method
Artisan Command

### Endpoint
`php artisan worktree:install-agent {agent} [options]`

### Parameters
#### Arguments
- **agent** (string) - Required - The agent to install. One of: `claude`, `git`, `conductor`, `paradev`, `cursor`, `codex`, `zed`, `devin`.

#### Options
- **--base=** (string) - Optional - (claude) Base for new branches. Default: configured `base_branch`, else current branch.
- **--secure** (flag) - Optional - Leave HTTPS to `site.secure` (claude/git). Default: off.
- **--timeout=** (int) - Optional - (claude) Seconds per hook. Default: `1800`.
- **--no-database** (flag) - Optional - Forwarded to setup/adopt. Default: off.
- **--no-migrate** (flag) - Optional - Forwarded to setup/adopt. Default: off.
- **--no-install** (flag) - Optional - Forwarded to setup/adopt. Default: off.
- **--seed** (flag) - Optional - Forwarded to setup/adopt. Default: off.
- **--clone** (flag) - Optional - Forwarded to setup/adopt. Default: off.
- **--no-clone** (flag) - Optional - Forwarded to setup/adopt. Default: off.

### Response
Exit `0` with what was written/added. For `cursor`, `codex`, `zed`, `devin`, prints the lines to add to a file instead of writing (exit `0`).
```

--------------------------------

### Laragon command driver configuration

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Example configuration for the 'command' driver using Laragon on Windows. Only a serve command is provided to reload Laragon; it cannot remove sites from the command line. The Laragon app must be running for the command to work.

```php
'command' => [
    'serve' => ['C:\laragon\laragon.exe', 'reload'],
],
```

--------------------------------

### Custom SiteDriver implementation example

Source: https://github.com/mozex/laravel-worktree

Shows how to implement the SiteDriver contract for a custom server. The available method checks for the server binary, url builds the site URL, serve runs the add command and warns on failure, isServed returns null (cannot tell), unserve removes the site, and timeoutHint provides a hint about elevation prompts.

```php
use Mozex\Worktree\Contracts\SiteDriver;
use Mozex\Worktree\Contracts\SiteRunner;
use Mozex\Worktree\Worktree;

class MyServerDriver implements SiteDriver
{
    public function available(): bool
    {
        return (bool) shell_exec('command -v myserver');
    }

    public function url(Worktree $worktree, bool $secure): ?string
    {
        return ($secure ? 'https' : 'http').'://'.$worktree->host();
    }

    public function serve(Worktree $worktree, bool $secure, SiteRunner $runner): bool
    {
        $result = $runner->run(['myserver', 'add', $worktree->site()], $worktree->path());

        if ($result?->successful() === true) {
            return true;
        }

        $runner->warn('Could not serve the site with myserver.');

        return false;
    }

    public function isServed(string $name, string $path, SiteRunner $runner): ?bool
    {
        return null; // cannot tell
    }

    public function unserve(string $name, string $path, bool $secure, SiteRunner $runner): void
    {
        $runner->run(['myserver', 'remove', $name]);
    }

    public function timeoutHint(): string
    {
        return 'It may be waiting on an elevation prompt.';
    }
}
```

--------------------------------

### configurePackage method signature

Source: https://github.com/mozex/laravel-worktree

Declares the package configuration method. Registers the package name, config file, all eight artisan commands, and the install command that publishes config and asks to star the repository.

```php
public function configurePackage(Package $package): void
```

--------------------------------

### SettingsFile usage: json encode and write

Source: https://github.com/mozex/laravel-worktree

Shows how to use SettingsFile::json() to encode a value with pretty printing and 2-space indent (as Claude Code and agent tools write), catching JsonException, and SettingsFile::write() to atomically write the file via Directory::replaceFile(). The example writes to .windsurf/hooks.json.

```php
try {
    $json = SettingsFile::json(['hooks' => ['post_setup_worktree' => [['command' => $command]]]]);
} catch (JsonException) {
    return false;
}

if (! SettingsFile::write($source.'/.windsurf/hooks.json', $json)) {
    // report failure
}
```

--------------------------------

### Zed create_worktree task in .zed/tasks.json

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Adds a 'Set up the worktree' task to .zed/tasks.json that runs on the create_worktree hook in each worktree Zed makes. Zed starts its agent without waiting for the task; in a trusted project it also runs git hooks, so the git hook works with nothing committed.

```json
[
  {
    "label": "Set up the worktree",
    "command": "php",
    "args": ["worktree-adopt.php", "--tool=zed", "--no-secure"],
    "hooks": ["create_worktree"],
    "reveal": "no_focus",
    "hide": "on_success"
  }
]
```

--------------------------------

### Create a worktree with auto-generated branch name

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Run `php artisan worktree:setup` without a branch name to have one generated automatically, e.g., `feature/auto-260714-193000`. The command outputs a summary table with the worktree path, branch, URL, database, and test database.

```bash
php artisan worktree:setup
```

--------------------------------

### Configure phpunit_files for multiple PHPUnit configs

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Lists PHPUnit config files to patch. Defaults to ['phpunit.xml', 'phpunit.xml.dist']; every listed file that exists gets patched. Files left out keep the test database name from the main checkout.

```php
'phpunit_files' => ['phpunit.xml', 'phpunit.browser.xml'],
```

--------------------------------

### ParadevConfig constructor and factory methods

Source: https://github.com/mozex/laravel-worktree

Defines the constructor and static factory methods for ParadevConfig. fromFile returns an empty config for a missing file or null for unreadable files; parse requires a JSON object and validates setup structure.

```php
public function __construct(protected stdClass $config = new stdClass) {}

public static function fromFile(string $file): ?self
public static function parse(string $json): ?self
```

--------------------------------

### dependencies: Copy vendor and node_modules when safe

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Configure the 'dependencies' block to copy vendor and node_modules from the main repository into the worktree when the lock files match byte-for-byte. Copying is off by default; enable per entry or via WORKTREE_COPY_VENDOR and WORKTREE_COPY_NODE_MODULES. If the lock file differs, the package installs from scratch instead.

```php
'dependencies' => [
    'vendor'       => ['copy' => true, /* ... */],
    'node_modules' => ['copy' => true, /* ... */],
],
```

--------------------------------

### Handler shape written by installer

Source: https://github.com/mozex/laravel-worktree

Example of a handler array with type, command, args, timeout, and statusMessage. Used by worktree:install-agent claude.

```php
[
    'type' => 'command',
    'command' => PHP_BINARY,                 // e.g. /usr/local/bin/php
    'args' => ['-d', 'display_errors=stderr', $artisan, 'worktree:hook', 'claude', 'create', '--base=main', '--no-secure'],
    'timeout' => 1800,
    'statusMessage' => 'Setting up the worktree',
]
```

--------------------------------

### worktree:adopt

Source: https://github.com/mozex/laravel-worktree

Provisions a worktree that was created by another tool. It accepts a path to an existing worktree and applies the standard setup steps, with options to control database, installation, and security behavior.

```APIDOC
## [CLI] worktree:adopt

### Description
Provisions a worktree that was created by another tool. It accepts a path to an existing worktree and applies the standard setup steps, with options to control database, installation, and security behavior.

### Method
CLI

### Endpoint
`php artisan worktree:adopt {path} [options]`

### Parameters
#### Arguments
- **path** (string) - Required - Worktree directory; must appear in `git worktree list`.

#### Options
- **--name=** (string) - Optional - Name standing in for the branch in the host template. Default: Conductor workspace name, else `substr(md5(path),0,8)`.
- **--tool=** (string) - Optional - What made the worktree (recorded); `setup` refused. Default: `adopt`.
- **--no-database** (flag) - Optional - As setup.
- **--no-migrate** (flag) - Optional - As setup.
- **--no-install** (flag) - Optional - As setup.
- **--seed** (flag) - Optional - As setup.
- **--clone** (flag) - Optional - As setup.
- **--no-clone** (flag) - Optional - As setup.
- **--no-secure** (flag) - Optional - Serve over http even when the driver would secure.
- **--unless-set-up** (flag) - Optional - Exit `0` when the record says provisioning finished and `.env` exists.

### Response
#### Success Response (exit 0)
- Summary table printed.
- With `--unless-set-up`: prints `"{path} is set up already."` and exits `0`.

#### Error Response (exit 1)
- Failures: unknown path, main checkout, setup-made worktree, moved worktree, `--tool=setup`.
```

--------------------------------

### create()

Source: https://github.com/mozex/laravel-worktree

Creates a database on the server. Throws for non-server drivers.

```APIDOC
## create()

### Description
Creates a database on the server. Throws for non-server drivers.

### Method
`create(string $name): void`

### Parameters
- **$name** (string) - Required - The name of the database to create.

### Behavior
- Connects server-side and runs the create statement.
- Postgres: no-op when the database exists.
- Throws `WorktreeException::unsupportedDriver()` for non-server drivers.
```

--------------------------------

### Install laravel-worktree as a dev dependency

Source: https://github.com/mozex/laravel-worktree/blob/main/README.md

Install the package as a dev dependency using Composer. Requires PHP 8.2+.

```bash
composer require mozex/laravel-worktree --dev
```

--------------------------------

### worktree:list signature

Source: https://github.com/mozex/laravel-worktree

Lists linked worktrees with their sites and databases. No arguments or options.

```text
worktree:list
```
Tokens:
Raw