agentwt

Parallel coding agents. Isolated Git worktrees. One safe workflow.

A native Rust CLI that gives every coding task its own branch, worktree,
terminal, and supervised agent process—without disrupting your main checkout.

Install · Quick Start · Cheatsheet · Commands · Configuration · Safety

---

Tip

One repository, many agents, zero shared-workspace collisions. Start Codex or Claude on independent tasks while Git remains the source of truth for every branch and worktree.

⚡ Parallel by design	🛡️ Safe by default	🧩 Native integrations
Give every task an independent branch and sibling worktree.	Refuse dirty state, collisions, unsafe paths, and destructive cleanup unless explicitly authorized.	Automatic Codex/Claude detection, Windows Terminal, Konsole, custom terminals, and native process control.

agentwt start auth-refactor       # create an isolated worktree and launch an agent
agentwt start payment-tests       # run another task in parallel
agentwt list --status             # see every managed session
agentwt cleanup auth-refactor --yes

agentwt manages worktree creation, local session state, selected configuration migration, terminal launching, agent supervision, synchronization, and guarded cleanup. It never automatically commits, stashes, merges, pushes, resets, or force-pushes.

Command cheatsheet

_{Click the image to open the full-resolution version.}

Accessible text version

# Check and set up
agentwt doctor
agentwt init --global --yes

# Start a session (automatic preference: Codex, then Claude)
agentwt start <name>
agentwt start <name> --no-launch
agentwt start <name> --agent codex

# Manage sessions
agentwt list --status
agentwt open <name> --agent
agentwt stop <name>

# Sync safely
agentwt sync <name> --dry-run
agentwt sync <name>

# Finish and clean
agentwt cleanup <name> --dry-run
agentwt cleanup <name> --yes

# Review before exceptional operations
git status --short --ignored

Use --allow-dirty only after reviewing the dirty source. Use --force-unmerged only after confirming that deleting the unmerged branch is safe.

Contents

• Command cheatsheet
• Why agentwt
• Supported platforms
• Requirements
• Installation
• Quick start
• How sessions are laid out
• Common workflows
• Command reference
• Configuration
• Local configuration migration
• State and process management
• Safety guarantees
• Troubleshooting
• Known limitations
• Development and releases

Why agentwt

Running multiple coding agents in one checkout creates avoidable contention: agents modify the same files, share local secrets and editor state, and can interfere with each other's Git operations. agentwt gives each task a separate worktree without requiring a second full clone.

For a repository named payments and a session named auth-refactor, the defaults are:

parent-directory/
|-- payments/                         # main worktree
`-- .payments.agentwt/
    `-- auth-refactor/                # agent worktree

branch: agent/auth-refactor

The session directory is a sibling of the main repository, so it cannot accidentally be staged from the main worktree.

agentwt deliberately does not commit, stash, merge, push, reset, or force-push for you.

Supported platforms

Platform	Git	Automatic terminal	Process control
Windows 10/11 x86-64	Git for Windows	Windows Terminal (wt.exe)	Process groups, named pipe, Job Object
Linux x86-64	Standard Git	Konsole (konsole)	Unix process groups and signals

Native Windows operation does not route commands through WSL, PowerShell, or cmd.exe. WSL users can run the Linux binary entirely inside WSL, but a single invocation must not mix Windows and WSL paths.

Requirements

At runtime:

• Git must be available on PATH, unless supplied with the global --git option.
• The default terminal must be installed if automatic launching is used:
  • Windows Terminal on Windows.
  • Konsole on Linux.
• The selected agent executable must be installed or configured. Built-in adapters are provided for Claude (claude) and Codex (codex). Automatic selection prefers Codex when it is installed and falls back to Claude.

To build from source:

• Rust 1.85 or newer.
• A native Windows MSVC or Linux GNU build environment.

Installation

Install the single agentwt executable in a permanent folder that is included in your user PATH. Administrator/root access is not required when using the recommended locations below.

Important: Copy only the commands inside code blocks. Text such as PS C:\>, $, >, >>, or › is a terminal prompt and must not be copied as part of a command.

