@aku11i/phantom 0.9.0 → 1.0.0

package/README.md

@@ -9,422 +9,177 @@
 [![Node.js Version](https://img.shields.io/node/v/@aku11i/phantom.svg)](https://nodejs.org)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/aku11i/phantom)
 
-[Installation](#-installation) • [Basic Usage](#-basic-usage) • [Why Phantom?](#-why-phantom) • [Documentation](#-documentation) • [日本語](./README.ja.md)
+[日本語](./README.ja.md) • [Installation](#-installation) • [Why Phantom?](#-why-phantom) • [Basic Usage](#-basic-usage) • [Documentation](#-documentation)
 
 </div>
 
-## ✨ Overview
+## ✨ What is Phantom?
 
-Phantom is a CLI tool that dramatically simplifies Git worktree management. It's optimized for modern development workflows where you need to work on multiple features, bug fixes, and PR reviews in parallel.
+Phantom is a powerful CLI tool that dramatically boosts your development productivity by making Git worktrees simple and intuitive. Run multiple tasks in isolated environments simultaneously and achieve true multitask development. Built for the next generation of parallel development workflows, including AI-powered coding with multiple agents.
 
 ### Key Features
 
-- 🚀 **Simplified Worktree Management** - Create and manage Git worktrees with intuitive commands
-- 🔄 **Seamless Context Switching** - Jump between different features without stashing or committing
-- 🤖 **AI-Friendly** - Perfect for running multiple AI coding agents in parallel
-- 🎯 **Branch-Worktree Sync** - Automatically creates matching branches for each worktree
-- 🐚 **Interactive Shell** - SSH-like experience for worktree navigation
-- ⚡ **Zero Configuration** - Works out of the box with sensible defaults
-- 📦 **Zero Dependencies** - Lightweight and fast with no external dependencies
+- 🚀 **Simple worktree management** - Create and manage Git worktrees with intuitive commands
+- 🔄 **True multitasking** - Create separate working directories per branch and run multiple tasks simultaneously
+- 🎯 **Execute commands from anywhere** - Run commands in any worktree with `phantom exec <worktree> <command>`
+- 🪟 **Built-in tmux integration** - Open worktrees in new panes or windows
+- 🔍 **Interactive selection with fzf** - Use built-in fzf option for worktree selection
+- 🎮 **Shell completion** - Full autocomplete support for Fish and Zsh
+- ⚡ **Zero dependencies** - Fast and lightweight
 
-## 🤔 Why Phantom?
-
-Modern development workflows often require working on multiple features simultaneously. While Git worktree is a powerful feature, it requires specifying paths and branches separately, which can be cumbersome.
-
-### The Manual Process
-
-When using Git worktree directly, you need to specify the worktree path, branch name, and base branch each time. Additionally, switching between tasks requires navigating directories, which can be a bit tedious when frequently switching between multiple parallel tasks.
+## 🚀 Installation
 
-### The Phantom Solution
+### Using Homebrew (recommended)
 
 ```bash
-# Traditional approach
-git worktree add -b feature ../project-feature origin/main
-cd ../project-feature
-
-# With Phantom
-phantom create feature --shell
+brew install aku11i/tap/phantom
 ```
 
-Phantom combines worktree and branch creation into a single command, making it easy to switch between and work in different workspaces.
-
-## 🚀 Basic Usage
+#### Using npm
 
 ```bash
-# Install Phantom
 npm install -g @aku11i/phantom
+```
 
-# Create a new worktree
-phantom create feature-awesome
-
-# Attach to an existing branch
-phantom attach existing-branch
-
-# Jump into the worktree
-phantom shell feature-awesome
+## 🤔 Why Phantom?
 
-# Or execute commands directly
-phantom exec feature-awesome npm install
-phantom exec feature-awesome npm test
+Git worktrees are powerful but require manual management of paths and branches. Also, navigating between multiple worktrees is cumbersome. Phantom eliminates these problems:
 
-# List all your worktrees
-phantom list
+```bash
+# Without Phantom
+git worktree add -b feature-awesome ../project-feature-awesome origin/main
+cd ../project-feature-awesome
 
-# Clean up when done
-phantom delete feature-awesome
+# With Phantom
+phantom create feature-awesome --shell
 ```
 
-## 📦 Installation
+### How Phantom Works
 
-### Using npm (recommended)
-```bash
-npm install -g @aku11i/phantom
-```
+When you run `phantom create feature-awesome`, a new Git worktree named `feature-awesome` is created in `.git/phantom/worktrees/`.
+All worktrees created with phantom are centrally managed in this location.
 
-### Using pnpm
-```bash
-pnpm add -g @aku11i/phantom
 ```
-
-### Using yarn
-```bash
-yarn global add @aku11i/phantom
+your-project/    # Git repository
+├── .git/
+│   └── phantom/
+│       └── worktrees/        # Phantom-managed directory
+│           ├── feature-awesome/  # branch name = worktree name
+│           ├── bugfix-login/     # another worktree
+│           └── hotfix-critical/  # yet another worktree
+└── ...
 ```
 
-### Build from source
-```bash
-git clone https://github.com/aku11i/phantom.git
-cd phantom
-pnpm install
-pnpm build
-npm link
-```
+This convention means you never need to remember worktree paths - just use the branch name for easy worktree operations.
 
-## 📖 Documentation
+### ✈️ Features for a Comfortable Development Experience
 
-### Commands Overview
+Phantom provides perfect functionality as a command-line tool. Developers feel the trust and comfort of flying first class.
 
-#### Worktree Management
+#### Shell Completion
 
-```bash
-# Create a new worktree with a matching branch
-phantom create <name>
-phantom create <name> --shell  # Create and enter interactive shell
-phantom create <name> --exec <command>  # Create and execute command
-phantom create <name> --tmux  # Create and open in new tmux window
-phantom create <name> --tmux-vertical  # Create and split tmux pane vertically
-phantom create <name> --tmux-v  # Shorthand for --tmux-vertical
-phantom create <name> --tmux-horizontal  # Create and split tmux pane horizontally
-phantom create <name> --tmux-h  # Shorthand for --tmux-horizontal
-
-# Create a worktree and copy specific files
-phantom create <name> --copy-file ".env" --copy-file ".env.local"
-
-# Attach to an existing branch as a worktree
-phantom attach <branch-name>
-phantom attach <branch-name> --shell  # Attach and enter interactive shell
-phantom attach <branch-name> --exec <command>  # Attach and execute command
-
-# List all worktrees with their current status
-phantom list
+Phantom supports full shell completion for fish and zsh. Use tab key to complete commands and worktree names.
 
-# Get the absolute path to a worktree
-phantom where <name>
+#### tmux Integration
 
-# Delete a worktree and its branch
-phantom delete <name>
-phantom delete <name> --force  # Force delete with uncommitted changes
-phantom delete --current        # Delete the current worktree (when inside one)
-phantom delete --current --force # Force delete current worktree
-```
-
-#### Working with Worktrees
+When creating worktrees, you can use tmux to open them in new windows or panes. This allows you to manage multiple work environments simultaneously.
 
 ```bash
-# Execute any command in a worktree's context
-phantom exec <name> <command> [args...]
+# Create and open worktree in new window
+phantom create feature-x --tmux
+# Create with split panes
+phantom create feature-y --tmux-vertical
+phantom create feature-z --tmux-horizontal
 
-# Examples:
-phantom exec feature-auth npm install
-phantom exec feature-auth npm run test
-phantom exec feature-auth git status
+# Open existing worktrees in tmux
+phantom shell feature-x --tmux
+phantom shell feature-y --tmux-v
 
-# Open an interactive shell session in a worktree
-phantom shell <name>
+# Result: Multiple worktrees displayed simultaneously, each allowing independent work
 ```
 
-### Environment Variables
+#### Editor Integration
 
-When opening an interactive shell with `phantom shell`, these environment variables are set:
+Phantom works seamlessly with editors like VS Code and Cursor. You can specify an editor to open worktrees.
 
-- `PHANTOM` - Set to "1" for all processes spawned from phantom shell
-- `PHANTOM_NAME` - Name of the current worktree
-- `PHANTOM_PATH` - Absolute path to the worktree directory
+```bash
+# Open with VS Code
+phantom create feature --exec "code ."
 
-## 💡 Use Cases
+# Or open existing worktree
+phantom exec feature code .
 
-Phantom is more than just a worktree wrapper - it's a productivity multiplier. Here are some real-world examples:
+# Open with Cursor
+phantom create feature --exec "cursor ."
+phantom exec feature cursor .
+```
 
-### tmux Integration
+#### fzf Integration
 
-Combine tmux with Phantom for an incredibly efficient workflow:
+Interactive search with fzf allows quick worktree selection.
 
 ```bash
-# Open a new tmux window and create a worktree in one command
-tmux new-window 'phantom create --shell new-feature'
-```
+# Open shell with fzf selection
+phantom shell --fzf
 
-This single line:
-1. Creates a new Git worktree for `new-feature` ✨
-2. Opens a new tmux window 🪟
-3. Starts an interactive shell in the new worktree 🚀
+# Delete with fzf selection
+phantom delete --fzf
+```
 
-When developing multiple features in parallel, you can manage each feature in its own tmux window.
+## 🔍 Basic Usage
 
-### VS Code Integration
+### Create a new worktree
 
 ```bash
-# Create a worktree and immediately open it in VS Code
-phantom create --exec "code ." new-feature
-phantom create --exec "cursor ." new-feature # also works with cursor!!
+phantom create feature-awesome
 
-# Attach to existing branch and open in VS Code
-phantom attach --exec "code ." feature/existing-branch
+phantom list
 ```
 
-### Parallel Development Workflow
+### Start a new shell in the worktree
 
 ```bash
-# When a bug report comes in during feature development
-phantom create hotfix-critical  # Create worktree for the fix
-phantom shell hotfix-critical   # Start working immediately
+phantom shell feature-awesome
 
-# After fixing, return to your feature
-exit  # Exit the hotfix shell
-phantom shell feature-awesome  # Continue feature development
-```
+# Start development work
 
-## 🔄 Phantom vs Git Worktree
-
-| Feature | Git Worktree | Phantom |
-|---------|--------------|---------|
-| Create worktree + branch | `git worktree add -b feature ../project-feature` | `phantom create feature` |
-| Attach to existing branch | `git worktree add ../project-feature feature` | `phantom attach feature` |
-| List worktrees | `git worktree list` | `phantom list` |
-| Navigate to worktree | `cd ../project-feature` | `phantom shell feature` |
-| Run command in worktree | `cd ../project-feature && npm test` | `phantom exec feature npm test` |
-| Remove worktree | `git worktree remove ../project-feature` | `phantom delete feature` |
-| Remove current worktree | `cd .. && git worktree remove project-feature` | `phantom delete --current` |
-
-## ⚙️ Configuration
-
-Phantom supports configuration through a `phantom.config.json` file in your repository root. This allows you to define files to be automatically copied and commands to be executed when creating new worktrees.
-
-### Configuration File
-
-Create a `phantom.config.json` file in your repository root:
-
-```json
-{
-  "postCreate": {
-    "copyFiles": [
-      ".env",
-      ".env.local",
-      "config/local.json"
-    ],
-    "commands": [
-      "pnpm install",
-      "pnpm build"
-    ]
-  }
-}
+# Exit the shell when done
+exit
 ```
 
-### Copy Files Feature
-
-When creating a new worktree, Phantom can automatically copy specified files from your current worktree to the new one. This is particularly useful for:
-
-- Environment configuration files (`.env`, `.env.local`)
-- Local development settings
-- Secret files that are gitignored
-
-You can specify files to copy in two ways:
-
-1. **Using the command line option:**
-   ```bash
-   phantom create feature --copy-file ".env" --copy-file ".env.local" --copy-file "config/local.json"
-   ```
-
-2. **Using the configuration file:**
-   Configure once in `phantom.config.json` and it will apply to all new worktrees.
-
-3. **Using both:**
-   Files specified in both the configuration file and command line options are merged together (duplicates are removed).
-
-> **Note:** Currently, glob patterns are not supported. Files must be specified with their exact paths relative to the repository root.
-
-### Post-Create Commands
-
-Phantom can automatically execute commands after creating a new worktree. This is useful for:
+### Run commands in any worktree
 
-- Installing dependencies (`pnpm install`, `npm install`, `yarn install`)
-- Building the project
-- Setting up the development environment
-- Running database migrations
-- Any other setup tasks specific to your project
-
-Commands are executed in the order they are specified in the configuration file. If a command fails, the creation process will stop and report the error.
-
-Example use cases:
-```json
-{
-  "postCreate": {
-    "commands": [
-      "pnpm install",           // Install dependencies
-      "pnpm db:migrate",        // Run database migrations
-      "cp .env.example .env",   // Create environment file from template
-      "pnpm build"              // Build the project
-    ]
-  }
-}
+```bash
+phantom exec feature-awesome {command to run}
+# Example: phantom exec feature-awesome npm run build
 ```
 
-## 🛠️ Development
+### Clean up when done
 
 ```bash
-# Clone and setup
-git clone https://github.com/aku11i/phantom.git
-cd phantom
-pnpm install
-
-# Run tests
-pnpm test
-
-# Run a specific test file
-pnpm test:file src/core/worktree/create.test.js
+phantom delete feature-awesome
+```
 
-# Type checking
-pnpm typecheck
 
-# Linting
-pnpm lint
+## 📚 Documentation
 
-# Run all checks
-pnpm ready
-```
+- **[Getting Started](./docs/getting-started.md)** - Common workflows and tips
+- **[Commands Reference](./docs/commands.md)** - All commands and options
+- **[Configuration](./docs/configuration.md)** - Set up automatic file copying and post-create commands
 
-## 🚀 Release Process
-
-To release a new version of Phantom:
-
-1. **Ensure you're on main branch and up to date**
-   ```bash
-   git checkout main
-   git pull
-   ```
-
-2. **Run all checks**
-   ```bash
-   pnpm ready
-   ```
-
-3. **Bump version**
-   ```bash
-   # For patch releases (bug fixes)
-   npm version patch
-
-   # For minor releases (new features)
-   npm version minor
-
-   # For major releases (breaking changes)
-   npm version major
-   ```
-
-4. **Push the version commit and tag**
-   ```bash
-   git push && git push --tags
-   ```
-
-5. **Publish to npm**
-   ```bash
-   pnpm publish
-   ```
-
-6. **Create GitHub release**
-   ```bash
-   # Create a release with automatically generated notes
-   gh release create v<version> \
-     --title "Phantom v<version>" \
-     --generate-notes \
-     --target main
-
-   # Example for v0.1.3:
-   gh release create v0.1.3 \
-     --title "Phantom v0.1.3" \
-     --generate-notes \
-     --target main
-   ```
-
-7. **Update release notes for clarity**
-   - Review the auto-generated release notes using `gh release view v<version>`
-   - Check PR descriptions for important details using `gh pr view <number>`
-   - Update the release notes to be more user-friendly:
-     - Group changes by category (Features, Bug Fixes, Improvements)
-     - Add usage examples for new features
-     - Explain the impact of changes in plain language
-     - Highlight security fixes and breaking changes
-   
-   ```bash
-   # Edit the release notes
-   gh release edit v<version> --notes "$(cat <<'EOF'
-   ## 🚀 What's New in v<version>
-   
-   ### ✨ New Features
-   - Feature description with usage example
-   
-   ### 🐛 Bug Fixes
-   - Clear description of what was fixed
-   
-   ### 🛠️ Improvements
-   - Performance, security, or other improvements
-   
-   EOF
-   )"
-   ```
-
-The build process is automatically handled by the `prepublishOnly` script, which:
-- Runs all tests and checks
-- Builds the TypeScript source to JavaScript using esbuild
-- Creates bundled executables in the `dist/` directory
-
-**Note**: The `dist/` directory is git-ignored and only created during the publish process.
 
 ## 🤝 Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
-
-Please make sure to:
-- Update tests as appropriate
-- Follow the existing code style
-- Run `pnpm ready` before submitting
+Contributions are welcome! See our [Contributing Guide](./CONTRIBUTING.md) for:
+- Development setup
+- Code style guidelines  
+- Testing requirements
+- Pull request process
 
 ## 📄 License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+MIT License - see [LICENSE](LICENSE)
 
 ## 🙏 Acknowledgments
 
-- Inspired by the need for better parallel development workflows
-- Built for the AI-assisted development era
-- Special thanks to all contributors
-
-## 🤝 Contributors
-
-- [@aku11i](https://github.com/aku11i) - Project creator and maintainer
-- [Claude (Anthropic)](https://claude.ai) - AI pair programmer who implemented most of the codebase
-
----
-
-<div align="center">
-Made with 👻 by <a href="https://github.com/aku11i">aku11i</a> and <a href="https://claude.ai">Claude</a>
-</div>
+Built with 👻 by [@aku11i](https://github.com/aku11i) and [Claude](https://claude.ai)