> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Workspace Isolation
> Give each agent its own git worktree so concurrent edits never clobber each other
Workspace isolation gives every agent its own working directory on its own branch, so agents editing the same repository never overwrite each other's changes.
This page covers the general-purpose `GitWorktreeAdapter` in `praisonaiagents.workspace`, which gives individual agents their own worktrees at the application layer. Kanban tasks have their **own** built-in worktree isolation — set `workspace_kind="worktree"` on the task instead. See [Kanban → Per-Task Worktree Isolation](/docs/features/kanban#per-task-worktree-isolation).
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Workspace Isolation"
Repo[📁 Repository] --> Alice[🤖 Alice Worktree]
Repo --> Bob[🤖 Bob Worktree]
Alice --> Merge[✅ Merge Back]
Bob --> Merge
end
classDef repo fill:#8B0000,stroke:#7C90A0,color:#fff
classDef tree fill:#189AB4,stroke:#7C90A0,color:#fff
classDef result fill:#10B981,stroke:#7C90A0,color:#fff
class Repo repo
class Alice,Bob tree
class Merge result
```
## Quick Start
Every run shares the same directory — the behaviour you already have.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.workspace import NoIsolationAdapter
workspace = NoIsolationAdapter()
workspace.create("alice") # -> current working directory
```
Give each agent its own git worktree — edits stay independent.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents.workspace import GitWorktreeAdapter
workspace = GitWorktreeAdapter()
alice = Agent(name="Alice", instructions="Edit README.md")
bob = Agent(name="Bob", instructions="Also edit README.md")
alice_dir = workspace.create("alice") # -> ./.praisonai/worktrees/alice-
bob_dir = workspace.create("bob") # -> ./.praisonai/worktrees/bob-
```
Restore a worktree to a clean state, or tear it down when the run ends.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
workspace.reset("alice") # git clean + checkout inside alice's worktree
workspace.remove("alice") # remove the worktree and its branch
```
***
## How It Works
`GitWorktreeAdapter` runs real `git worktree` commands to provision a fresh branch and directory per run.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant GitWorktreeAdapter
participant git
participant Worktree as Isolated Worktree
User->>Agent: Run task on repo
Agent->>GitWorktreeAdapter: create("alice")
GitWorktreeAdapter->>git: git worktree add -B praisonai/alice
git-->>Worktree: New branch + directory
Worktree-->>Agent: Isolated path
Agent-->>User: Edits stay contained
```
| Method | What it does |
| -------------- | ---------------------------------------------------------------------------------------- |
| `create(name)` | Provision the isolated directory and return its path (idempotent — reused if it exists). |
| `path(name)` | Return the directory path for `name` without creating it. |
| `reset(name)` | Restore tracked files and drop untracked files inside the worktree. |
| `remove(name)` | Tear down the worktree and delete its branch. |
When the directory is not a git repository, every method degrades gracefully — `create` and `path` return the original directory, and `reset` and `remove` do nothing.
***
## Choosing an Adapter
Both adapters share the same interface, so you can swap them without changing your code.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Start{Agents editing
the same repo
in parallel?} -->|Yes| Git[GitWorktreeAdapter]
Start -->|No| CwdCheck{Is cwd
a git repo?}
CwdCheck -->|Yes| Git
CwdCheck -->|No| NoIso[NoIsolationAdapter]
classDef question fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef git fill:#189AB4,stroke:#7C90A0,color:#fff
classDef none fill:#6366F1,stroke:#7C90A0,color:#fff
class Start,CwdCheck question
class Git git
class NoIso none
```
`GitWorktreeAdapter` is always safe — if the directory is not a git repo it falls back to `NoIsolationAdapter` behaviour automatically.
***
## Configuration Options
`GitWorktreeAdapter` accepts three options.
| Option | Type | Default | Description |
| --------------- | --------------------- | ----------------------------- | --------------------------------------------------------------------------------- |
| `root` | `str \| Path \| None` | `Path.cwd()` | Repository root to isolate. |
| `branch_prefix` | `str` | `"praisonai"` | Prefix for worktree branches — branches are named `{branch_prefix}/{slug(name)}`. |
| `worktrees_dir` | `str \| Path \| None` | `{root}/.praisonai/worktrees` | Directory where per-run worktrees are created. |
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.workspace import GitWorktreeAdapter
workspace = GitWorktreeAdapter(
root=".",
branch_prefix="team",
worktrees_dir=".worktrees",
)
if workspace.available:
workspace.create("alice")
```
The `available` attribute is `True` only when `root` is inside a git repository and `git` is on the PATH.
`NoIsolationAdapter` accepts a single `root` option (`str | Path | None`, default `Path.cwd()`) that it returns from `create` and `path`.
***
## Common Patterns
Give parallel sub-agents their own worktrees.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.workspace import GitWorktreeAdapter
workspace = GitWorktreeAdapter()
for name in ("researcher", "writer", "reviewer"):
workspace.create(name) # each gets an independent branch + directory
```
Reuse the same worktree for a named agent — `create` is idempotent.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
first = workspace.create("alice")
second = workspace.create("alice")
assert first == second # same worktree reused, no duplicate created
```
Clean up when the run finishes.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
workspace.create("alice")
# ... agent does its work ...
workspace.remove("alice") # removes worktree and branch
```
***
## Best Practices
It degrades gracefully outside git repos, so you can always reach for it. No need to detect git yourself — `available` reports the state and non-git directories simply fall back to shared behaviour.
Names are hashed into collision-resistant slugs, so `"agent one"` and `"agent-one"` never share a worktree. Stable names keep `create` idempotent across retries.
Each worktree lives under `.praisonai/worktrees/`. Call `remove()` on completion to stop that directory from growing over long-running sessions.
`git worktree` was introduced in git 2.5. On older git or non-git directories, isolation is unavailable and the adapter falls back to the shared directory.
***
## Related
Isolate per-agent runtime and resolver state — the context half of concurrency.
Contain file operations to a workspace with read/write access controls.
Per-task git worktrees for kanban workers — set `workspace_kind="worktree"`.