Obtain the executable

Use a release archive when one is available, or build from source.

Build from source with Rust 1.85 or newer:

git clone <repository-url>
cd agentwt
cargo build --release --locked

The compiled executable is:

• Windows: target\release\agentwt.exe
• Linux: target/release/agentwt

Release archives use these names:

agentwt-<version>-x86_64-pc-windows-msvc.zip
agentwt-<version>-x86_64-unknown-linux-gnu.tar.gz
SHA256SUMS

Windows installation for beginners

Open PowerShell or Windows Terminal normally. Administrator mode is not required.

Run each command below separately. If you built from source and PowerShell is open in the repository directory, set the source file with:

$AgentwtSourceFile = (Resolve-Path ".\target\release\agentwt.exe").Path

If you downloaded agentwt.exe, provide its actual downloaded location instead:

$AgentwtSourceFile = "$env:USERPROFILE\Downloads\agentwt.exe"

Confirm that Windows can find the source file:

Test-Path -LiteralPath $AgentwtSourceFile

This must print True. If it prints False, correct $AgentwtSourceFile before continuing.

Choose the permanent per-user installation folder:

$AgentwtInstallFolder = "$env:LOCALAPPDATA\Programs\agentwt"

Create the folder and copy the executable:

New-Item -ItemType Directory -Force -Path $AgentwtInstallFolder | Out-Null

Copy-Item -LiteralPath $AgentwtSourceFile -Destination "$AgentwtInstallFolder\agentwt.exe" -Force

Confirm the installed copy exists:

Test-Path -LiteralPath "$AgentwtInstallFolder\agentwt.exe"

This must also print True.

Add the installation folder to the permanent user PATH. These commands intentionally avoid a multiline if/elseif statement, so they can safely be pasted one at a time:

$AgentwtUserPath = [Environment]::GetEnvironmentVariable("Path", "User")

$AgentwtPathFolders = @($AgentwtUserPath -split ";" | Where-Object { $_ -and $_ -ne $AgentwtInstallFolder })

$AgentwtNewPath = (@($AgentwtPathFolders) + $AgentwtInstallFolder) -join ";"

[Environment]::SetEnvironmentVariable("Path", $AgentwtNewPath, "User")

The last command normally prints nothing. That is expected.

Make the command available in the PowerShell window that is already open:

$env:Path = "$AgentwtInstallFolder;$env:Path"

Verify the installation:

agentwt --version

Expected output:

agentwt 0.1.0

Also verify the help screen:

agentwt --help

Close PowerShell completely, open a new PowerShell window, and run agentwt --version again. If it still works, the permanent PATH installation is complete.

Windows installation troubleshooting

• › is not recognized: the › prompt character was copied. Run the command again without it.
• elseif is not recognized: parts of a multiline if/elseif statement were pasted separately. Use the four single-line PATH commands above instead.
• Test-Path prints False: $AgentwtSourceFile does not point to the downloaded or compiled executable.
• agentwt is not recognized: run $env:Path = "$AgentwtInstallFolder;$env:Path", or close and reopen PowerShell after saving the user PATH.
• Access denied: do not copy the executable into C:\Windows\System32. Use %LOCALAPPDATA%\Programs\agentwt, which belongs to the current user.

To see which executable Windows will run:

Get-Command agentwt

Linux installation for beginners

Open a terminal in the repository after building, or extract the downloaded Linux archive. Create a personal binary directory:

mkdir -p "$HOME/.local/bin"

Install the compiled binary:

install -m 755 target/release/agentwt "$HOME/.local/bin/agentwt"

If you downloaded a release, replace target/release/agentwt with the path to the extracted agentwt file.

Make it available in the current terminal:

export PATH="$HOME/.local/bin:$PATH"

Verify it:

agentwt --version
agentwt --help

To make the PATH change permanent, add this line to the startup file used by your shell, such as ~/.profile, ~/.bashrc, or ~/.zshrc:

export PATH="$HOME/.local/bin:$PATH"

