# How the AIOX Worktree Manager Provides Branch Isolation in Epic 1

> Discover how AIOX Worktree Manager ensures branch isolation for concurrent development with dedicated Git worktrees and uniquely prefixed branches. Streamline your workflow today.

- Repository: [SynkraAI/aiox-core](https://github.com/synkraai/aiox-core)
- Tags: internals
- Published: 2026-03-15

---

**The AIOX Worktree Manager guarantees branch isolation by automatically provisioning dedicated Git worktrees and uniquely prefixed branches (`auto-claude/<storyId>`) for every story, ensuring complete separation from the main repository and concurrent development streams.**

The **SynkraAI/aiox-core** repository implements **Epic 1** through the Worktree Manager, a specialized component that solves concurrent development conflicts by binding each story to its own isolated Git branch and working directory. This architecture prevents cross-contamination between stories while maintaining a clean main branch history.

## Core Branch Isolation Mechanisms

### Per-Story Branch Naming with Configurable Prefixes

In [`.aiox-core/infrastructure/scripts/worktree-manager.js`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/infrastructure/scripts/worktree-manager.js), the `getBranchName(storyId)` function (lines 13-15) constructs isolated branch identifiers by concatenating the configurable `branchPrefix` (defaulting to `auto-claude/`) with the story identifier. This naming convention ensures that every story operates on a distinct branch namespace, physically separating commits from the main branch and other stories.

### Isolated Worktree Creation

The `create(storyId)` method (lines 24-48) enforces isolation at the filesystem level. It first validates against the `maxWorktrees` limit to prevent resource exhaustion, then executes:

```bash
git worktree add <repo>/.aiox/worktrees/<storyId> -b auto-claude/<storyId>

```

This command simultaneously creates a new working directory under `.aiox/worktrees/<storyId>` and a fresh branch with the prefixed name, establishing a sandboxed environment where changes remain invisible to the main repository.

### Filtered Worktree Discovery

Isolation requires that the manager only recognizes its own worktrees. The `list()` method (lines 16-20) parses `git worktree list --porcelain` output and filters entries to return only those branches starting with the configured `branchPrefix`. This prevents the manager from interfering with manually created worktrees or branches outside the AIOX ecosystem.

### Complete Cleanup of Branches and Worktrees

The `remove(storyId)` implementation (lines 63-84) terminates isolation cleanly by executing `git worktree remove` followed by `git branch -d` (or `-D` when forced). This dual deletion ensures that neither the working directory nor the isolated branch persists after story completion, preventing branch clutter and repository bloat.

## Configuration and Resource Limits

The Worktree Manager preserves isolation integrity through configurable guards defined in the options (lines 18-22). The `maxWorktrees` setting caps concurrent isolated environments, while `staleDays` identifies inactive worktrees for automatic cleanup via `cleanupStale()` (lines 34-55). These limits prevent resource exhaustion while maintaining strict separation for active stories.

## Practical Implementation Examples

### Creating an Isolated Story Worktree

```javascript
const WorktreeManager = require('.aiox-core/infrastructure/scripts/worktree-manager');

async function startStory(storyId) {
  const manager = new WorktreeManager(process.cwd());
  await manager.create(storyId);  // Creates .aiox/worktrees/STORY-42
  console.log(`Isolated worktree for ${storyId} ready`);
}

startStory('STORY-42');

```

This invocation triggers the branch isolation protocol, creating both the directory `.aiox/worktrees/STORY-42` and the branch `auto-claude/STORY-42` automatically.

### Listing Isolated Worktrees Only

```javascript
async function showIsolatedWorktrees() {
  const mgr = new WorktreeManager('.');
  const list = await mgr.list();  // Filters to branchPrefix 'auto-claude/'
  console.log(mgr.formatList(list));
}

showIsolatedWorktrees();

```

The output displays only manager-owned worktrees, confirming isolation boundaries:

```text
📁 Active Worktrees (2/10)
──────────────────────────────────────────────────
🟡 STORY-42   │ auto-claude/STORY-42 │ clean          │ 1h ago
🟢 STORY-99   │ auto-claude/STORY-99 │ 3 uncommitted │ 5m ago

```

### Merging and Cleaning Up Isolated Branches

```javascript
async function finalizeStory(storyId) {
  const mgr = new WorktreeManager('.');
  const result = await mgr.mergeToBase(storyId, { cleanup: true });
  console.log(result.success ? 'Merge succeeded' : 'Merge failed');
}

finalizeStory('STORY-42');

```

The `mergeToBase()` method integrates the isolated branch back into the base branch and, with `cleanup: true`, invokes `remove()` to eliminate both the worktree and the `auto-claude/STORY-42` branch, completing the isolation lifecycle.

## Related Components

Branch isolation extends beyond the core manager into supporting infrastructure:

- **[`.aiox-core/infrastructure/scripts/story-worktree-hooks.js`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/infrastructure/scripts/story-worktree-hooks.js)**: Lazy-loads the Worktree Manager during story lifecycle events to maintain isolation boundaries during automated transitions.
- **[`.aiox-core/infrastructure/scripts/project-status-loader.js`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/infrastructure/scripts/project-status-loader.js)**: Consumes the filtered `list()` output to render isolation status in UI dashboards without exposing non-AIOX worktrees.
- **[`tests/infrastructure/worktree-manager.test.js`](https://github.com/SynkraAI/aiox-core/blob/main/tests/infrastructure/worktree-manager.test.js)**: Validates that branch prefixes are respected and isolation holds across concurrent operations.

## Summary

- **The AIOX Worktree Manager binds every story to a unique branch** using the `auto-claude/<storyId>` naming convention implemented in `getBranchName()`.
- **Physical isolation occurs through `git worktree add`** with the `-b` flag, creating dedicated directories under `.aiox/worktrees/` that mirror isolated branch states.
- **The manager maintains separation boundaries** by filtering `git worktree list` results to only recognize branches matching the configurable prefix.
- **Complete isolation teardown** via `remove()` deletes both the working directory and the associated branch, ensuring no residual artifacts remain.
- **Resource guards** (`maxWorktrees`, `staleDays`) preserve isolation quality by preventing system overload while automatically retiring inactive environments.

## Frequently Asked Questions

### How does the Worktree Manager prevent branch name collisions between stories?

The manager eliminates collisions through the `getBranchName()` function in [`.aiox-core/infrastructure/scripts/worktree-manager.js`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/infrastructure/scripts/worktree-manager.js) (lines 13-15), which prefixes every branch with `auto-claude/` followed by the unique story identifier. This namespace guarantees that `auto-claude/STORY-42` and `auto-claude/STORY-99` remain distinct, preventing cross-story interference.

### Can the Worktree Manager interfere with manually created Git worktrees?

No. The `list()` method (lines 16-20) explicitly filters the output of `git worktree list --porcelain` to return only worktrees whose branches start with the configured `branchPrefix`. This ensures the manager only manipulates AIOX-generated worktrees, leaving manually created worktrees and branches completely untouched.

### What happens to the isolated branch after a story is merged?

When `mergeToBase()` is called with `cleanup: true`, or when `remove()` is invoked directly (lines 63-84), the manager executes `git worktree remove` to delete the directory followed by `git branch -d` (or `-D` for forced deletion) to eliminate the `auto-claude/<storyId>` branch. This ensures complete cleanup of the isolated environment.

### How does AIOX limit resource consumption while maintaining branch isolation?

The Worktree Manager implements configurable guards defined in the constructor options (lines 18-22). The `maxWorktrees` parameter caps the number of concurrent isolated environments, while `staleDays` triggers automatic cleanup via `cleanupStale()` (lines 34-55) to remove inactive worktrees and their branches, preventing repository bloat without compromising active story isolation.