DEV Community: Juan Saez

Worktree lifecycle for AI agents

Juan Saez — Thu, 15 Oct 2026 20:50:25 +0000

The problem is not creating worktrees, but managing them

When two or more agents work in parallel on different features, a problem
appears that Git does not solve by itself: how to manage changes so the agents
do not interfere with one another.

One possible strategy is agent-to-agent communication. Agents can delegate
tasks, transfer context, declare ownership, and perform handoffs. This helps
coordinate intent and dependencies, but it is not physical isolation. If one
agent has to wait for another agent's response, contract, or commit before it
can continue, the supposed parallelism can become a sequence of coordinated
steps.

Claude Code's documentation makes this distinction explicit: agent teams can
communicate and share tasks, while worktrees are used when changes to files
need to be isolated.

Worktrees complement that strategy. Each agent works in its own working tree
and can modify files without directly overwriting another agent's checkout.
This reduces interference during editing, but it does not eliminate semantic
conflicts: two agents can still design incompatible changes or depend on
different interfaces.

Communication does not disappear either. It may still be necessary to
coordinate a contract, a commit, a merge, or a later integration.

That raises another question: what happens after a worktree is created, and
how is its lifecycle managed?

An isolated worktree has no lifecycle by itself

Git provides worktrees, but it does not define how their entire lifecycle
should be managed.

A first management layer can be found in the
obra/superpowers/using-git-worktrees
skill. It detects whether the agent is already inside a worktree, distinguishes
a submodule from a worktree, selects a location, verifies that the directory
is ignored, creates the worktree, prepares dependencies, and runs a test
baseline.

That flow solves provisioning and initial setup. Operational questions still
remain: how is the work integrated? What happens when a merge fails? How do we
avoid removing a branch with an unexpected state? What happens if the process
dies during shutdown? How are local changes in the destination recovered?

That is the space worktree.sh attempts to cover: not replacing Git's
worktree creation, but adding a lifecycle layer for agents that create, use,
integrate, and abandon work environments in an automated way.

`worktree.sh`: a lifecycle for worktrees

worktree.sh is a tool for managing the lifecycle of worktrees. Its
parent-only interface includes these operations:

create: creates and validates the worktree and its working branch.
complete: verifies the state, performs the squash merge, and removes resources when the closing conditions are met.
cleanup: removes the worktree without integrating it; destructive discard requires --discard.
recover: resumes pending preserve-dirty transactions.
prune: cleans up Git's worktree records and reports unassociated directories.
list: shows the worktrees registered by Git.

The tool also adds ID validation, base-branch selection, predictable paths and
branches, locks for incompatible operations, and journals that record closing
phases.

An agent's workflow

The workflow starts when the agent receives a work-id. From that ID,
worktree.sh creates a separate branch and working tree from the detected base
branch or from the branch provided explicitly.

work request
    ↓
create worktree
    ↓
agent modifies isolated files
    ↓
prepare / verify, when configured
    ↓
complete or cleanup

A minimal way to start work is:

.flowtask/scripts/worktree.sh create hotfix/test-001 --base main

The agent works inside the worktree without directly modifying the shared
checkout. When it finishes, it can run configured validations and close the
work with:

.flowtask/scripts/worktree.sh complete hotfix/test-001 --base main

complete verifies the worktree's identity and state, integrates commits with
a squash merge, and only then removes the branch and worktree when the closing
validations succeed.

If the work must be abandoned without integration, the workflow uses
cleanup:

.flowtask/scripts/worktree.sh cleanup hotfix/test-001

Forced discard requires explicit authorization through --discard.

There is also a more delicate case: the destination may contain local changes
that should not become commits yet. With --preserve-dirty, the tool captures
eligible tracked and untracked changes, temporarily cleans the destination,
performs the squash merge, and then attempts to restore those changes.

Ignored files are not part of that preservation. If restoration encounters a
conflict, the transaction becomes pending_manual: the backup is preserved and
resolution requires human intervention. In that case, recover can resume the
transaction, but it does not resolve the conflict automatically.

What happens when something fails

The lifecycle must also define what happens if a process dies during a merge,
the worktree changes, or restoration finds a different state.

For that purpose, worktree.sh records closing phases in journals. A journal
identifies which steps have been confirmed and from where an operation can be
resumed. It is not merely an informational log: it is part of the state the
tool uses to decide whether it can continue or must stop.

For example, if complete attempts a squash merge and encounters a conflict,
the closing operation stops and preserves the worktree and branch. The tool
does not remove resources that may be needed to investigate or resolve the
conflict.

In a --preserve-dirty transaction, if the process dies after capturing the
destination changes but before restoring them, recover can resume the flow
from the recorded state.

If restoration encounters a conflict, the transaction enters pending_manual,
keeps the backup, and requires human intervention. recover can continue the
reconciliation after the state is corrected, but it does not decide how to
resolve the conflict.

This behavior is deliberate: when the state cannot be verified, the tool
prefers to stop and preserve resources rather than perform an irreversible
action.

The tool's current state

The current manager has a parent-only flow—the main repository creates and
closes its own worktrees—and a submodule flow.