Then close and reopen the terminal.

Verify a downloaded release

Compare downloaded files with SHA256SUMS before installation.

Windows PowerShell:

Get-FileHash .\agentwt-*.zip -Algorithm SHA256
Get-Content .\SHA256SUMS

Linux:

sha256sum --check SHA256SUMS

Optional global configuration

The executable works with built-in defaults immediately. To create one user configuration shared by all repositories, first change into any Git repository and run:

agentwt init --global --dry-run
agentwt init --global --yes

The generated configuration uses default_agent = "auto": Codex is selected when installed, with Claude as the fallback. init --global must be executed inside a Git repository because initialization also validates the repository and installed integrations.

Quick start

Run these commands from inside the Git repository you want to manage.

1. Inspect initialization

agentwt init --dry-run

This reports the repository, Git common directory, current platform, configured terminal, configured agents, and the configuration file it would create.

2. Create repository configuration

agentwt init --yes

This creates .agentwt.toml in the main worktree. To create user configuration instead, use:

agentwt init --global --yes

init --global still needs to be run from a Git repository because initialization also validates the current repository and integrations.

3. Start a session

agentwt start auth-refactor

This creates:

• Branch agent/auth-refactor from the current branch's committed HEAD.
• Worktree ../.<repository-name>.agentwt/auth-refactor.
• A managed session record.
• A new terminal window running the configured agent.

To create the worktree without opening a terminal:

agentwt start auth-refactor --no-launch

Forward arguments to the agent after --:

agentwt start auth-refactor -- --model opus --permission-mode plan

Every forwarded value remains a separate process argument. No shell command string is generated.

4. Inspect sessions

agentwt list --status

Include unmanaged Git worktrees:

agentwt list --all --status

Machine-readable output:

agentwt list --json --all --status

5. Synchronize a session

agentwt sync auth-refactor

This fetches the recorded remote and rebases the clean session branch onto <remote>/<base-branch>.

6. Clean up when merged

agentwt cleanup auth-refactor --dry-run
agentwt cleanup auth-refactor --yes

Normal cleanup removes the worktree and deletes the session branch only after confirming that the worktree is clean, inactive, not in the middle of another Git operation, and merged into its recorded base.

How sessions are laid out

For a main repository at:

C:\Users\User\src\payments       # Windows
/home/user/src/payments            # Linux

the default container is:

C:\Users\User\src\.payments.agentwt
/home/user/src/.payments.agentwt

The naming formulas are:

container = <main-repository-parent>/.<repository-name>.agentwt
worktree  = <container>/<session-name>
branch    = agent/<session-name>

The container is removed automatically only when cleanup leaves it empty.

Session names should be simple slugs such as auth-refactor, issue_42, or test-hardening. Names containing path separators, control characters, .., unsafe Git-ref characters, trailing dots/spaces, or Windows reserved device names are rejected.

Common workflows

Complete parallel-development workflow

The following example uses three Codex agents to develop sorting, searching, and tree features independently. Run agentwt commands from the main repository unless a step explicitly says otherwise.

First, confirm that the main checkout contains a committed starting point:

git status
git add -A
git commit -m "Save project before parallel agent work"

Create three isolated sessions:

agentwt start sorting --agent codex
agentwt start searching --agent codex
agentwt start trees --agent codex
agentwt list --status

start creates a new branch and worktree. Do not use it to restart an existing session. If a terminal was closed while its worktree still exists, reopen it instead:

agentwt open sorting --agent
agentwt open searching --agent
agentwt open trees --agent

Open a normal shell in an existing worktree without launching its agent:

agentwt open sorting

Each agent should test and commit its work on its own branch before integration. From the corresponding worktree, use the project's normal verification commands and create a commit:

npm test
npm run lint
npm run build
git add -A
git commit -m "Implement sorting algorithms and visualizer"

Repeat that step in the searching and trees worktrees with appropriate commit messages. A clean main checkout does not prove that linked worktrees are committed. Inspect all branch-only commits from the main checkout:

git log --oneline main..agent/sorting
git log --oneline main..agent/searching
git log --oneline main..agent/trees

If a merge says Already up to date but an agent visibly changed files, inspect that agent's worktree. The changes are probably uncommitted:

git -C "../.AlgoVisualizer.agentwt/sorting" status --short

After all agent work is committed, switch to the main checkout and merge one branch at a time:

git switch main
git merge --no-ff agent/sorting -m "Merge sorting algorithms"
git merge --no-ff agent/searching -m "Merge searching algorithms"
git merge --no-ff agent/trees -m "Merge tree algorithms"

agentwt deliberately does not perform these merges. Keeping integration as an explicit Git operation prevents an agent session from unexpectedly changing the main branch.

If a merge reports conflicts, do not begin the next merge. Inspect and resolve the current operation first:

git status
# edit each unmerged file and preserve the intended changes from both branches
git add -A
git commit

To abandon only the current unfinished merge and return to the state before it began:

git merge --abort

After all merges, verify the combined application and push the main branch when a remote is configured:

npm test
npm run lint
npm run build
git push origin main

Finally, preview and remove the finished sessions:

agentwt cleanup sorting --dry-run
agentwt cleanup sorting --yes
agentwt cleanup searching --yes
agentwt cleanup trees --yes

Cleanup removes the linked worktree and its agent/<name> branch. Code already merged into main remains in main.

Test multiple web worktrees on different localhost ports

Each worktree is a separate project directory, so install its dependencies separately. For a Vite project, open one ordinary terminal per session and give each development server a unique port:

agentwt open sorting
# in the new sorting terminal
npm install
npm run dev -- --port 5173 --strictPort

agentwt open searching
# in the new searching terminal
npm install
npm run dev -- --port 5174 --strictPort

agentwt open trees
# in the new trees terminal
npm install
npm run dev -- --port 5175 --strictPort

The three versions are then available independently at:

Session	URL
Sorting	http://localhost:5173
Searching	http://localhost:5174
Trees	http://localhost:5175

Press Ctrl+C in each development-server terminal to stop it. agentwt stop <name> supervises the recorded coding-agent process; it does not manage unrelated development servers launched from a separate shell.

Start when only generated or ignored files are present

The source safety check includes ignored files. Common generated entries such as node_modules/, dist/, and *.tsbuildinfo therefore cause start to report a dirty worktree even when ordinary git status looks clean.

Inspect exactly what is present:

git status --short
git status --short --ignored

Short-status markers have these meanings:

Marker	Meaning
M	Modified tracked file
??	Untracked file
!!	Ignored file

If every reported item is a disposable dependency or build output, explicitly authorize creation:

agentwt start sorting --agent codex --allow-dirty

Do not commit dependency/build directories merely to satisfy the check. Uncommitted source changes are not copied into the new worktree, so commit meaningful source changes before using --allow-dirty.

Clean up after a local-only merge

Normal cleanup checks the session branch against its recorded <remote>/<base> reference. If the repository has no configured origin, or main was merged locally but not pushed, the remote reference may not exist even though the branch is an ancestor of local main.

Check local ancestry explicitly:

git merge-base --is-ancestor agent/sorting main

Exit status 0 means the branch is contained in local main. The preferred solution for a repository with a remote is to push the base branch and then use normal cleanup:

git push origin main
agentwt cleanup sorting --force-dirty --yes

For a deliberately local-only repository, after confirming the ancestry check returned 0, bypass the unavailable remote check explicitly:

agentwt cleanup sorting --force-dirty --force-unmerged --yes

In this specific situation, --force-unmerged authorizes bypassing remote verification; it does not imply that the branch failed the local ancestry check. --force-dirty is needed only when the worktree still contains generated, ignored, untracked, or modified content that will be deleted.

Start from another base branch

agentwt start payment-retry --base release/2026-q3

Detached HEAD is rejected unless --base is supplied explicitly.

Use another remote

agentwt start auth-refactor --remote upstream
agentwt sync auth-refactor --remote upstream

The selected remote and base are recorded with the session. Passing new values to sync updates the record after a successful rebase.

