Skip to content

Results from this documentation version only.

    ← Alcubi Delegator

    Set up a project for worktrees

    Every Delegator ticket runs in a fresh Git worktree to provide separation. Delegator doesn’t install anything in the worktree. To work seamlessly with worktrees there may need to be some setup so the agents can work more effectively.

    A worktree contains only tracked files. Everything your project ignores, as specified in .gitignore is unavailable. For example, this could be items like:

    • Installed dependencies, such as node_modules/ or .venv/.
    • Generated directories, including the hook directories that some hook managers create.
    • Local configuration, such as .env.
    • Build outputs and caches.

    Worktrees live under the Delegator data directory. For where they are and when Delegator removes them, see each ticket has its own checkout.

    Put one bootstrap command in the agent instructions file of the project (CLAUDE.md, AGENTS.md, or the file your agent reads):

    ## Fresh worktrees
    A new worktree has no installed dependencies. Run `npm ci` before you run
    anything else. For a Python project, run `uv sync`.

    Don’t let agents symlink or copy dependencies from your main checkout. Those files follow the lockfile of that checkout, and it can be behind the branch of the ticket. A tool may then fail in confusing ways, for example a linter that can’t load its configuration because a plugin was never installed.

    Add a second rule for the failure case:

    If a tool can't resolve a module, run the install command again. Don't work
    around the error.

    Delegator sets DELEGATOR_PROJECT_CACHE_DIR in every agent run and in dg ticket chat. It is one directory for each project, at <data dir>/cache/projects/<project id>, and all tickets of that project share it. Accepting a ticket doesn’t remove it, and its contents are disposable. Delegator doesn’t use the directory itself. It exists so you can point package manager caches at it.

    Terminal window
    npm_config_cache="$DELEGATOR_PROJECT_CACHE_DIR/npm" npm ci
    UV_CACHE_DIR="$DELEGATOR_PROJECT_CACHE_DIR/uv" uv sync

    Only point a tool at the directory if it supports concurrent access, because several tickets can install at the same time. Keep the same instructions working in your main checkout, where the variable is not set:

    If `DELEGATOR_PROJECT_CACHE_DIR` is set, use it for package manager caches:
    `npm_config_cache="$DELEGATOR_PROJECT_CACHE_DIR/npm" npm ci`.
    If it is not set, run `npm ci` without the prefix.

    An ignored hook will be unavailable in the worktree. That may cause pre-commit hooks to be bypassed when the agent commits code. Git will skip it, so a commit that should have been blocked will go through. This happens when the hook directory is generated and ignored.

    This happens when the hook directory is ignored. husky is one common example: it uses .husky/_, which is ignored and generated by the install step. Other hook managers may do the same.

    Keep the hooks in a tracked directory instead:

    .githooks/pre-commit

    Install hooks from the install step that every worktree already runs. This is the same command you put in the agent instructions. That step must run git config --local core.hooksPath .githooks. This will make the hooks available in the worktree.

    In a Node project, a prepare script does this, because npm runs it after npm install and npm ci:

    {
    "scripts": {
    "prepare": "git config --local core.hooksPath .githooks"
    }
    }

    Other ecosystems need a different place to run the same command. A Python project can call it from a task runner target or from a setup script that the install command runs. If your tooling has no install hook, add the git config line to the bootstrap command in the agent instructions, for example uv sync && git config --local core.hooksPath .githooks.

    core.hooksPath is stored in the repository config, which all worktrees share. Git resolves a relative path against the root of each worktree, so every worktree runs its own tracked copy of the hook. Because the hooks are tracked, every worktree has the hook files. A worktree that skipped the install doesn’t have the setting, so run git config --local core.hooksPath to check that it is set. Keep each hook file executable. Git skips a hook file that isn’t executable and, in recent versions, prints a hint.

    Define one command that runs everything the hook runs, and provide it in the agent instructions. Use the task runner of your project: make check, just check, npm run check, or a script in scripts/. For example, in a Node project:

    {
    "scripts": {
    "check": "npm run lint && npm run typecheck && npm test"
    }
    }
    Run `npm run check` before you finish. The pre-commit hook runs the same checks.

    This setup provides redundancy and a command for the agent to run as part of its development rather than waiting for the pre-commit hook to run. It does add additional run time so be sure to keep the check fast. You can utilize a scheduled agent to regularly monitor the timing of the checks and instruct it to create a dg ticket if the runtime exceeds a certain amount.

    A check can pass in a worktree and fail on main. This happens when your local copy of main holds files that git doesn’t track and doesn’t ignore, such as scratch notes or an exported data folder that you haven’t committed or added to .gitignore.

    A tool that you run on . doesn’t ask git which files belong to the project. It reads every file it can find, so it checks those local files too. A worktree holds only tracked files, so it doesn’t have them. The agent’s check passes there, and the same check, or the pre-commit hook, then fails on main because of files that are not part of the project.

    For example, you keep a notes/ folder in your copy of main and haven’t committed it:

    main worktree of a ticket
    ├── .gitignore ├── .gitignore
    ├── package.json ├── package.json
    ├── src/ ├── src/
    │ └── index.js │ └── index.js
    └── notes/ └── (no notes/ folder)
    └── scratch.js

    prettier --check . scans notes/scratch.js on main and reports errors in it. In the worktree the file doesn’t exist, so the same command passes.

    Add local-only folders to .gitignore, and to the ignore file of each tool that doesn’t read .gitignore. Then the check scans the same files on main and in every worktree.

    Files such as .env should be ignored, so they are not available in the worktree. Give tests the defaults they need in the test setup, or commit an example file such as .env.example that has safe values. Don’t ask agents to copy secrets from another checkout. Unit tests should not need credentials. Use fakes or recorded responses, so that npm run check passes in every worktree without secrets.

    Some integration tests call a real service and need a credential. Read the credential from an environment variable, not from a file. A worktree doesn’t have your .env, and an environment variable works the same way in main and in every worktree, without a copy step.

    Run these tests with their own command, so the main check doesn’t need them:

    {
    "scripts": {
    "test:integration": "node --test test/integration"
    }
    }

    Make the test skip with a clear message when the variable is missing. An agent that sees the message knows the cause and doesn’t look for the credential somewhere else:

    import { test } from 'node:test';
    const token = process.env.SERVICE_API_TOKEN;
    test('lists projects from the service', { skip: !token && 'SERVICE_API_TOKEN is not set' }, async () => {
    // call the service with the token
    });

    Set the variable in the environment of the agent run. How you do this depends on your agent, so check that a test run in a worktree sees the variable before you rely on it. Use a credential for a sandbox account with the smallest scope that the tests need. Delegator runs agents with your user permissions, so a production key adds exposure that the tests don’t need.

    Avoid hard-coded paths and shared resources

    Section titled “Avoid hard-coded paths and shared resources”

    Scripts must find the repository root with git rev-parse --show-toplevel, not with a path to your main checkout:

    Terminal window
    root=$(git rev-parse --show-toplevel)

    Several worktrees can run at once on one machine. Tests must not use fixed ports, database names, or container names, because two tickets will collide. Pick a free port, or add a random suffix to names. See set capacity for your working style for how many runs can happen together.

    • The agent instructions give one install command for a fresh worktree.
    • The instructions forbid symlinking or copying dependencies from another checkout.
    • The instructions say to rerun the install when a module can’t be resolved.
    • Package manager caches use DELEGATOR_PROJECT_CACHE_DIR when it is set.
    • Git hooks are tracked, and the install step sets core.hooksPath.
    • One check command runs everything the hook runs, and the instructions name it.
    • Local-only folders are ignored, so checks pass in every checkout.
    • Tests have the config defaults they need without a real .env.
    • Unit tests need no credentials, and integration tests read them from environment variables and skip when they are missing.
    • Scripts use git rev-parse --show-toplevel.
    • Tests don’t use fixed ports, database names, or container names.