Submodule initialization is explicit: it does not run by default when an agent
creates a worktree. This avoids populating dependencies the agent does not
need.

To act directly on a submodule, target-direct treats the submodule as the
target repository. The flow validates its relationship with the parent
repository, the path, the gitlink (the parent's reference to the submodule
commit), and branch identity.

link-parent is also available for controlled gitlink updates, with the
staged-only mode modifying only the index; it does not commit, merge, or push
the parent.

The tool does not yet expose an MCP interface or subtree integration. Evolution
toward MCP is already included in the project roadmap.

Project evolution

The manager's roadmap is organized into these stages:

1. Stabilize the standalone CLI
        ↓
2. Migrate the backend to Python
        ↓
3. Keep worktree.sh as a compatibility shim
        ↓
4. Expose the backend through MCP

The main direction is to separate the manager's core, preserve its guarantees
during the migration, and later provide an interface suitable for agents and
other orchestrators.

The code and the manager's evolution are available in the
worktree-manager repository.

Why Your Multi-Turn AI Agents Lose Their Train of Thought (And How to Fix It)

Juan Saez — Wed, 10 Jun 2026 15:36:09 +0000

1. The Agent That Forgot Everything

I have an agent that clarifies requirements. I give it a problem, it asks questions, I answer, it refines, and after three or four rounds it should have a spec ready. Simple.

Round one works fine. It asks reasonable questions. I answer. But when I ask it to continue — same session, same agent, next step in the pipeline — the clarifier starts from scratch. It repeats questions I already answered. It ignores constraints we already agreed on. Sometimes it contradicts its own analysis from five minutes ago.

This isn't an LLM bug. It's an architecture problem. Claude Code, OpenCode, and pretty much any coding agent that delegates work to subagents shares the same behavior: every invocation of a subagent — even the same one, to continue a conversation — creates a brand new session. No history. No context. No memory of what that subagent already thought, asked, or decided.

The good news: the infrastructure to fix this already exists in these tools. It's just that nobody uses it by default.

2. How Coding Agents Delegate

The pattern is the same everywhere. A main agent receives your prompt, reasons about it, and when it needs specialized help, it calls a delegation tool — typically named task().

// OpenCode — tool/task.ts, lines 144-155
const session = taskID
  ? yield* sessions.get(SessionID.make(taskID))
      .pipe(Effect.catchCause(() => Effect.succeed(undefined)))
  : undefined

const nextSession =
  session ??                    // If it exists, reuse it
  (yield* sessions.create({     // Otherwise, create a new one
    parentID: ctx.sessionID,
    title: "params.description + ` (@${next.name} subagent)`,"
    permission: [...],
  }))

Here's the flow: the LLM decides to call task(), the system looks up the subagent definition (permissions, model, system prompt), creates a new session with parentID pointing to the main session, and kicks off an independent LLM loop. The subagent does its work, returns the result, and the main agent continues.

Claude Code exposes resume: sessionId in its SDK for exactly this — the same pattern: pass the session ID and the agent resumes with full history; omit it and a new session is created. OpenCode has the task_id parameter that lets you resume an existing session, but if you don't explicitly pass it, the system creates a new session. And since the main agent — the one calling task() — has no way of knowing which task_id it used last time, the default wins every time.

The subagent gets called, works, finishes. The next time you need it — even if it's the exact same agent to continue the exact same conversation — it's born with no past.

3. What Actually Happens to the Session

Here's what I found when I dug into OpenCode's source code: the infrastructure already persists everything. The problem isn't technical — it's a design choice.

Finding 1: Sessions store EVERYTHING.

OpenCode persists sessions in SQLite. Every message, every tool call, every output, every step of reasoning gets recorded:

SessionTable         MessageTable          PartTable
────────────         ────────────          ─────────
id (PK)              id (PK)               id (PK)
parent_id (FK→self)  session_id (FK)       message_id (FK)
title                data (JSON)           session_id (FK)
agent                                      data (JSON)
time_created                               ↑ text | tool | reasoning
time_updated                               ↑ snapshots | patches

When a subagent executes 15 tool calls, analyzes 8 files, and produces a 500-word response — all of it lands on disk. And it stays there.

Finding 2: Subagents can't delete their sessions.

Subagents' default permissions don't include task or todowrite. There is no end_session, close, terminate, or anything similar. A subagent cannot — by accident or by design — destroy its own session.

Finding 3: The LLM loop exits — it doesn't destroy.

When the subagent finishes responding, the main loop checks an exit condition:

// OpenCode — prompt.ts, lines 1267-1274
if (
  lastAssistant?.finish &&
  !["tool-calls"].includes(lastAssistant.finish) &&
  !hasToolCalls &&
  lastUser.id < lastAssistant.id
) {
  break  // ← Exits the loop. Nothing else.
}

That break doesn't call sessions.remove(). It doesn't archive the session. It doesn't touch a single field in the database. The in-memory runner cleans itself up, but in SQLite the session sits there intact, with all its messages.

Finding 4: No TTL, no timeout, no automatic cleanup.