Select another configured agent

agentwt start codex-review --agent codex

Claude and Codex are available as built-in adapters:

agentwt start claude-task --agent claude
agentwt start codex-task --agent codex

With the generated default_agent = "auto" configuration, a normal start detects the available agent automatically:

agentwt start codex-task

Detection checks Codex first, then Claude. No per-session option or configuration edit is needed. You can still force a particular adapter with --agent claude or --agent codex.

Any other adapter must exist under [agents.<name>] in configuration.

Override the terminal for one session

agentwt start no-ui-task --terminal none
agentwt start konsole-task --terminal konsole
agentwt start windows-task --terminal windows-terminal

Valid terminal adapter names are auto, konsole, windows-terminal, custom, and none.

If terminal launch fails after creation, the valid worktree is preserved. Open it later with agentwt open, or change directory to the path printed by start.

Reopen an existing session

Open the terminal's default shell:

agentwt open auth-refactor

Run the session's recorded agent adapter:

agentwt open auth-refactor --agent
agentwt open auth-refactor --agent -- --model sonnet

Synchronize every managed session

Preview first:

agentwt sync --all --dry-run
agentwt sync --all

Each remote is fetched once per batch. Active, dirty, detached, or mid-operation worktrees are refused before rebasing.

Stop a running agent

Request graceful termination:

agentwt stop auth-refactor

Force termination only when graceful shutdown is insufficient:

agentwt stop auth-refactor --force

On Linux, graceful and forced stopping use SIGTERM and SIGKILL on the verified process group. On Windows, _run accepts a local named-pipe request; graceful stopping sends CTRL_BREAK_EVENT, while forced stopping terminates the Job Object and its child processes.

Clean up merged sessions in a batch

agentwt cleanup --merged --dry-run
agentwt cleanup --merged --yes

Sessions that do not meet normal cleanup conditions are skipped in --merged mode.

Keep the branch after removing the worktree

agentwt cleanup auth-refactor --keep-branch --yes

Explicitly authorize exceptional cleanup

agentwt cleanup auth-refactor --force-dirty --yes
agentwt cleanup auth-refactor --force-unmerged --yes
agentwt cleanup auth-refactor --force-dirty --force-unmerged --yes

These flags authorize different risks and are intentionally separate:

• --force-dirty permits forced removal of a worktree containing changes.
• --force-unmerged permits deletion of a branch not merged into the recorded base.

Always use --dry-run and inspect the worktree manually before using either option.

Command reference

All commands accept the global option:

--git <GIT>    Use a specific Git executable

Examples:

agentwt --git "C:\Program Files\Git\cmd\git.exe" list
agentwt --git /usr/local/bin/git doctor

agentwt init

agentwt init [--global] [--dry-run] [--yes]

• Discovers the current repository and Git common directory.
• Reports platform integrations and whether configured agents are available.
• Writes repository configuration by default or user configuration with --global.
• Requires --yes before writing.
• Does not overwrite an existing configuration file.

agentwt start

agentwt start <NAME>
    [--base <REF>]
    [--remote <REMOTE>]
    [--agent <ADAPTER>]
    [--terminal <ADAPTER>]
    [--no-launch]
    [--allow-dirty]
    [--dry-run]
    [-- <AGENT_ARGS>...]

Before mutation, start checks the session name, generated branch, source status, base commit, destination, registered Git worktrees, configuration, and collisions. The branch and directory are never reused automatically.

By default, tracked, untracked, and ignored source changes cause refusal. --allow-dirty bypasses this source-worktree check; it does not copy arbitrary changes into the new worktree.

Creation and configuration-migration failures trigger rollback. Terminal-launch failure does not remove a successfully created worktree.

agentwt list

agentwt list [--json] [--all] [--status]

• Default output contains managed sessions.
• --all also includes registered external worktrees without adopting them.
• --status checks whether each displayed worktree is clean.
• --json emits stable structured output suitable for scripts.

Example JSON object:

