hjWorktree CLI

Web-based git worktree manager for running multiple AI coding agents in parallel.

Features

• Multiple Terminals: Run multiple terminal sessions in parallel across git worktrees
• AI Agent Ready: Execute any AI coding agent (Claude Code, Codex CLI, Gemini CLI, etc.) directly in terminals
• Git Worktree Management: Create, manage, and delete worktrees with automatic cleanup
• Real-time Terminal: xterm.js terminals with full PTY support via Socket.IO
• Session Management:
  • Always-visible LNB (Left Navigation Bar) for session navigation
  • Branch-grouped session display
  • Individual and bulk session deletion
  • Add new worktrees while sessions are running
• Modern Web UI: React + Zustand state management
• Auto Port Detection: Automatically finds available port when running multiple instances

Installation

npm install -g hjworktree-cli

Requirements: Node.js >= 20.0.0

Usage

Navigate to your git repository and run:

cd /path/to/your/project
hjWorktree

This opens a web UI in your browser where you can:

Running Multiple Projects

You can run hjWorktree in multiple projects simultaneously. The CLI automatically detects available ports:

# Project A - uses default port 3847
cd /path/to/project-a && hjWorktree

# Project B - automatically uses port 3848
cd /path/to/project-b && hjWorktree

# Or specify a custom port
PORT=5000 hjWorktree

1. Select Branch: Choose the base branch for worktrees
2. Set Worktree Count: Specify how many parallel worktrees to create
3. Run: Launch terminals in each worktree, then run your preferred AI agent

UI Overview

+---------------------------+-----------------------------------+
|  SETUP            [−]     |                                   |
|  ① Branch: main           |                                   |
|  ② Count: 3               |        Terminal View              |
+---------------------------+                                   |
|  SESSIONS                 |   $ claude                        |
|  ▼ main (3)               |   > Ready to help!                |
|    ● main-project-1       |                                   |
|    ○ main-project-2       |                                   |
|    ○ main-project-3       |                                   |
|                           |                                   |
|  [+ Add Session]          |                                   |
+---------------------------+-----------------------------------+

Supported AI Agents

Run any AI coding agent directly in your terminals:

| Agent | Command | Description | |-------|---------|-------------| | Claude Code | claude | Anthropic Claude Code agent | | Codex CLI | codex | OpenAI Codex CLI agent | | Gemini CLI | gemini | Google Gemini CLI agent |

Simply type the agent command in any terminal session to start coding with AI assistance.

Development

# Clone and install
git clone https://github.com/user/hjworktree-cli.git
cd hjworktree-cli
npm install

# Development mode (server + web)
npm run dev

# Build for production
npm run build

# Run production server
npm run start

Architecture

hjWorktree-cli/
├── bin/cli.js           # CLI entry point
├── server/              # Express + Socket.IO backend
│   ├── index.ts         # Server entry
│   ├── socketHandlers.ts # Terminal PTY management
│   ├── routes/api.ts    # REST API
│   └── services/        # Git/Worktree services
├── web/                 # React frontend
│   ├── src/components/  # UI components
│   ├── src/hooks/       # Custom hooks
│   └── src/stores/      # Zustand stores
└── shared/              # Shared types/constants

API Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/info | Project info | | GET | /api/branches | List branches | | POST | /api/worktrees | Create worktrees | | POST | /api/worktrees/single | Create single worktree | | DELETE | /api/worktrees/:name | Delete worktree | | DELETE | /api/worktrees/batch | Batch delete worktrees | | DELETE | /api/worktrees | Delete all worktrees |

Changelog

v2.5.0

• Auto Port Detection: Automatically finds available port (range 3847-3856) when default port is in use
• Multi-Project Support: Run hjWorktree in multiple projects simultaneously without port conflicts
• Custom Port: Support PORT environment variable for explicit port specification

v2.4.0

• Simplified Workflow: Removed AI agent selection step (3-step wizard: Branch → Count → Run)
• Pure Terminal: Terminals now open as shell, run any AI agent manually (claude, codex, gemini)
• Session Fix: Fixed session duplication bug on page refresh

v2.3.0

• macOS Fix: Resolved posix_spawnp failed error on global installation
• node-pty Update: Upgraded from v1.0.0 to v1.1.0 with spawn-helper fix
• Path Normalization: Added symlink resolution for cwd (e.g., /tmp → /private/tmp on macOS)
• Shell Resolution: Improved shell path resolution with symlink handling and PATH fallback
• Environment Sanitization: Added filtering of undefined/null values from environment variables
• Postinstall Script: Auto-fix spawn-helper execute permissions on macOS/Linux

v2.2.0

• Security Fix: Added critical protection guards to prevent accidental deletion of main repository's .git folder during worktree cleanup
• Session Reliability: Added path and shell validation before PTY spawn
• PTY Stability: Added retry logic with exponential backoff for PTY spawn failures
• Resource Protection: Added spawn interval control (150ms minimum) to prevent resource contention when creating multiple terminals

v2.1.0

• Improved LNB with session management and always-visible navigation
• Implemented wizard navigation with LNB
• Rebuilt as web-based application

License

MIT

Author

hyungju-lee [email protected]