Lyre / documentation
Get Lyre
Workspaces and agents

Work with parallel agents in Git worktrees

Give independent implementation, investigation or review tasks separate working copies, choose their starting refs and inspect results before integration.

On this page

Can I work with several agents without sharing one checkout?

Yes. Create separate Git worktree workspaces for independent tasks and choose an available coding agent in each. Each worktree has its own working files and branch context while sharing the repository. This can separate implementation, investigation and review; it does not promise faster results or merge the work automatically. A worktree is not a process or permission sandbox.

Prepare a repository and a shared starting point

What you’ll need
  • A Git repository on the selected Lyre host, a compatible host with worktree support, and an approved project/workspace. A plain folder without Git cannot provide this worktree workflow.
  • Owner access, or the required Developer access to that approved project. App-only viewers cannot create workspaces, run agents or use Git tools. Worktree isolation does not expand a project grant.
  • A known starting branch and commit for the tasks. Preserve current edits before creating new worktrees; uncommitted and ignored files from another checkout do not become the new branch’s committed base.
  • Review the project’s committed worktree setup configuration before creation. Creating a worktree can execute its configured setup commands under the host account.
  • Connected agent software, enough host memory and CPU for the chosen tasks, and the project’s dependencies and development configuration in each new working copy. Provider accounts, quotas and usage charges still apply.

Check build and client availability, coding-provider setup and workspace basics. Claude Code, Codex and other supported providers retain their own models, features and approval controls. Choose the providers that fit the tasks rather than assuming their child-agent features create Lyre worktrees.

Split by independent outcome

Use separate tasks with limited overlap. This example is a suggested division of work, not an automatically created agent team.

Task Starting point Expected result
Implement an import validation fix The agreed baseline commit A small diff and its focused checks
Investigate slow list loading The same baseline, in another worktree A read-only diagnosis and proposed check before edits
Review the validation fix The implementation’s actual completed branch or supported PR checkout Findings against that change, with no edits unless requested

A reviewer starting only from the old baseline cannot see another worktree’s uncommitted edits. Record the branch and commit being reviewed. Opening another conversation in the same workspace still shares its files; create the separate worktree deliberately.

Choose isolation and the exact starting ref

  1. Open New workspace for the project

    In the project’s GitHub surface, use WorktreesNew workspace, or the existing new-workspace action. Check the selected Project and Computer. Workspace guidance explains where the work belongs.

  2. Select a separate working copy

    Set IsolationNew worktree. Confirm the host actually supports the option. Local uses the existing directory and is not a second isolated checkout. Do not continue a parallel edit in Local just because worktree creation is unavailable.

  3. Choose the base deliberately

    Use Starting branch or PR to select the intended ref. Local and origin/upstream refs can differ; check which one is selected and inspect its commit before starting. Refreshing a panel is not a remote fetch. A branch choice starts a new branch from that ref; a supported PR selection checks out that change for review.

  4. Check the resulting branch and workspace

    Choose the agent/model and submit the bounded task. In the created workspace, inspect Current branch and the workspace identity; record the resulting branch name and starting commit. New branch names may be generated. If your team requires a specific name, use its existing branch workflow before making edits; advanced operations remain in Git tools and depend on host support and their confirmation guards.

Creation check

Each task opens in the intended project on the intended computer, with a distinct worktree and the expected branch/base. Check this before letting two agents modify files.

Prepare each working copy before running it

Inspect the output of configured worktree setup commands and complete any missing preparation. Install dependencies using the project’s existing lockfile and package manager in each new worktree. Prepare ignored environment files and test data explicitly; installed packages and secrets are not automatically copied from the original checkout. Host preparation covers those requirements.

Use separate development databases or other resources when tasks could change the same data. Services need non-conflicting ports and correct backend addresses. Follow project service configuration and stack recipes before opening a preview for a particular worktree. A worktree does not isolate shared services, credentials, network access or host processes.

Give each agent an explicit contract

Adapt the paths and acceptance checks to the actual repository. This example asks one agent to implement the agreed fix in its assigned worktree: 

Work only on the import validation task in this workspace.
Confirm the selected branch and starting commit before editing.
Preserve unrelated work. Keep changes within the agreed parser and
its tests; ask before expanding scope. Do not switch branches,
merge, publish or edit another worktree. Report changed files,
the exact checks and results, and any remaining uncertainty.

Give an investigator a read-only diagnosis request first. Give a reviewer the actual change branch or PR, and ask for findings against its base. Review tool approvals for each agent. Task modes and Orchestrate remain available through their own controls; a task mode or a prompt restriction does not enforce a host permission boundary.

Collect evidence from each task

  1. Inspect each workspace separately

    Use the current-worktree picker or Worktrees to open the right workspace. Read Changes and confirm the branch, affected files and scope. Keep diff review tied to that selected worktree rather than another agent’s summary.

  2. Check the reported results

    Inspect actual test output and unresolved errors. Test the changed behavior with its proper tools; for web work, open that worktree’s app and interact with it. A completed turn or running service is not proof of passing checks.

  3. Review the completed change

    Make the intended branch/commit available through your normal review workflow, then review the actual diff and findings. Do not count a review of the original baseline as a review of the implementation.

Success check

Every result identifies its worktree, branch, reviewed change and check output. You can explain which independent task it completes and what still needs integration.

Integrate only after review

Creating worktrees and finishing agent turns do not merge changes. Choose which result to keep, inspect the target branch and current work, then use your repository’s existing commit, pull-request and merge workflow. Main Changes owns working/staged review; Git tools holds available advanced branch operations. Git review remains the entry point.

Read the target, included commits and confirmation before a merge or other mutation. Preserve dirty work and resolve conflicts deliberately; do not bypass a refusal or retry an operation whose result is unknown. Inspect repository state first. Re-run the checks affected by the combined result and try its real behavior before treating it as accepted.

When work is finished, use the workspace’s existing archive flow and read any running-work or worktree-removal confirmation. Check for uncommitted or untracked files you need to retain. Closing a conversation pane does not stop its work, and archiving is not evidence that a branch has been merged. See workspace lifecycle.

Recover without losing another task’s work

New worktree is missing or creation fails
Check that this project is a Git repository on a connected compatible host and that your grant permits workspace creation. Inspect the existing workspace list before retrying; do not silently fall back to a shared Local checkout.
The task starts from the wrong code
Stop the agent, preserve any edits and inspect the selected ref and commit. A local branch can differ from its upstream; use the intended base before asking for more changes.
A test or app works only in the original checkout
Check dependencies, ignored configuration, generated inputs, development data and ports in this worktree. Do not copy production secrets or share a mutable database merely to get a passing run.
Two tasks need the same files or service
Reduce concurrency or define ownership and integrate one result first. Separate files do not prevent conflicts in shared data, global tools or repository-wide operations.
The host disconnects or a Git result is uncertain
Reconnect, inspect the same workspace and its actual status, then decide the next action. Check host recovery and the visible Git diagnostic. Avoid automatic retries that could duplicate a mutation.