{
  "name": "auth-refactor",
  "managed": true,
  "platform": "windows",
  "branch": "agent/auth-refactor",
  "base": "main",
  "path": "C:\\src\\.payments.agentwt\\auth-refactor",
  "clean": true,
  "agent_status": "created"
}

agentwt open

agentwt open <NAME> [--agent] [-- <AGENT_ARGS>...]

Without --agent, opens the recorded worktree in the configured terminal's default shell. With --agent, runs the recorded adapter through the internal _run process supervisor.

agentwt sync

agentwt sync [<NAME> | --all]
    [--base <BRANCH>]
    [--remote <REMOTE>]
    [--dry-run]

Synchronization performs:

git fetch -- <remote>
git rebase <remote>/<base>

It never auto-stashes, merges, resets, pushes, or force-pushes.

If a rebase conflicts, Git's recoverable state is left in the worktree:

git status
# resolve files
git add <resolved-files>
git rebase --continue

To abandon the rebase:

git rebase --abort

agentwt stop

agentwt stop <NAME> [--force]

The recorded PID and platform process identity are verified before signaling, reducing the risk of acting on a reused PID. --force escalates to the platform's force-termination mechanism.

agentwt cleanup

agentwt cleanup <NAME>
    [--keep-branch]
    [--force-unmerged]
    [--force-dirty]
    [--yes]
    [--dry-run]

agentwt cleanup --merged [--yes] [--dry-run]
agentwt cleanup --prune-orphans [--yes] [--dry-run]

Mutation requires --yes. Normal cleanup requires a managed, inactive, clean worktree with no in-progress Git operation and a branch merged into its recorded remote/base.

--prune-orphans runs Git worktree pruning. It repairs Git metadata only; it does not adopt external worktrees.

agentwt doctor

agentwt doctor [--repair] [--yes]

Checks the repository, configured terminal and agents, recorded worktree paths, Git worktree inventory, desktop-session hints on Linux, and long-path configuration on Windows.

The default operation is read-only. --repair requires --yes and prunes stale Git worktree metadata. A non-zero exit status means one or more required integrations or managed records need attention.

agentwt completions

agentwt completions <bash|elvish|fish|powershell|zsh>

Examples:

agentwt completions powershell | Out-String | Invoke-Expression

agentwt completions bash > ~/.local/share/bash-completion/completions/agentwt
agentwt completions zsh > ~/.zfunc/_agentwt
agentwt completions fish > ~/.config/fish/completions/agentwt.fish

Persist completions using the location recommended by your shell and operating system.

Configuration

Configuration precedence, from highest to lowest, is:

1. Command-line options.
2. <main-worktree>/.agentwt.toml.
3. Platform user configuration.
4. Built-in defaults.

User configuration locations:

Platform	Path
Windows	%APPDATA%\agentwt\config.toml
Linux with XDG	$XDG_CONFIG_HOME/agentwt/config.toml
Linux fallback	$HOME/.config/agentwt/config.toml

Full example

branch_prefix = "agent/"
default_agent = "auto"
default_remote = "origin"

[terminal]
kind = "auto"

[platform.windows]
worktree_root = "../.${repo_name}.agentwt"

[platform.linux]
worktree_root = "../.${repo_name}.agentwt"

[agents.claude]
executable = "claude"
args = []

[agents.claude.platform.windows]
executable = "claude.exe"
args = []

[agents.claude.platform.linux]
executable = "claude"
args = []

[agents.codex]
executable = "codex"
args = []

[agents.codex.platform.windows]
executable = "codex.exe"
args = []

[agents.codex.platform.linux]
executable = "codex"
args = []

[agents.cursor]
executable = "cursor-agent"
args = []

Logical worktree patterns use /. ${repo_name} expands to the main repository directory name, after which the path is converted to the native platform representation.

Custom terminal adapter

[terminal]
kind = "custom"

[terminal.custom]
executable = "kitty"
args = [
  "--directory",
  "{worktree}",
  "agentwt",
  "_run",
  "{session_id}"
]

Available placeholders are:

