Workspace Isolation

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.

Three surfaces, one primitive:

CLI — praisonai run --worktree (Isolated Runs) for one-off human-driven runs.
Kanban tasks — workspace_kind="worktree" (Per-Task Worktree Isolation) for dispatched workers.
Library API — GitWorktreeAdapter (this page) for programmatic isolation.

This page covers the general-purpose GitWorktreeAdapter in praisonaiagents.workspace (used programmatically) and the praisonai run --worktree CLI wrapper that provisions one per run. Kanban tasks have their own built-in worktree isolation — set workspace_kind="worktree" on the task instead. See Kanban → Per-Task Worktree Isolation.

Using it from the CLI

You don’t need to touch the adapter API — the praisonai run command has a built-in --worktree flag that wires the adapter into your normal run.

praisonai run "Rework the retry loop" --worktree

The agent runs on a fresh branch; your working tree stays clean. Any output is auto-committed to the branch for review, or the branch is pruned if nothing changed.

Isolated Runs (CLI)

praisonai run --worktree / --keep — per-run isolation from the terminal.

From the CLI

Run any agent on a fresh, disposable branch — no code required.

# Run any agent on a fresh, disposable branch
praisonai run "refactor auth" --worktree

# Keep the branch checkout in place for review
praisonai run "refactor auth" --worktree --keep

The agent edits inside an isolated praisonai/<task>-<hash> worktree; on teardown its changes are auto-committed to that branch for review, or the worktree is kept in place with --keep. See praisonai run --worktree for the full behaviour.

Quick Start

Isolate a run from the CLI

Add --worktree to any run invocation — the agent works on a fresh branch instead of your working tree.

praisonai run "refactor auth to use bcrypt" --worktree
# > Isolated run on branch 'praisonai/refactor-auth-<uid>' (./.praisonai/worktrees/refactor-auth-<uid>)
# ... agent runs ...
# > Committed changes to branch 'praisonai/refactor-auth-<uid>'.
# > Review/merge with: git merge praisonai/refactor-auth-<uid>

Keep the worktree in place for in-place review with --keep:

praisonai run agents.yaml --worktree --keep

No-op outside a git repo, so it’s always safe to pass. See praisonai run --worktree.

Concurrent Agents With Isolation (Python)

Give each agent its own git worktree — edits stay independent.

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-<hash>
bob_dir = workspace.create("bob")      # -> ./.praisonai/worktrees/bob-<hash>

Default, Reset, or Remove

Opt out of isolation with NoIsolationAdapter, or reset and tear down worktrees when a run ends.

from praisonaiagents.workspace import NoIsolationAdapter

workspace = NoIsolationAdapter()
workspace.create("alice")  # -> current working directory

Reset or Remove

Restore a worktree to a clean state, or tear it down when the run ends.

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.

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.

CLI Usage

praisonai run --worktree wraps the adapter so a single command runs the agent on a fresh branch — no Python glue required.

praisonai run "refactor auth to use bcrypt" --worktree

The run detects changes with git status --porcelain, so brand-new (untracked) files are never lost.

Situation	Worktree checkout	Branch	Reported
No changes	Removed	Removed	`No changes on '<branch>'.`
Any change (tracked or untracked)	Pruned	Retained with auto-commit	`Committed changes to branch '<branch>'. Review/merge with: git merge <branch>`
`--keep`	Retained	Retained	`Worktree kept at <path> (branch '<branch>'). Review/merge then remove with: git worktree remove.`
Cwd is not a git repo	n/a (no-op)	n/a	Warning: `Not a git repository; running without worktree isolation.`

--worktree never destroys the agent’s output. On any change the branch is committed and retained even without --keep — only the worktree checkout is pruned.

A short random 8-char token is appended to every branch/worktree name, so two runs of the same target never collide — run praisonai run "..." --worktree twice in parallel and each gets its own branch and directory.

