Should agents bind to a local directory, or stick with the worktree-per-run model?

[Bohan-J]

We've been hearing from a number of users who'd like the ability to bind an agent to an existing local directory, rather than the current model where each run gets its own worktree. Before we go and build it, we want to open this up — because the worktree model is doing real work for us today, and we don't want to lose what it gives us without first understanding why people are asking for the change.

How it works today: one worktree per run

Every agent run gets its own git worktree on a dedicated branch. Concretely:

• You can open 10 issues at once and have 10 different agents iterate on them in parallel.
• None of those agents step on each other — no local file write contention, no "wait for agent A to finish before agent B starts," no mid-run conflicts on disk.
• The agents' working state is isolated from your own checkout, so you can keep coding locally while they run.

For the way we build Multica itself, this has been a meaningful productivity unlock. Parallelism on the same repo just works.

What we're hearing

Some users want the agent to operate directly inside a chosen local directory — presumably so changes show up in their existing editor without pulling a branch, or so they can iterate with the agent on a single working copy they're already using.

That's a reasonable thing to want. But it would also mean giving up (or significantly complicating) the "10 agents on one repo, no conflicts" property.

What we're not yet sure about

Before adding a "bind to local directory" mode, we'd like to better understand the underlying need:

1. Is there a concrete workflow that the current worktree model genuinely blocks? E.g. something where the round-trip via a branch breaks the loop you're trying to run.
2. Or is it mostly that the parallel-agent model hasn't been fully discovered yet? Folks coming from single-agent CLI tools often default to "one agent, one repo" thinking and may not have tried running several agents in parallel on the same project.

If it's (1), we want to design for it properly. If it's mostly (2), the right fix is probably docs and onboarding around parallel agents — not removing the isolation that makes parallelism safe.

We'd love to hear from you

• If you've asked for local-directory binding: what's the specific workflow where worktrees got in your way?
• If you've leaned into the parallel-agent model: what does a typical day look like, and what would you lose if local-binding became the default?
• Anything in between — partial use cases, hybrid ideas, "I'd want both" stories.

Thanks for the input.

[fabiogalera]

I think the worktree model is the right default, but the missing piece is review/control UX.

The ideal flow for me would be: each agent run still gets an isolated worktree, but Multica makes that worktree first-class. I want to open the exact folder the agent is editing, inspect uncommitted changes live, run tests locally, and decide whether to commit/push myself.

For security-sensitive workflows, I would also like a mode where the agent has no GitHub credentials and cannot push. Potentially even no local commit ability, so the output is just an editable worktree plus a patch/diff artifact. Then a human or lead agent can review before any commit exists.

This preserves the advantage of safe parallelism. Ten agents can still work on ten issues without touching my main checkout. But it also gives users the feeling of direct local control that they are asking for from “bind to local directory.”

I would treat local-directory binding as an explicit pair-programming mode for single-agent workflows, not the default.

[seepine]

The worktree is excellent.

List my workflow for everyone's reference.

• Set up a Gitea code repository and Multica platform.
• Created a separate Git account for the agent.
• Using Docker to run the VM ubuntu, and configuring Claude、 Git accounts and Multica Daemon.
• Create an organization and repo in Gitea, allowing the agent to collaborate through forking and submitting pull requests.
• Agent use giteacli creating PR and viewing review results.
• I create issues on Multica. Review code and release artifacts on Gitea.

Therefore, it would be better to isolate each task as much as possible, and it would also be more beneficial for handling multiple issues in parallel.

[douglas-pereira-1]

I think binding a single repository to the workspace and using git worktrees per task would be a better model.

From my perspective, the issue is not parallel development itself — worktrees actually preserve that capability. Each task can still run in an isolated working tree and branch, so agents don’t step on each other, while avoiding the need to clone/pull the full repository for every task.

Technically, this seems like a good middle ground:

• one repository "instance" bound to the workspace;
• multiple task-specific worktrees for isolation;
• preserved parallel execution;
• less disk usage and less repeated repository setup;
• easier lifecycle management, since old task worktrees could be pruned/cleaned up.

So I don’t see worktrees as a trade-off against parallelism. I see them as a way to keep the benefits of parallel execution while reducing the overhead of having a separate repository checkout per task.

The main thing I’m unsure about is whether there’s already a cleanup mechanism for old task directories/worktrees. If not, that would be an important part of the design, and also the ability to bind a directory to a project to avoid the agent choosing arbitrary projects to work on.

[Bohan-J]

