Workspace setup

Workspace config tells HumanLayer where to create task worktrees, what branch names to use, which repositories belong to a task workspace, which local files to copy, and which setup commands to run.

Use this guide when you are setting up a repo for the first time. For every field, default, and merge rule, see the workspace config reference.

How it works

When you create a task with workspace setup enabled, HumanLayer reads workspace config from the repository you selected in the task form. It combines shared config with optional local overrides, then creates one worktree per configured repository.

The flow is:

1. You select a repository when creating a task.
2. HumanLayer looks for .humanlayer/workspace.json in that repository.
3. If .humanlayer/workspace.local.json exists, HumanLayer applies those local overrides on top of the shared config.
4. HumanLayer creates the task workspace using the effective config.
5. The task starts in the primary repo's worktree.

For a single-repo project, the task workspace usually contains one worktree. For a multi-repo project, it contains one worktree per configured repo.

For each configured repo, HumanLayer can:

• create a git worktree at a path derived from the task slug and repo name
• create a task branch from a configured source ref
• copy local-only files such as .env into the worktree
• run a setup command after the worktree exists
• start the task in the primary repo's worktree

Where the files go

Create the files inside the repository you select when creating a task:

your-repo/

.humanlayer/

workspace.jsonshared config

workspace.local.jsonlocal overrides

workspace.json is the shared configuration. Commit it when the settings are useful for the whole team.

workspace.local.json is optional. Use it for machine-specific paths, personal source refs, private setup commands, or repo additions/removals that should not affect teammates.

Best practices

• Commit .humanlayer/workspace.json when it describes the team's normal task workspace.
• Do not commit .humanlayer/workspace.local.json; add it to .gitignore.
• Keep workspace.json portable: avoid usernames, absolute local paths, private tokens, and machine-specific commands.
• Put local-only values in workspace.local.json, especially personal paths and secrets-related copy rules.
• Start with a single-repo config, then move to multi-repo only when a task usually needs coordinated work across multiple repos.
• Use one primary repo in multi-repo workspaces. HumanLayer starts sessions in the primary repo's worktree.
• Keep setup commands safe to run in a fresh worktree, such as bun install, pnpm install, or make bootstrap.

Add the local override file to .gitignore:

.humanlayer/workspace.local.json

Single-repo setup

Use a single-repo setup when tasks normally happen inside the selected repo.

Create .humanlayer/workspace.json:

{
  "pathTemplate": "~/.humanlayer/workspaces/{{ TASKSLUG }}/{{ REPOBASENAME }}",
  "branchTemplate": "{{ TASKSLUG }}",
  "repos": [
    {
      "localPath": ".",
      "description": "Project repo",
      "primary": true
    }
  ]
}

With this config, a task named eng-123-fix-login creates a worktree for the selected repo under:

~/.humanlayer/workspaces/eng-123-fix-login/<selected-repo-name>

Add a setup command when each fresh worktree needs dependencies installed:

{
  "setupCommand": "bun install",
  "repos": [
    {
      "localPath": ".",
      "primary": true
    }
  ]
}

Multi-repo setup

Use a multi-repo setup when a task workspace should include multiple sibling repositories, such as an API repo and a web repo.

In this example, the selected repo is a coordination repo or main repo, and the API and web repos live beside it:

projects/

platform/selected repo

.humanlayer/workspace.json

api/sibling repo

web/sibling repo

Create .humanlayer/workspace.json in the selected repo:

{
  "pathTemplate": "~/.humanlayer/workspaces/{{ TASKSLUG }}/{{ REPOBASENAME }}",
  "branchTemplate": "{{ TASKSLUG }}",
  "sourceRef": "HEAD",
  "setupCommand": "bun install",
  "repos": [
    {
      "localPath": ".",
      "description": "Primary monorepo OR coordination repository",
      "primary": true
    },
    {
      "localPath": "../api",
      "description": "API service"
    },
    {
      "localPath": "../web",
      "description": "Web frontend"
    }
  ]
}

This creates one worktree per repo:

~/.humanlayer/workspaces/eng-123-fix-login/

platformprimary repo worktree

apiAPI repo worktree

webweb repo worktree

The primary repo is the default launch directory for the task session. In multi-repo workspaces, choose the repo that should provide the session's local project context and agent configuration.

Local overrides

Use .humanlayer/workspace.local.json when your machine needs different behavior than the shared config.

For example, you can change your worktree path and add a local-only file to copy:

{
  "pathTemplate": "~/worktrees/{{ TASKSLUG }}/{{ REPOBASENAME }}",
  "copyGlobs": [".env.local"]
}

Or override one repo and remove another from your local workspace:

{
  "repos": [
    {
      "localPath": "../api",
      "sourceRef": "origin/main",
      "setupCommand": "bun install --frozen-lockfile"
    },
    {
      "localPath": "../web",
      "$patch": "delete"
    }
  ]
}

Local overrides are merged with shared config. Some fields replace shared values, while lists such as copyGlobs are appended and deduplicated. Repos are matched by localPath; a matching local repo overrides fields for that repo, a new local repo is added, and $patch: "delete" removes a repo locally.

For the exact merge rules, see workspace.local.json merge behavior.

Disable workspace setup

Set disabled when a repo should not use automatic workspace setup:

{
  "disabled": true
}

You can also disable or re-enable workspace setup locally without changing the shared file:

{
  "disabled": false
}

Troubleshooting

• If HumanLayer says no workspace config exists, confirm the files are in .humanlayer/ inside the selected repo.
• If JSON parsing fails, check for comments, trailing commas, or unknown keys. The files must be strict JSON.
• If a sibling repo is missing, confirm its localPath is relative to the selected repo.
• If copied files are missing, confirm the glob matches files in the source repo and that those files exist before task creation.
• If setup fails, run the setup command manually inside the created worktree to see the full error.

Next, read the workspace config reference for every field, default, and merge rule.