Run in an Isolated Worktree

Run a single praisonai run in a fresh git worktree/branch so agent output never touches your working tree

praisonai run --worktree runs an agent on a fresh git branch and worktree, then commits, keeps, or discards the result — your working tree is never touched.

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

That single command provisions a fresh worktree on a new branch, runs the agent there, commits every change (tracked and untracked) to the isolated branch, and prints how to merge it back.

Quick Start

1. Run a prompt in isolation

   The agent edits a fresh branch — your working tree stays clean.

   praisonai run "Refactor the auth module" --worktree
   
2. Run a YAML file in isolation

   The YAML file is resolved to an absolute path before isolation, so an untracked or git-ignored agents.yaml still loads.

   praisonai run agents.yaml --worktree
   
3. Keep the worktree for review

   Both the worktree checkout and the branch stay in place after the run so you can inspect the files directly.

   praisonai run "Draft a migration plan" --worktree --keep
   

---

How It Works

--worktree provisions a per-run branch and directory, chdirs into it for the run, then decides what to keep based on whether the agent produced changes.

Step	What happens
Probe	GitWorktreeAdapter.available checks the cwd is a git repo with git on PATH.
Provision	A fresh worktree is created at .praisonai/worktrees/<slug> on branch praisonai/<slug>.
Unique per run	A short random token is appended (<target>-<token>) so repeated or concurrent runs never share a worktree.
Run	The CLI chdirs into the worktree for the duration of the run.
Teardown	A git status --porcelain snapshot decides: commit-and-retain, prune, or keep.

The worktree is named after the run target plus a random token, then hashed into a git-ref-safe slug. Two runs of the same prompt or YAML file never clobber each other’s uncommitted changes.

---

Teardown Matrix

What survives after the run depends on whether the agent changed anything and whether you passed --keep.

Situation	What happens	User-visible message
Not a git repo	No-op, run continues normally	Not a git repository; running without worktree isolation.
Run made no changes	Worktree and branch removed	No changes on '<branch>'.
Run made changes	Commit praisonai run: <target>, retain branch, prune worktree checkout	Committed changes to branch '<branch>'. Review/merge with: git merge <branch>
Commit fails (e.g. no git identity)	Worktree kept in place so output is never lost	Could not commit isolated changes; worktree kept at <path> (branch '<branch>') for manual review.
--keep	Both worktree and branch retained	Worktree kept at <path> (branch '<branch>'). Review/merge then remove with: git worktree remove.

Untracked new files are committed too. Teardown uses git status --porcelain (not git diff), so brand-new files the agent creates are always captured on the branch before the checkout is pruned.

---

What Gets Rejected

--worktree is scoped to direct prompt and YAML file runs. These combinations fail fast with exit code 1.

Combination	Message	Reason
--worktree --attach	--worktree cannot be combined with --attach	The warm runtime is a separate process whose cwd can’t be redirected into the worktree.
--keep without --worktree	--keep requires --worktree	--keep is only meaningful with isolation.
--worktree with --agent / --command / --profile / --profile-deep	--worktree is only supported for direct prompt and YAML file runs	Scoped intentionally to keep the feature focused.

---

CI / JSON Mode

Under --output json, the isolation status messages are suppressed but isolation still happens.

praisonai run "Generate a changelog" --worktree --output json

The agent runs on the isolated branch exactly as before; only the informational prints (Isolated run on branch ..., Committed changes ...) are silenced so your JSON payload stays clean.

---

Best Practices

Use --worktree for risky or exploratory edits

Isolation means a bad run never dirties your working tree. Run the agent, inspect the branch, then git merge only if you like the result.

Add --keep when you want to inspect files, not just the diff

Without --keep, changed runs commit and prune the checkout — you review via git merge <branch>. With --keep, the checkout stays on disk under .praisonai/worktrees/ so you can open the files directly.

Configure a git identity so commits succeed

On teardown, changes are committed with git commit --no-verify. If no user.name / user.email is set, the commit fails and the worktree is kept in place for manual review instead. Set a git identity to get the clean commit-and-merge path.

Clean up kept worktrees when you're done

--keep and commit-failure paths leave a worktree on disk. Remove it with git worktree remove <path> once you’ve reviewed or merged the branch.

---

Related

Workspace Isolation

The SDK GitWorktreeAdapter this CLI flag wraps.

Kanban Worktree Isolation

Per-task git worktrees for kanban workers.

Run Command

Full praisonai run CLI reference.