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

``bash
npm install -g hjworktree-cli
`

Requirements: Node.js >= 20.0.0

Usage

Navigate to your git repository and run:

`bash
cd /path/to/your/project
hjWorktree
`

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

$3

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

`bash


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

`bash


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

$3


- 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

$3

- 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

$3

- 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

$3

- 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

$3

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

License

MIT

Author

hyungju-lee