I searched for ttl, expir, timeout.*session, auto.*delete across the entire codebase. Zero results for sessions. Sessions live until someone deletes them manually. They don't expire.

The irony: the infrastructure already does exactly what we need. It persists context. It keeps the history. It destroys nothing. You just need to ask it to reuse a session. And all it takes is passing the right task_id.

4. The Handshake: 200 Lines That Change Everything

The problem isn't one of capability — it's one of indexing. OpenCode can persist sessions and resume them if you pass a task_id. What it can't do is answer questions like:

"Give me the session for spec-42's clarifier"
"Has spec-42's constructor finished?"
"Resume the conversation with the planner where we left off"

To OpenCode, a session is ses_1d6f79327ffe7JM4ZcELwlMV0D. It doesn't know what "spec-42" is, which agent ran in that session, or which step of the workflow you're on. That's domain knowledge.

The handshake is the layer that translates domain knowledge into session references. Three functions:

Discovery: given a spec ID, find the right session's task_id
Naming: instead of ses_1d6f79327ffe, you see Kael-planner, Aitana-validator
Orchestration state: is the planner running? Did the validator approve?

The analogy is DNS. A web server can serve content if you give it the right IP. DNS translates github.com to 140.82.121.3. The handshake translates spec-42 → constructor to ses_1d6e78035ffe. It doesn't replace persistence. It complements it.

In practice, two scenarios:

Scenario A — New: No task_id exists for this agent. Call task() normally. Capture the task_id from the response. Persist it in a map: "spec-42/constructor" → "ses_1d6e78035ffe".

Scenario B — Resume: A task_id already exists. Retrieve it from the map. Call task() with that task_id. OpenCode loads the full session. The agent doesn't "remember" by magic — it sees its entire history.

The result: a 5-agent pipeline (clarifier → planner → auditor → constructor → validator) where each agent can resume with full context. Seven iterations on the same spec without losing a single reference.

5. Three Benefits You Didn't Expect

The obvious benefit is that the agent stops repeating questions. But there are three more that only show up in production.

Fewer tokens, lower latency. When an agent resumes its session, it doesn't need to re-run grep to find the relevant files, re-read documentation it already read, or re-analyze code it already understood. All of that is in the tool call history. Every tool call not re-executed is tokens saved and seconds the user doesn't wait for.

Real iterative refinement. A clarifier that goes through three rounds of questions sharpens its understanding each time. Without session continuity, round three is just as generic as round one — the agent doesn't know what it already asked or what you already answered. With it, each iteration builds on the last.

Auditability. When something goes wrong, the session history shows you exactly what the agent did, which tools it used, and why. Without continuity, that record fragments into orphaned sessions. With the handshake, you have a traceable reasoning chain end to end.

6. This Isn't New — The Industry Already Does It

What's interesting isn't that it works. It's that the industry already solved this problem with the same pattern — just with more infrastructure.

LangGraph implements checkpoints with thread_id + checkpointer. The thread_id is the direct equivalent of our task_id. The difference is that LangGraph needs you to configure SqliteSaver or PostgresSaver — FlowTask uses OpenCode's SQLite, which was already there. [docs]

Temporal runs workflows with durable execution: when a worker crashes at step 5 of 10, another worker picks up the workflow, replays the event history from the beginning, skips already-completed activities, and resumes from the last checkpoint. OpenCode solves the same conceptual problem — use history to avoid repeating completed work — at the LLM context level. The difference: Temporal guarantees this against infrastructure failures with deterministic replay; OpenCode does it at the conversational context layer of the LLM. [docs]

Microsoft Agent Framework defines supersteps with checkpoint storage: each superstep captures the full state upon completion. Each agent in our pipeline is a superstep that persists its state when done. [docs]

The difference: FlowTask solves it with 200 lines of protocol. Your tool already has the rest.

7. Conclusion

Session continuity isn't an infrastructure problem — it's a design omission. The tools already persist all the context. All that's missing is the handshake that reuses it.

If your agents depend on multi-turn reasoning, don't accept the default of a fresh session every time.

The full pattern is implemented in FlowTask for reference.

The difference: FlowTask solves it with 200 lines of protocol. Your tool already has the rest.

7. Conclusion

Session continuity isn't an infrastructure problem — it's a design omission. The tools already persist all the context. All that's missing is the handshake that reuses it.

If your agents depend on multi-turn reasoning, don't accept the default of a fresh session every time.

The full pattern is implemented in FlowTask for reference.

DEV Community: Juan Saez

Worktree lifecycle for AI agents

The problem is not creating worktrees, but managing them

An isolated worktree has no lifecycle by itself

worktree.sh: a lifecycle for worktrees

An agent's workflow

What happens when something fails

The tool's current state

Project evolution

Why Your Multi-Turn AI Agents Lose Their Train of Thought (And How to Fix It)

1. The Agent That Forgot Everything

2. How Coding Agents Delegate

3. What Actually Happens to the Session

4. The Handshake: 200 Lines That Change Everything

5. Three Benefits You Didn't Expect

6. This Isn't New — The Industry Already Does It

7. Conclusion

7. Conclusion

`worktree.sh`: a lifecycle for worktrees