Placeholder	Meaning
{worktree}	Native worktree path
{name}	Session name/title
{session_id}	Internal managed session ID

Each template entry becomes exactly one argument. Placeholder expansion never splits an argument and never invokes a shell.

If the configured terminal executable is missing, start preserves the created worktree and prints recovery instructions. It does not silently choose another terminal.

Agent adapters

[agents.reviewer]
executable = "review-agent"
args = ["--mode", "review"]

Configured arguments are applied first, followed by arguments forwarded after -- on start or open.

Executables are resolved using native PATH behavior. On Windows, .exe, .cmd, and .bat candidates are recognized. Unsafe control characters in arguments forwarded to command shims are rejected.

Local configuration migration

After creating a worktree, agentwt discovers local-only files reported by Git and copies selected content into the new worktree:

• .env and .env.* files.
• Untracked or ignored files under .claude/.
• Untracked or ignored files under .cursor/.

Tracked files are already populated by Git and are not migrated. Existing destination content is never overwritten. Symlinks, sockets, devices, named pipes, directories masquerading as files, and other special files are rejected.

Copies are written through temporary files and renamed into place. A migration failure removes files created by that migration and rolls back the newly created worktree and branch.

Permissions:

• Linux files are restricted to 0600; private directories use 0700.
• Windows files and directories receive a restrictive ACL for the owner and SYSTEM.

Important: the default source cleanliness check includes ignored and untracked files. If the repository contains local .env, .claude/, or .cursor/ content that you intentionally want migrated, inspect git status --ignored, then explicitly allow the dirty source:

agentwt start auth-refactor --allow-dirty

--allow-dirty authorizes session creation from a dirty source. Only the selected local configuration paths above are copied; unrelated changes are not transferred.

Never assume a migrated secret remains synchronized. Copies are intentionally independent per worktree.

State and process management

State locations:

Platform	Path
Windows	%LOCALAPPDATA%\agentwt\state\repos\<repository-id>\
Linux with XDG	$XDG_STATE_HOME/agentwt/repos/<repository-id>/
Linux fallback	$HOME/.local/state/agentwt/repos/<repository-id>/

Each repository directory contains:

operation.lock
state.json

The state record includes session identity, branch/base/remote information, canonical native path, timestamps, selected agent, migrated paths, runner PID, process identity, and the latest lifecycle result.

Paths are stored in a platform-tagged byte-safe representation. State is local to one operating system and should not be copied between Windows and Linux.

Mutating operations acquire an exclusive repository lock. State writes use a same-directory temporary file, flush and filesystem synchronization, restrictive permissions, and atomic replacement.

Do not hand-edit state.json while an agentwt command is running. Use agentwt doctor to diagnose discrepancies between local state and Git's worktree inventory.

Safety guarantees

agentwt applies the following safeguards:

• Uses structured executable and argument values; it does not build shell command strings.
• Treats git worktree list --porcelain -z as the worktree authority.
• Keeps native paths as PathBuf/OsString values and parses Git worktree output as raw bytes.
• Rejects unsafe session names and invalid Git refs.
• Rejects existing branches, directories, sessions, and registered-worktree collisions.
• Rejects destinations inside registered worktrees.
• Rejects unexpected symlink or junction traversal in destination parents.
• Uses case-insensitive path/session comparisons on Windows and case-sensitive comparisons on Linux.
• Serializes common Git mutations with an advisory operation lock.
• Rolls back creation and migration failures in reverse order.
• Preserves valid worktrees after terminal-launch failure.
• Refuses dirty source and managed worktrees by default.
• Refuses sync or cleanup while an agent is recorded as active.
• Verifies process identity before stopping an agent.
• Never adopts or mutates external worktrees automatically.
• Never automatically commits, stashes, pushes, merges, resets, or force-pushes.

Force options are narrow authorizations. They do not disable unrelated validation.

Troubleshooting

not inside a Git repository

Run agentwt from the main worktree or one of the repository's registered linked worktrees:

git rev-parse --show-toplevel
git worktree list

Source worktree is dirty

