@akiojin/gwt 6.30.3 → 9.0.1

package/README.md

@@ -1,512 +1,232 @@
-# @akiojin/gwt
+# gwt
 
 [日本語](README.ja.md)
 
-Interactive Git worktree manager with Coding Agent selection (Claude Code / Codex CLI / Gemini CLI / OpenCode), graphical branch selection, and advanced workflow management.
+gwt is a terminal-based (TUI) tool for managing Git worktrees and launching
+coding agents (`Claude Code`, `Codex`, `Gemini`, `OpenCode`) on a project basis.
 
-## Overview
+## Install
 
-`@akiojin/gwt` is a powerful CLI tool that revolutionizes Git worktree management through an intuitive interface. It seamlessly integrates with Claude Code / Codex CLI / Gemini CLI / OpenCode workflows, providing intelligent branch selection, automated worktree creation, and comprehensive project management capabilities.
+Download the binary for your platform from
+[GitHub Releases](https://github.com/akiojin/gwt/releases) and place it in
+your `PATH`.
 
-## Migration Status
+### macOS
 
-The Rust implementation covers the core CLI/TUI workflow and the Web UI (REST + WebSocket terminal). The migration from TypeScript/Bun to Rust is complete. Remaining work is focused on documentation polish and continuous improvements.
-
-## Key Features
-
-- **Modern TUI**: Built with Ratatui for a smooth, responsive terminal interface
-- **Full-screen Layout**: Persistent header with repo context and boxed branch list
-- **Branch Summary Panel**: Real-time branch details panel with commit history, change stats, branch metadata, plus a Tab-switchable session summary view
-- **Smart Branch Creation**: Create feature, bugfix, hotfix, or release branches with guided prompts and automatic base branch selection
-- **Advanced Worktree Management**: Complete lifecycle management including creation, cleanup of worktree-backed branches, and path optimization
-- **Coding Agent Selection**: Choose between built-in agents (Claude Code / Codex CLI / Gemini CLI / OpenCode) or custom coding agents defined in `~/.gwt/tools.json`
-- **Coding Agent Integration**: Launch the selected agent in the worktree (Claude Code includes permission handling and post-change flow)
-- **GitHub PR Integration**: Automatic cleanup of merged pull request branches and worktrees
-- **Change Management**: Built-in support for committing, stashing, or discarding changes after development sessions
-- **tmux Multi-Agent Mode**: Run multiple coding agents in parallel using tmux panes (automatically enabled when running inside tmux)
-- **Universal Package**: Install once, use across all your projects with consistent behavior
-
-## Installation
-
-GitHub Releases are the source of truth for prebuilt binaries. The npm/bunx wrapper automatically downloads the matching release asset on install.
-
-### From GitHub Releases (Recommended)
-
-Download pre-built binaries from the [Releases page](https://github.com/akiojin/gwt/releases). Each release includes binaries for all supported platforms:
-
-- `gwt-linux-x86_64` - Linux x86_64
-- `gwt-linux-aarch64` - Linux ARM64
-- `gwt-macos-x86_64` - macOS Intel
-- `gwt-macos-aarch64` - macOS Apple Silicon
-- `gwt-windows-x86_64.exe` - Windows x86_64
+Run the installer:
 
 ```bash
-# Example for Linux x86_64
-curl -L https://github.com/akiojin/gwt/releases/latest/download/gwt-linux-x86_64 -o gwt
-chmod +x gwt
-sudo mv gwt /usr/local/bin/
+curl -fsSL https://raw.githubusercontent.com/akiojin/gwt/main/installers/macos/install.sh | bash
 ```
 
-### Via npm/bunx
-
-Install globally or run without installation:
+Install a specific version:
 
 ```bash
-# Global install
-npm install -g @akiojin/gwt
-bun add -g @akiojin/gwt
-
-# One-time execution
-npx @akiojin/gwt
-bunx @akiojin/gwt
+curl -fsSL https://raw.githubusercontent.com/akiojin/gwt/main/installers/macos/install.sh | bash -s -- --version 6.30.3
 ```
 
-### Via Cargo
-
-Install the CLI with Cargo:
+### Windows
 
-```bash
-# With cargo-binstall (faster, downloads prebuilt binary from GitHub Releases)
-cargo binstall gwt-cli
-
-# From GitHub (latest development version)
-cargo install --git https://github.com/akiojin/gwt --package gwt-cli --bin gwt --locked
+Download the binary from GitHub Releases and add it to your `PATH`.
 
-# Or, from a local checkout
-cargo install --path crates/gwt-cli
+### Linux
 
-# Or run directly from source
-cargo run -p gwt-cli
-```
+Download the binary from GitHub Releases and add it to your `PATH`.
 
-### Build from Source
+### Uninstall (macOS)
 
 ```bash
-# Clone the repository
-git clone https://github.com/akiojin/gwt.git
-cd gwt
-
-# Build release binary (default: gwt-cli)
-cargo build --release
-
-# Build all workspace crates (including web/wasm)
-cargo build --workspace
-
-# The binary is at target/release/gwt
-./target/release/gwt
+curl -fsSL https://raw.githubusercontent.com/akiojin/gwt/main/installers/macos/uninstall.sh | bash
 ```
 
-## Quick Start
+## Usage
 
-Run in any Git repository:
+Launch the TUI in the current directory:
 
 ```bash
-# If installed globally or in PATH
 gwt
-
-# Or use bunx for one-time execution
-bunx @akiojin/gwt
 ```
 
-CLI options:
+### Terminal requirements
+
+- 256-color terminal recommended (most modern terminals support this)
+- Minimum 80x24 terminal size
+
+## First-time usage
+
+1. Run `gwt` in a Git repository.
+2. Browse branches and worktrees in the sidebar.
+3. Use branch actions to:
+   - create/list/clean worktrees
+   - launch an agent
+4. Open **Settings** to set up AI profile settings if you use Agent or
+   summary features.
+
+## Key bindings
+
+Most TUI key bindings use the `Ctrl+G` prefix. Dragging terminal text copies
+the selection immediately.
+
+| Key binding | Action |
+|---|---|
+| `Ctrl+G`, `c` | New shell tab |
+| `Ctrl+G`, `n` | New agent tab |
+| `Ctrl+G`, `1`-`9` | Switch to tab N |
+| `Ctrl+G`, `]` | Next tab |
+| `Ctrl+G`, `[` | Previous tab |
+| `Ctrl+G`, `x` | Close current tab |
+| `Ctrl+G`, `w` | Worktree list |
+| `Ctrl+G`, `s` | Settings |
+| `Ctrl+G`, `?` | Help / key binding reference |
+| `Ctrl+G`, `q` | Quit |
+
+Drag across terminal text to copy it. When the host terminal forwards the
+shortcut, the platform copy shortcut also works:
+
+- macOS: `Cmd+C`
+- Linux / Windows: `Ctrl+Shift+C`
+
+To investigate Japanese IME candidate selection in a shell or agent terminal,
+launch gwt with `GWT_INPUT_TRACE_PATH=/tmp/gwt-input-trace.jsonl`. The JSONL
+trace records raw `crossterm` key events, keybind decisions, and forwarded PTY
+bytes without adding a runtime input-mode toggle.
+
+To compare that routed trace with raw terminal input, run
+`cargo run -p gwt-tui --example keytest -- --mode raw` in the same terminal.
+The probe logs every raw `crossterm::event::Event` to
+`/tmp/gwt-crossterm-events.jsonl` by default, or to the positional output path
+you pass.
+
+To isolate redraw-related IME regressions, the same probe also supports
+`--mode redraw` and `--mode ratatui`. `redraw` repaints the same committed-text
+surface on a periodic tick using direct `crossterm` commands, while `ratatui`
+uses the same surface through ratatui on the same tick. Use `--tick-ms <N>` to
+change the redraw interval when comparing modes.
+
+gwt also requests minimal kitty keyboard enhancements during terminal startup
+(`DISAMBIGUATE_ESCAPE_CODES | REPORT_ALL_KEYS_AS_ESCAPE_CODES |
+REPORT_ALTERNATE_KEYS | REPORT_EVENT_TYPES`) and pops them on shutdown.
+Unsupported terminals fail open and continue with existing behavior. Repeated
+key events from compatible terminals now stay on the same input path as normal
+key presses, which matters when IME candidate navigation advances to another
+page. While the terminal pane owns focus, idle 100 ms ticks now avoid repainting
+the TUI unless an overlay or other explicit periodic UI surface still needs
+animation, which reduces IME candidate interruption from background redraws.
+PTY output still requests an immediate redraw, so committed text and normal
+shell output are not delayed until the next keypress.
+
+## Environment and requirements
+
+### Required
+
+- `git` command available in `PATH`.
+
+### Optional (depends on use)
+
+- AI provider keys in environment variables (or saved in gwt profile settings):
+  - `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN`
+  - `OPENAI_API_KEY`
+  - `GOOGLE_API_KEY` or `GEMINI_API_KEY`
+- `bunx` or `npx` for local agent launch fallback.
+- Python 3.9+ on `PATH` when gwt needs to bootstrap or repair the shared project-index runtime
+  (for example during startup or repository initialization).
+  gwt bootstraps `~/.gwt/runtime/chroma-venv` automatically, then reuses that managed runtime.
+  On Windows, make sure either `python` or `py -3` works in Command Prompt or PowerShell.
+- Vector index data (SPECs / Issues / source files) is stored under `~/.gwt/index/<repo-hash>/`.
+  Issues and SPECs are repo-scoped and shared across worktrees; source files are worktree-scoped.
+  The TUI runs a per-Worktree filesystem watcher and refreshes the Issue index asynchronously
+  (15-minute TTL) at startup. The first search after a fresh install downloads the
+  `intfloat/multilingual-e5-base` embedding model (~440 MB) into `~/.cache/huggingface/`.
+  SPECs live as GitHub Issues labeled `gwt-spec` and are cached locally at
+  `~/.gwt/cache/issues/<repo-hash>/`; use `gwt issue spec <n>` to read and `gwt issue spec <n> --edit <section> -f <file>` to write.
+
+### Hook file ownership
+
+- gwt regenerates `.claude/settings.local.json` as a local machine file and manages its Git exclusion.
+- gwt creates or merges `.codex/hooks.json`, but does not add it to `.gitignore` or `info/exclude`.
+- Whether `.codex/hooks.json` is version-controlled is a repository decision. When the file already exists, gwt replaces only gwt-managed hook entries and keeps user hooks plus unrelated top-level settings.
+
+### GitHub Token (PAT) requirements
+
+gwt uses `gh` CLI for GitHub operations. Authenticate with:
 
 ```bash
-# Display help
-gwt --help
-
-# Check version
-gwt --version
-
-# List worktrees
-gwt list
-
-# Add worktree for existing branch
-gwt add feature/my-feature
-
-# Create new branch with worktree
-gwt add -n feature/new-feature --base develop
-
-# Remove worktree
-gwt remove feature/old-feature
-
-# Cleanup orphaned worktrees
-gwt clean
-
-# Show logs
-gwt logs --limit 100
-
-# Follow logs
-gwt logs --follow
+gh auth login
 ```
 
-The tool presents an interactive interface with the following options:
+#### Fine-grained PAT recommended permissions
 
-1. **Select Existing Branch**: Choose from local or remote branches with worktree auto-creation
-2. **Create New Branch**: Guided branch creation with type selection (feature/bugfix/hotfix/release)
-3. **Manage Worktrees**: View, open, or remove existing worktrees
-4. **Cleanup Branches**: Remove merged PR branches or branches identical to their base directly from the CLI (branches without worktrees are excluded)
-
-## Keyboard Shortcuts
-
-### Branch List Screen
-
-| Key | Action |
-|-----|--------|
-| `Enter` | Focus existing agent pane / Show hidden pane / Open wizard |
-| `d` | Delete agent pane (with confirmation) |
-| `v` | Open GitView (git status details for selected branch) |
-| `Space` | Select/Deselect branch |
-| `Up/Down` | Navigate branches |
-| `PageUp/PageDown` | Page navigation |
-| `Home/End` | Jump to first/last branch |
-| `f` | Enter filter mode |
-| `r` | Refresh branch list |
-| `c` | Cleanup merged branches |
-| `l` | View logs |
-| `?` | Help |
-| `q` / `Ctrl+C` | Quit |
-
-Mouse:
-- Double-click a branch row to trigger the Enter action (focus pane / open wizard).
-
-### Filter Mode
-
-| Key | Action |
-|-----|--------|
-| `Esc` | Exit filter mode |
-| Type | Filter branches by name |
-
-### GitView Screen
-
-The GitView screen shows detailed git status for a branch, including files and recent commits.
-
-| Key | Action |
-|-----|--------|
-| `Up/Down` | Navigate files and commits |
-| `Space` | Expand/collapse file diff or commit details |
-| `Enter` | Open PR link in browser (when focused on header) |
-| `v` / `Esc` | Return to branch list |
-
-Mouse:
-- Click on the PR link in the header to open it in your browser.
-
-## Status Icons Legend
-
-| Icon | Color | Meaning |
-|------|-------|---------|
-| `o` | Green | Safe - No uncommitted or unpushed changes |
-| `!` | Red | Uncommitted - Has local changes |
-| `^` | Yellow | Unpushed - Has commits not pushed to remote |
-| `*` | Yellow | Unmerged - Has unmerged changes |
-
-## Agent Status Display
-
-In the branch list, running agents are displayed on the right side:
-
-| Format | Meaning |
-|--------|---------|
-| `[/] Claude 01:23:45` | Running agent (spinner, name, uptime) |
-| `[BG] Claude 01:23:45` | Hidden (background) agent (grayed out) |
-
-## Coding Agents
-
-gwt detects agents available on PATH and lists them in the launcher.
-
-Supported agents (built-in):
-
-- Claude Code (`claude`)
-- Codex CLI (`codex`)
-- Gemini CLI (`gemini`)
-- OpenCode (`opencode`)
-
-### Custom coding agents
-
-Custom agents are defined in `~/.gwt/tools.json` and will appear in the launcher.
-
-Minimal example:
-
-```json
-{
-  "version": "1.0.0",
-  "customCodingAgents": [
-    {
-      "id": "aider",
-      "displayName": "Aider",
-      "type": "command",
-      "command": "aider",
-      "defaultArgs": ["--no-git"],
-      "modeArgs": {
-        "normal": [],
-        "continue": ["--resume"],
-        "resume": ["--resume"]
-      },
-      "permissionSkipArgs": ["--yes"],
-      "env": {
-        "OPENAI_API_KEY": "sk-..."
-      },
-      "models": [
-        { "id": "gpt-4o", "label": "GPT-4o" },
-        { "id": "claude-3-opus", "label": "Claude 3 Opus" }
-      ],
-      "versionCommand": "aider --version"
-    }
-  ]
-}
-```
-
-Notes:
-
-- `type` supports `path`, `bunx`, or `command`.
-- `modeArgs` defines args per execution mode (Normal/Continue/Resume).
-- `env` is optional per-agent environment variables.
-- `models` is optional. If defined, model selection step will be shown for this agent.
-- `versionCommand` is optional. If defined, version detection will use this command instead of skipping version selection.
-
-## Bare Repository Workflow
-
-gwt supports a bare repository workflow for efficient worktree management. This approach keeps the bare repository (`.git` data) separate from worktrees, providing cleaner project organization.
-
-### Directory Structure
-
-```text
-/project/
-├── repo.git/           # Bare repository
-├── main/               # Worktree (main branch)
-├── feature-x/          # Worktree (feature/x branch)
-└── .gwt/               # gwt configuration
-    └── project.json
-```
-
-### Setting Up a Bare Repository
-
-```bash
-# Clone as bare repository
-git clone --bare https://github.com/user/repo.git repo.git
+| Permission | Access | Used for |
+|---|---|---|
+| **Contents** | Read and Write | Repository browsing, branch operations, releases |
+| **Pull requests** | Read and Write | PR create / edit / merge / review |
+| **Issues** | Read and Write | Issue create / edit / comment |
+| **Metadata** | Read | Implicitly granted |
 
-# Create worktrees from bare repository
-cd repo.git
-git worktree add ../main main
-git worktree add ../feature-x feature/x
-```
-
-### Using gwt with Bare Repositories
-
-When you run gwt in a bare repository or its worktrees:
-
-| Location | Header Display |
-|----------|----------------|
-| Normal repository | `Working Directory: /path [branch]` |
-| Bare repository | `Working Directory: /path/repo.git [bare]` |
-| Worktree (normal) | `Working Directory: /path [branch]` |
-| Worktree (bare-based) | `Working Directory: /path [branch] (repo.git)` |
-
-### Migration from `.worktrees/` Method
-
-If you have an existing repository using the `.worktrees/` directory method, gwt will detect this and offer migration to the bare repository method:
+#### Read-only minimum
 
-1. **Backup**: Creates backup in `.gwt-migration-backup/`
-2. **Create bare repo**: Creates `{repo-name}.git`
-3. **Migrate worktrees**: Moves existing worktrees to new structure
-4. **Cleanup**: Removes old `.worktrees/` directory
-5. **Configure**: Creates `.gwt/project.json`
+For browse-only usage (no PR creation or branch management):
 
-### Submodule Support
+| Permission | Access |
+|---|---|
+| **Contents** | Read |
+| **Pull requests** | Read |
+| **Issues** | Read |
+| **Metadata** | Read |
 
-When creating worktrees, gwt automatically initializes submodules if present. This ensures submodules are ready to use immediately after worktree creation.
+### Optional advanced toggles
 
-## Advanced Workflows
+- `GWT_AGENT_AUTO_INSTALL_DEPS` (`true` / `false`)
+- `GWT_DOCKER_FORCE_HOST` (`true` / `false`)
 
-### Branch Strategy
+### Logging and profiling
 
-This repository follows a structured branching strategy:
-
-- **`main`**: Production-ready code. Protected branch for releases only.
-- **`develop`**: Integration branch for features. All feature branches merge here.
-- **`feature/*`**: New features and enhancements. **Must be based on and target `develop`**.
-- **`hotfix/*`**: Critical production fixes. Based on and target `main`.
-- **`release/*`**: Release preparation branches.
-
-**Important**: When creating feature branches, always use `develop` as the base branch:
-
-```bash
-# Correct: Create feature branch from develop
-git checkout develop
-git pull origin develop
-git checkout -b feature/my-feature
-
-# Or use this tool which handles it automatically
-gwt
-# → Select "Create new branch" → "feature" → automatically uses develop as base
-```
-
-### Branch Creation Workflow
-
-> **Important**: This workflow is intended for human developers. Autonomous agents must never create or delete branches unless a human gives explicit, task-specific instructions.
-
-1. Select "Create new branch" from the main menu
-2. Choose branch type (feature, bugfix, hotfix, release)
-3. Enter branch name with automatic prefix application
-4. Select base branch from available options (feature → develop, hotfix → main)
-5. Confirm worktree creation path
-6. Automatic worktree setup and selected tool launch
-
-### Worktree Management
-
-- **Open Existing**: Launch the selected tool in existing worktrees
-- **Remove Worktree**: Clean removal with optional branch deletion
-- **Batch Operations**: Handle multiple worktrees efficiently
-
-### GitHub Integration
-
-- **Branch Cleanup**: Automatically detect and remove merged pull request branches or branches that no longer differ from their base
-- **Authentication Check**: Verify GitHub CLI setup before operations
-- **Remote Sync**: Fetch latest changes before cleanup operations
-
-## System Requirements
-
-- **Rust**: Stable toolchain (for building from source)
-- **Git**: Latest version with worktree support
-- **Coding Agent**: At least one built-in agent or a custom coding agent should be available
-- **GitHub CLI**: Required for PR cleanup features (optional)
-- **bun/npm**: Required for bunx/npx execution method
-
-## Project Structure
-
-```text
-@akiojin/gwt/
-├── Cargo.toml           # Workspace configuration
-├── crates/
-│   ├── gwt-cli/         # CLI entry point and TUI (Ratatui)
-│   ├── gwt-core/        # Core library (worktree management)
-│   ├── gwt-web/         # Web server (Axum)
-│   └── gwt-frontend/    # Web frontend (Leptos CSR)
-├── package.json         # npm distribution wrapper
-├── bin/gwt.js           # Binary wrapper script
-├── scripts/postinstall.js  # Binary download script
-├── specs/               # Feature specifications
-└── docs/                # Documentation
-```
+Normal logs are stored per project as JSON Lines under `~/.gwt/logs/<repo-hash>/gwt.log.YYYY-MM-DD`. Performance profiling can be enabled in **Settings > Profiling**.
+See [#1758](https://github.com/akiojin/gwt/issues/1758) for the logging specification.
 
 ## Development
 
-### Setup
+### Build
 
 ```bash
-# Clone the repository
-git clone https://github.com/akiojin/gwt.git
-cd gwt
-
-# Build the project
-cargo build
-
-# Run tests
-cargo test
-
-# Run with debug output
-cargo run
+cargo build -p gwt-tui
 ```
 
-### Available Commands
+### Run (development)
 
 ```bash
-# Development build
-cargo build
-
-# Release build
-cargo build --release
-
-# Run tests
-cargo test
-
-# Run clippy lints
-cargo clippy --all-targets --all-features -- -D warnings
-
-# Format code
-cargo fmt
-
-# Run the CLI locally
-cargo run
+cargo run -p gwt-tui
 ```
 
-### Development Workflow
-
-1. **Fork and Clone**: Fork the repository and clone your fork
-2. **Create Branch**: Use the tool itself to create a feature branch
-3. **Development**: Make changes with Rust
-4. **Testing**: Test CLI functionality with `cargo run`
-5. **Quality Checks**: Run `cargo clippy` and `cargo fmt --check`
-6. **Pull Request**: Submit a PR with clear description
-
-### Code Structure
-
-- **Entry Point**: `crates/gwt-cli/src/main.rs` - Main application logic
-- **Core Modules**: Git operations, worktree management in `gwt-core`
-- **TUI Components**: Ratatui-based interface in `gwt-cli/src/tui/`
-- **Type Safety**: Comprehensive Rust type definitions
-- **Error Handling**: Robust error management with `thiserror`
-
-## Release Process
-
-End users can install the latest published package (via npm or the GitHub Releases tab). Maintainers should follow the release flow requirements in `specs/SPEC-77b1bc70/spec.md`.
-
-## Troubleshooting
-
-### Common Issues
-
-**Permission Errors**: Ensure proper directory permissions
-**Git Worktree Conflicts**: Use the cleanup feature to remove stale worktrees
-**GitHub Authentication**: Run `gh auth login` before using PR cleanup features
-**Binary Not Found**: Ensure the gwt binary is in your PATH
-**Unicode Character Corruption in Docker + tmux**: If Unicode characters (like the Claude Code logo) appear as underscores in Docker containers with tmux, start tmux with UTF-8 mode:
+### Test
 
 ```bash
-tmux -u
+cargo test -p gwt-core -p gwt-tui
 ```
 
-Or add to your `~/.tmux.conf`:
+### Lint
 
-```
-set -gq utf8 on
+```bash
+cargo clippy --all-targets --all-features -- -D warnings
 ```
 
-You may also need to install and configure locales in your Docker container:
+### Format
 
 ```bash
-apt-get update && apt-get install -y locales
-sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen
-locale-gen
-export LANG=en_US.UTF-8
-export LC_ALL=en_US.UTF-8
+cargo fmt
 ```
 
-### Debug Mode
-
-For verbose output, set the environment variable:
+## Project structure
 
-```bash
-GWT_DEBUG=1 gwt
+```text
+├── Cargo.toml          # Workspace configuration
+├── crates/
+│   ├── gwt-core/       # Core library (Git operations, PTY management, config)
+│   ├── gwt-github/     # GitHub Issue SOT for SPEC management (SPEC-12)
+│   └── gwt-tui/        # ratatui TUI frontend + CLI dispatch (`gwt issue spec ...`)
+└── package.json        # Development scripts
 ```
 
 ## License
 
-MIT - See LICENSE file for details
-
-## Contributing
-
-We welcome contributions! Please read our contributing guidelines:
-
-1. **Issues**: Report bugs or request features via GitHub Issues
-2. **Pull Requests**: Follow the development workflow above
-3. **Code Style**: Maintain Rust best practices and existing patterns
-4. **Documentation**: Update README and code comments for significant changes
-
-### Contributors
-
-- AI Novel Project Team
-- Community contributors welcome
-
-## Support
-
-- **Documentation**: This README and inline code documentation
-- **Issues**: GitHub Issues for bug reports and feature requests
-- **Discussions**: GitHub Discussions for questions and community support
+MIT