Thanks @douglas-pereira-1 — this is exactly the kind of nuanced framing we were hoping the discussion would surface. The "shared repo instance + per-task worktree" mental model is the same one we landed on internally, so it's reassuring to hear it articulated from the outside.

A quick note on the cleanup question, since you flagged it as a missing piece — it's actually already in place today:

• A single repo is checked out once per workspace under the daemon's working directory; subsequent task runs reuse that clone.
• Each task gets its own git worktree on a dedicated branch, so isolation and parallelism are preserved without re-cloning.
• The daemon runs a periodic cleanup pass that prunes worktrees whose underlying task is finished (merged / closed / cancelled) and whose branch has been pushed or is no longer needed locally. Active worktrees are never touched.
• git worktree prune is also run to keep the admin metadata in sync.

So in practice you get the "one repo instance, many short-lived worktrees, auto-pruned" lifecycle you described, without users having to manage it by hand.

The "bind a directory to a project so the agent doesn't pick arbitrary repos" point is a separate and valid one — we'll fold that into the next round of thinking on this thread.

Appreciate the writeup!

[douglas-pereira-1]

@Bohan-J Thanks for the detailed response!

We’re currently running daemon version 0.2.22, and in this version it still seems to execute multica repo checkout <repository_link> for each task, creating separate repository copies under the daemon workdir (~/multica_workspaces/<workspace_id>/<task_id>/workdir/<repository_copy>).

Because of that, I’m not yet seeing the “shared repo + per-task worktree” model in practice. I might be missing something, but from what I can observe, each task still results in a full repository copy.

When you mentioned that this is already in place today, I wasn’t sure whether:

this behavior should already be happening in the current version, or
if this is part of a newer update that hasn’t reached our setup yet.

My main issue right now is with large repositories — since each task creates a new copy, it ends up consuming a significant amount of disk space and adds overhead to each run.

[CyborgYL]

@Bohan-J I'm working on exsiting game project. The current worktree mode is a no-go for me. the worktree is 100GB just for the engine part. Creating a seperate worktree per agent per issue is impossible.
Now the workaround is to disable git checkout in config and firstly run a prepare phase to setup symlink to the worktree I manually created beforehand and have agents all symlinking to that exsiting worktree.
I whish there is a toggle button built directly into multica to use local worktree instead of creating seperate ones everytime, just like in Codex.

[guilhermesilveira]

Take a look at my worktree-manager project. It creates a pool of working trees and recycles them (you might want to setup the max number). Even allocating huge wt are time and Io consuming. So Recycling in a pool as I do there helps a lot.
Right now I do it by adding the description in all agents that they should request for the worktree manager a pooled wt. It's a copy and paste amongst agents but would love to see multica supporting pooled working trees natively.

[lucas-p-costa]

One clarification about my local workflow: I don’t personally want worktrees to be mandatory.

I understand they are useful for users who run many tasks in parallel, and I agree they should remain available. But my workflow is more supervised and sequential: I prefer one canonical local repo, one current change set, review the diff myself, then decide what to commit/push.

For example, in Codex I usually leave the worktree option disabled.

Today I’m working around this in Multica with a local repo rule in my agent instructions/config: I explicitly tell agents that the canonical repo root is a fixed local path, and that the transient Multica workdir is not the source of truth. Agents must write artifacts into the canonical repo path, not wherever the task happens to run.

That workaround works, but it is brittle because it relies on prompt/config discipline instead of a first-class project setting.

So my request would be:

• support binding a Multica project/workspace to a local repository path;
• make worktree usage optional/configurable per project or task;
• allow a direct local-repo mode for slower, supervised, one-change-at-a-time workflows;
• keep worktrees available for users who want isolation and parallelism;
• make Git actions such as commit/push explicit and user-controlled.

In short: I’m not asking to remove worktrees. I’m asking for first-class local repo binding, plus an option to disable worktrees when the user prefers to work directly in the bound local repo.

[lucas-p-costa]

Small follow-up: I’ve also been following #787 since it was opened, and I’m really looking forward to seeing it merged.

Local repositories as a first-class concept, project-to-repo linking, and multica run from a local path are very close to what I was trying to work around with my local repo rule in agent instructions.

I’ll keep using my workaround for now because I still prefer a direct, supervised, one-change-at-a-time local repo flow. But I’m very happy to see this moving forward.

My remaining ask is configurability: keep worktrees for users who want isolation/parallelism, but allow an option to disable them and work directly in the bound local repo.

[jorge-gbs]

So this might be a user skill issue, in this case myself, but with regards to the multi-work tree structure.