Inspect all tracked, untracked, and ignored content:

git status --short --ignored

Commit, remove, or relocate unintended changes. Use --allow-dirty only after reviewing them and understanding that unrelated changes will not appear in the new worktree.

Branch or destination already exists

agentwt never reuses either automatically. Inspect:

git branch --list "agent/*"
git worktree list --porcelain

Choose a different session name or manually resolve stale Git metadata. agentwt doctor --repair --yes can prune stale worktree registrations, but it does not delete arbitrary directories or branches.

Terminal executable is missing

The worktree remains usable. Either:

agentwt open <name>

or change directory to the path reported by agentwt start. Install the expected default terminal, configure a custom adapter, or use --no-launch/--terminal none.

On Linux, also verify that DISPLAY or WAYLAND_DISPLAY is set in the desktop session.

Agent executable is missing

Check adapter detection:

agentwt doctor

Then verify the executable on PATH or configure an absolute/native executable path under [agents.<name>].

Sync fails because the remote is unavailable

No branch is rewritten before a successful fetch. Verify connectivity and the recorded remote:

git remote -v
git fetch -- <remote>

Retry agentwt sync after connectivity is restored.

Rebase conflict

The worktree is intentionally left in a recoverable rebase state. Resolve and continue, or abort, using the commands printed by agentwt. Sync and cleanup remain blocked until the Git operation is completed or aborted.

Stop refuses because the PID identity changed

The recorded PID may have been reused after an unclean exit. agentwt never signals a process whose identity differs from the recorded runner. Current builds safely clear that stale runner record when stop confirms the mismatch:

agentwt stop <name>

Expected recovery output is similar to:

cleared stale runner record for `<name>`; no process was terminated

Cleanup can then proceed normally. Do not use taskkill, kill, or Stop-Process on the reused PID because it may now belong to an unrelated application.

Cleanup says the branch is unmerged

Confirm the intended remote/base and inspect ancestry:

git fetch origin
git merge-base --is-ancestor agent/<name> origin/<base>

If origin/<base> does not exist, check whether the repository has a remote and whether the local base was pushed:

git remote -v
git merge-base --is-ancestor agent/<name> <base>
git push origin <base>

Use --force-unmerged only if losing the branch is intentional, or after separately proving that it is contained in the local base and the recorded remote reference is intentionally unavailable. Use --keep-branch when you want to remove only the worktree.

Windows long paths

agentwt doctor warns when Git's long-path support is not enabled. With an appropriately configured Git for Windows installation, inspect or enable it according to your organization's policy:

git config --show-origin --get core.longpaths
git config --global core.longpaths true

Elevated system policy may still be required for some Windows environments.

State and Git disagree

Start with the read-only diagnostic:

agentwt doctor
git worktree list --porcelain

If the issue is stale Git worktree metadata:

agentwt doctor --repair --yes

External worktrees remain external and are never automatically adopted.

Known limitations

Version 1 scope intentionally excludes:

• macOS.
• ARM64 release artifacts.
• Built-in Windows/WSL path translation.
• Mixing native Windows and WSL worktrees in one invocation.
• Automatic submodule initialization.
• Automatic Git LFS installation or repair.
• Automatic fallback to unrelated terminal applications.
• Automatic commit, stash, merge, push, reset, or force-push operations.

Desktop terminal behavior cannot be fully verified in ordinary headless CI. Validate Windows Terminal and Konsole launching in the desktop environments used for deployment.

Development and releases

The package uses Rust Edition 2024 and declares Rust 1.85 as its minimum supported version.

Run the full local verification suite:

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --locked
cargo build --release --locked

The CI matrix runs formatting, Clippy, tests, and release compilation on both ubuntu-latest and windows-latest.

Generate completion artifacts for packaging:

agentwt completions bash > agentwt.bash
agentwt completions zsh > _agentwt
agentwt completions fish > agentwt.fish
agentwt completions powershell > agentwt.ps1

Tagged releases build x86-64 Linux GNU and Windows MSVC archives, then publish a SHA256SUMS file alongside them.