v6.2.0

🚀 What's New in v6.2.0

v6.2.0 adds branch-preserving worktree deletion and improves the reliability of Phantom's packaged CLI and test pipeline.

✨ New Features

Keep branches when deleting worktrees (#433)

You can now delete a worktree without deleting its Git branch. This works from the CLI, from MCP clients, and as a global Phantom preference.

# Delete only the worktree and keep the branch
phantom delete feature-auth --keep-branch

# Make branch preservation your default
phantom preferences set keepBranch true

🛠️ Improvements

• Migrate the CLI bundler from esbuild to tsdown (#415) - Keeps the existing ESM output and executable behavior while modernizing the build pipeline.
• Move worktree orchestration into @phantompane/core (#423) - Centralizes create and attach flows in core and keeps CLI handlers focused on parsing and delegation.
• Add end-to-end CLI coverage (#424) - Introduces a dedicated e2e/ workspace with Vitest-based coverage for core Phantom commands.
• Add E2E coverage for phantom.config.json post-create hooks (#425) - Verifies postCreate.copyFiles and postCreate.commands in real repository flows.
• Migrate tests to Vitest (#413) - Replaces the previous node --test setup with Vitest across the monorepo.
• Migrate tests to TypeScript (#414) - Converts repository tests to TypeScript and tightens type safety in the suite.
• Extract a dedicated @phantompane/tmux package (#429) - Separates tmux responsibilities from general process helpers.
• Rename the shared workspace package to utils (#430) - Clarifies package responsibilities and keeps CLI-specific concerns inside the CLI layer.
• Fix devenv git-hooks input wiring (#432) - Restores successful devenv shell -- true evaluation.

🐛 Bug Fixes

• Bundle Phantom CLI runtime dependencies with tsdown (#417) - Prevents unresolved workspace imports in packaged npm installs and keeps the published CLI runnable.

📚 Documentation

• Document the keep-branch delete workflow (#434) - Adds usage guidance for phantom delete --keep-branch, the keepBranch preference, and the MCP keepBranch option.

📦 Dependencies

• Bump actions/setup-node from 6.2.0 to 6.3.0 (#421)
• Bump @typescript/native-preview from 7.0.0-dev.20260309.1 to 7.0.0-dev.20260313.1 (#422)
• Bump @typescript/native-preview from 7.0.0-dev.20260313.1 to 7.0.0-dev.20260320.1 (#426)
• Bump @types/node from 25.3.5 to 25.4.0 (#427)
• Bump tsdown from 0.21.3 to 0.21.4 (#428)

---

Installation/Upgrade:

npm install -g @phantompane/cli@latest
# or
brew upgrade phantom

Full Changelog: v6.1.0...v6.2.0

v6.1.0

🚀 What's New in v6.1.0

Worktree directory naming customization, toolchain migration to OX tools, and Turborepo-powered task orchestration.

✨ New Features

directoryNameSeparator config option (#407)

Customize how directory paths are flattened when creating worktree directories. Configure via phantom.config.json or phantom preferences:

# Set separator in preferences
phantom preferences set directoryNameSeparator "-"

# Or configure in phantom.config.json
{
  "directoryNameSeparator": "-"
}

🛠️ Improvements

• Migrate from Biome to OX tools (#408) - Replace Biome with oxfmt and oxlint for formatting and linting
• Add Turborepo task orchestration (#409) - Introduce Turborepo for monorepo task orchestration with turbo run
• Centralize context settings resolution (#410) - Resolve directoryNameSeparator inside createContext with preference-over-config precedence
• Add devenv pre-commit hooks (#411) - Add devenv-managed pre-commit hooks for fix, typecheck, and test via Turborepo

📦 Dependencies

• Bump @types/node from 25.3.0 to 25.3.5 (#403)
• Bump @modelcontextprotocol/inspector from 0.21.0 to 0.21.1 (#400)
• Bump @typescript/native-preview from 7.0.0-dev.20260306.1 to 7.0.0-dev.20260309.1 (#402)

---

Installation/Upgrade:

npm install -g @phantompane/cli@latest
# or
brew upgrade phantom

Full Changelog: v6.0.0...v6.1.0

v6.0.0

🚀 What's New in v6.0.0

Phantom's repository and npm packages have been transferred to the new phantompane organization.

• GitHub: aku11i/phantom → phantompane/phantom
• npm: @aku11i/phantom → @phantompane/cli

The old package @aku11i/phantom has been deprecated.

⚠️ Action Required for npm Users

Please reinstall using the new package:

npm uninstall -g @aku11i/phantom
npm install -g @phantompane/cli

No action is needed if you installed via Homebrew.

✨ Changes

Repository & Package Migration (#399, #404)

• Renamed all package scopes from @aku11i/phantom-* to @phantompane/*
• Updated all internal references and documentation to use new organization URLs
• Deprecated @aku11i/phantom on npm with migration message

Bug Fixes

• fix: keep worktreesDirectory as project config (#396) - worktreesDirectory in phantom.config.json is now correctly prioritized as a project-level config

Development

• Added devenv-based devcontainer (#397)
• Added .envrc for devenv direnv integration (#398)

Dependencies

• Bump @biomejs/biome 2.4.0 → 2.4.4 (#387)
• Bump @modelcontextprotocol/sdk 1.26.0 → 1.27.1 (#389, #393)
• Bump @typescript/native-preview (#388, #390, #395)
• Bump @modelcontextprotocol/inspector 0.20.0 → 0.21.0 (#392)
• Bump @types/node 25.2.3 → 25.3.0 (#394)

---

Full Changelog: v5.1.0...v6.0.0

v5.1.0

🚀 What's New in v5.1.0

Worktree names can now be auto-generated — just run phantom create without a name and get a unique, human-readable identifier.

✨ New Features

Automatic worktree name generation (#381)

You no longer need to come up with a name every time you create a worktree. Simply omit the name and Phantom will generate one for you:

# Auto-generate a unique worktree name
phantom create

# You can still specify a name explicitly
phantom create my-feature

Generated names are human-readable (e.g., bold-red-dragon) and guaranteed to be unique across existing worktree directories and branches.

🐛 Bug Fixes

• Fixed branchExists always returning true (#383) — git show-ref --verify --quiet exits with code 1 and empty stderr for missing branches, which was silently treated as success. Switched to git branch --list to correctly detect branch existence. This fix unblocks the automatic name generation feature above.

📦 Dependencies

• bump @modelcontextprotocol/sdk from 1.25.1 to 1.26.0 (#351, #361, #377)
• bump @modelcontextprotocol/inspector from 0.18.0 to 0.20.0 (#365, #379)
• bump @biomejs/biome from 2.3.11 to 2.4.0 (#366, #372, #374, #380)
• bump zod from 4.3.4 to 4.3.6 (#349, #362)
• bump esbuild from 0.27.2 to 0.27.3 (#371)
• bump @types/node from 25.0.0 to 25.2.3 (#352, #356, #359, #370, #375)
• bump @typescript/native-preview (#350, #355, #363, #364, #369, #376, #378)
• bump oven-sh/setup-bun from 2.0.2 to 2.1.2 (#348, #357)
• bump dependabot/fetch-metadata from 2.3.0 to 2.5.0 (#347)
• bump actions/setup-node from 6.1.0 to 6.2.0 (#360)
• bump actions/checkout from 6.0.1 to 6.0.2 (#358)

---

Installation/Upgrade:

npm install -g @aku11i/phantom@latest
# or
brew upgrade phantom

Full Changelog: v5.0.0...v5.1.0

v5.0.0

🚀 What's New in v5.0.0

Fork PR checkouts now match GitHub CLI naming (owner/branch), aligning worktree and local branch names with gh pr checkout.

⚠️ Breaking Changes

Fork PR worktree names now include owner prefix (#342)

Fork PR checkouts now create worktrees/branches as {owner}/{branch} instead of {branch}. Scripts that assumed the old naming should be updated.

# previous behavior (fork PR)
phantom github checkout 123
# worktree: feature/add-logging

# new behavior
phantom github checkout 123
# worktree: aku11i/feature/add-logging

🛠️ Improvements

• Docs/help updated for fork PR naming (#342)

🔧 Release

• Version bump PR (#343) — Thanks @github-actions[bot]!

🙏 New Contributors

No new contributors in this release.

---

Installation/Upgrade:

npm install -g @aku11i/phantom@latest
# or
brew upgrade phantom

Full Changelog:
v4.0.0...v5.0.0

v4.0.0

🚀 What's New in v4.0.0

The default (git root) worktree is now included in list output by default, with a new --no-default flag to preserve previous behavior.

⚠️ Breaking Changes

Default worktree now appears in phantom list (#339)

phantom list / phantom list --names / phantom list --fzf now include the default (git root) worktree. Scripts that assumed only sub worktrees must pass --no-default.

# previous behavior
phantom list --no-default
phantom list --names --no-default

🛠️ Improvements

• Protect default worktree in delete flows (#339) — phantom delete <default-branch> now reports the worktree as not found; delete completions exclude default entries.
• Dependabot auto-merge workflow (#338)

🧹 Dependency Updates

• Dependabot bumps (#324, #325, #326, #328, #330, #331, #332, #334, #336) — Thanks @dependabot[bot]!

🔧 Release

• Version bump PRs (#340, #341) — Thanks @github-actions[bot]!

🙏 New Contributors

No new contributors in this release.

---

Installation/Upgrade:

npm install -g @aku11i/phantom@latest
# or
brew upgrade phantom

Full Changelog: v3.3.1...v4.0.0

v3.3.1

What's Changed

• Add Windows command resolution using where.exe for phantom exec by @aku11i in #282
• chore(version): v3.3.1 by @github-actions[bot] in #323

Full Changelog: v3.3.0...v3.3.1

v3.3.0

🚀 What's New in v3.3.0

This release introduces flexible worktree directory configuration through preferences and the ability to delete multiple worktrees at once.

✨ New Features

Configurable Worktree Directory via Preferences (#318)

You can now configure where phantom stores worktrees using phantom preferences:

# Set custom worktrees directory (relative path)
phantom preferences set worktreesDirectory ../phantom-worktrees

# View current preference
phantom preferences get worktreesDirectory

The preference supports both absolute and relative paths. Relative paths are resolved from your repository root. The default remains .git/phantom/worktrees/.

Note: phantom.config.json worktreesDirectory is now deprecated and will show a warning. Please migrate to preferences.

Delete Multiple Worktrees at Once (#316)

phantom delete now accepts multiple worktree names:

# Delete multiple worktrees
phantom delete feature-a feature-b hotfix-123

# Interactive selection with fzf
phantom delete

🐛 Bug Fixes

• Normalize preference key casing (#319)

🛠️ Improvements

• Add latest Node to CI matrix (#320) - Ensures compatibility with newest Node.js versions

📚 Documentation

• Update Homebrew installation instructions (#313)
• Add platform support notes (#303)

📦 Dependencies

• bump @modelcontextprotocol/sdk from 1.23.0 to 1.24.0 (#314)
• bump @modelcontextprotocol/inspector from 0.17.2 to 0.17.5 (#309)
• bump @biomejs/biome from 2.3.1 to 2.3.8 (#307)
• bump @types/node from 24.9.1 to 24.10.1 (#308)
• bump esbuild from 0.27.0 to 0.27.1 (#312)
• bump actions/checkout from 6.0.0 to 6.0.1 (#305)
• bump actions/setup-node from 6.0.0 to 6.1.0 (#306)
• bump @typescript/native-preview from 7.0.0-dev.20251120.1 to 7.0.0-dev.20251203.1 (#310)

---

Installation/Upgrade:

npm install -g @aku11i/phantom@latest
# or
brew upgrade phantom

Full Changelog: v3.2.0...v3.3.0

v3.2.0

🚀 What's New in v3.2.0

Phantom now has built-in editor and AI launchers so you can jump into a worktree or your preferred coding assistant with one command.

✨ New Features

phantom edit (#296)

Open any worktree directly in your configured editor (prefers phantom.editor over $EDITOR).

# Set your editor once
phantom preferences set editor "code --reuse-window"
# Open a worktree (optionally target a path)
phantom edit feature-auth README.md

phantom ai (#299)

Launch your configured AI assistant inside a worktree with Phantom context.

# Configure your assistant once
phantom preferences set ai "claude"
# Start it in a worktree
phantom ai feature-auth

🛠️ Improvements

• Preferences subcommands to manage editor/AI defaults in global git config (#298)
• Better exec completions and GitHub checkout help alignment (#297, #295)
• Dependency bump to zod v4 (#294)

🐛 Bug Fixes

• Packaging now requires an explicit package version when building (#293)

📚 Documentation

• Refreshed docs/help/completions for edit/ai/preferences (#301)

🙏 New Contributors

• No new contributors in this release.

---

Installation/Upgrade:

npm install -g @aku11i/phantom@latest
# or
brew upgrade phantom

Full Changelog: v3.1.1...v3.2.0

v3.1.1

What's Changed

• Update archive naming order for build outputs by @aku11i in #291
• chore(version): v3.1.1 by @github-actions[bot] in #292

Full Changelog: v3.1.0...v3.1.1