Web-based git worktree parallel AI coding agent runner
npm install hjworktree-cliWeb-based git worktree manager for running multiple AI coding agents in parallel.
- 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
``bash`
npm install -g hjworktree-cli
Requirements: Node.js >= 20.0.0
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:
You can run hjWorktree in multiple projects simultaneously. The CLI automatically detects available ports:
`bashProject A - uses default port 3847
cd /path/to/project-a && 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 installDevelopment mode (server + web)
npm run devBuild for production
npm run buildRun 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 cleanupMIT
hyungju-lee