--worktree works with a direct prompt or a YAML file. It cannot be combined with --attach, --agent, --command, --profile, or --profile-deep, and --keep requires --worktree. See the run CLI reference for the full options table and compatibility matrix.

Choosing an Adapter

Both adapters share the same interface, so you can swap them without changing your code. 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.

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.

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.

first = workspace.create("alice")
second = workspace.create("alice")
assert first == second  # same worktree reused, no duplicate created

Clean up when the run finishes.

workspace.create("alice")
# ... agent does its work ...
workspace.remove("alice")  # removes worktree and branch

CLI usage

The same isolation primitive is available directly on the CLI — pass --worktree to praisonai run and every invocation gets its own branch. Pass --keep to retain the worktree checkout after the run for review. See Per-run worktree isolation for the full flag reference and behaviour matrix.

praisonai run "refactor auth.py" --worktree
praisonai run agents.yaml --worktree --keep

Best Practices

Reach for --worktree before the Python API

For a one-off isolated agent run there is nothing to install and no Python glue — just append --worktree. The programmatic GitWorktreeAdapter is only needed when you’re orchestrating multiple agents from your own code.

Use --keep when you want to inspect in place

Without --keep, the worktree checkout is pruned after each run (the branch is preserved). With --keep, both the checkout and the branch stay so you can cd into the isolated directory and inspect changes in place.

Merge or squash the auto-commit

The isolated run auto-commits everything (tracked + untracked) with the message praisonai run: <target>, so merge or cherry-pick with a plain git merge praisonai/<name>-<uid>. To collapse into a single commit, use git merge --squash.

Use GitWorktreeAdapter unconditionally

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.

Name worktrees by agent or run, not by task

Names are hashed into collision-resistant slugs, so "agent one" and "agent-one" never share a worktree. Stable names keep create idempotent across retries.

Clean up with remove() when the run ends

Each worktree lives under .praisonai/worktrees/. Call remove() on completion to stop that directory from growing over long-running sessions.

Requires git ≥ 2.5

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.

Also available on the CLI

Run a single praisonai run invocation on a fresh worktree/branch with the --worktree flag — no Python needed. It commits the run’s output to the branch on exit (or keep it in place with --keep).

praisonai run --worktree "Refactor the auth module and add tests"

See Isolated Runs (Git Worktree) for the full flag reference and teardown behaviour.

Run CLI

praisonai run --worktree / --keep — the CLI wrapper and its full options table.

Multi-Agent Context Safety

Isolate per-agent runtime and resolver state — the context half of concurrency.

Code & Workspace Access

Contain file operations to a workspace with read/write access controls.

Kanban Worktree Isolation

Per-task git worktrees for kanban workers — set workspace_kind="worktree".

praisonai run --worktree

Run any agent on an isolated branch from the CLI — no code required.

Run --worktree

The praisonai run --worktree one-liner that wraps this adapter from the CLI.

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Workspace Isolation

Using it from the CLI

Isolated Runs (CLI)

From the CLI

Quick Start

How It Works

CLI Usage

Choosing an Adapter

Configuration Options

Common Patterns

CLI usage

Best Practices

Also available on the CLI

Run CLI

Multi-Agent Context Safety

Code & Workspace Access

Kanban Worktree Isolation

praisonai run --worktree

Run --worktree

​Using it from the CLI

Isolated Runs (CLI)

​From the CLI

​Quick Start

​How It Works

​CLI Usage

​Choosing an Adapter

​Configuration Options

​Common Patterns

​CLI usage

​Best Practices

​Also available on the CLI

​Related

Run CLI

Multi-Agent Context Safety

Code & Workspace Access

Kanban Worktree Isolation

praisonai run --worktree

Run --worktree

Using it from the CLI

From the CLI

Quick Start

How It Works

CLI Usage

Choosing an Adapter

Configuration Options

Common Patterns

CLI usage

Best Practices

Also available on the CLI

Related