I'm working on a Laravel application, and it's been a little difficult to wrap my head around how to properly test the different work trees and view maybe the live site for them. That's been a challenge.

Whereas using a single repo and local directory would be very straightforward. Again, probably a skill issue, but having the option would be great. If anyone wants to drop a guide of the ideal workflow for these types of projects, that'd be fantastic.

[alexgrozav]

The worktree approach is great, in my opinion, and it's the standard approach right now for agent collaboration. I think you're trying to fix the wrong issue. The thing that's severely lacking is control and visibility over the code and workspace:

As a developer, I need:

• a way to know what the worktree for the current issue is
• a way to know what the branch name for the current issue is
• a way to open a worktree in an IDE of my choice at the click of a button
• a way to explore the worktree in a project-tree view
• a way to setup my application for the current worktree
• a way to build my application for the current worktree
• a way to run my application for the current worktree
• a way to cleanup my application for the current workftree
• a way to open, read, edit, and search a file from the worktree
• a way to explore the current worktree diff in a git diff view
• a way to view my CI workflow run status so that I can reference failures in the discussion
• a way to coordinate concrete workflows as described in [Feature]: Workflow Orchestration #1943

Right now, my daily work driver platform/IDE is Conductor, which has all of the features above, but none of the fine-grained Agents/Skills/Project Management features from Multica, which I badly want.

If/when you add these workspace visibility features to Multica, my team and I will be ready to make the switch.

[Bohan-J]

Great one, noted! I also used Conductor to coding before building Multica. control and visibility over the code and workspace is defenitely the key point.

[alexgrozav]

Great to hear that! I actually came across Multica when I was researching the idea of building an orchestration platform like this, because Conductor is great, but it's lacking the fine grained controls and project overview.

Do you have plans to take Multica in this direction? I'd love to contribute.

[guilhermesilveira]

Binding an agent to a specific directory is limiting and the "old way" of doing things.
Think Codex and Claude desktop clients. Both used to work on a specific folder. Then working tree support came so that multiple tasks can be executed without interfering one in the other. They still support non-working tree, folder based. But removing working tree support is going backwards, limiting what we can do today. So as far as I understand, removing working tree support is the wrong move.

That being said, agent attached to a specific folder is not a feature that requires (deterministic) code implementation. Today, an agent has access to the entire machine. It is just that its current working directory is related to the one of the working tree. That can easily be overriden by the agent by setting its description to "Dont use the working tree, use the folder XPTO."
It will still create and GC working trees, but those who are asking for a more limiting feature can use that today.
"But the agent will have access to the entire machine and might play around with other folders" => it already does, nothing new here.
Of course, it can be a checkbox on the agent config "fix it to a specific folder instead of using working trees". Not hard to implement, optional, default false (it is a limiting feature, not one that opens possibilities).

---

THe last point related to working trees is that working trees can be pooled. Pooled working trees for multiple repos makes "checking out" faster, tasks running in multiple working trees consume less hard disk space etc. It is another power up on top of working trees.

[MatzeJoerling]

I think this discussion is very relevant for more persistent multi-agent setups.

Right now Multica is heavily focused on the "workspace per run" model where every task gets its own generated worktree and runtime bootstrap files like AGENTS.md.

That works fine for stateless task execution or Claude Code style workflows, but it becomes problematic once agents are treated as long-lived identities instead of disposable runners.

My setup is closer to an "agent OS" model:

• every agent has its own Linux user
• persistent home directory
• persistent MCP configuration
• persistent memory/cache/tooling
• own SSH keys / credentials
• own Git repos and shell environment
• dedicated model/runtime combinations

Example:

• communication agent
• research/documentation agent
• coding agent
• infrastructure automation agent

The problem is that some specialized runtimes like OpenCode or Hermes do not work well with dynamically generated workspaces because they expect a stable environment and persistent bootstrap/config locations.

In practice this means:

• runtime-generated AGENTS.md conflicts with existing agent configs
• MCP/tool configuration becomes fragmented
• persistent memory and caches break
• relative paths and repo assumptions fail
• agents lose their "identity" between runs

What I would really like to see is an optional persistent-agent mode where Multica does not create and manage a temporary workspace for every execution but instead attaches the task to a pre-existing agent workspace/home.

Then Multica would mainly handle:

• orchestration
• routing
• task assignment
• presence/state
• coordination

while the agent runtime itself owns the environment.

I think this would make Multica much more attractive for advanced self-hosted and MCP-heavy setups where agents are treated more like persistent digital workers than ephemeral CI jobs.