User Guide

1 Create a Workspace

After launching the app, you'll need to create or import a workspace on first use:

• New Workspace: Select an empty directory and the app will initialize it automatically
• Import Existing Project: Select a directory containing Git projects

2 Add a Project

Add Git projects to your workspace using any of these three methods:

3 Create a Worktree

Click the + button in the sidebar and follow the wizard:

1. Enter a branch name (e.g. feature/login)
2. Choose which branch to base it on (defaults to main)
3. Select the projects to include
4. Configure folders to link (e.g. node_modules)
5. Click "Create" and wait for it to finish

4 Start Developing

From the Worktree list:

• Click Open IDE: opens in VS Code / Cursor / IDEA
• Click Terminal: run commands in the built-in terminal
• Click the folder icon: open in your file manager

Multi-Window Workflow

Each Workspace can be opened in its own independent window, letting you work on multiple workspaces simultaneously without interference.

• In the sidebar Workspace list, click the external link icon (↗️) next to a Workspace name to open it in a new window
• Each window runs independently -- you can view and operate different Workspaces at the same time
• When the main window closes, child windows close as well

Window Title

The window title dynamically shows the current workspace and branch info in this format:

This makes it easy to tell windows apart when working with multiple workspaces.

Worktree Locking

When a Worktree is already open in one window, it shows as "occupied" in other windows.

• An occupied Worktree cannot be operated on from another window, preventing conflicts
• Switching to a different Worktree automatically releases the lock on the current one
• Closing a window automatically releases all locks held by that window

Built-in Terminal

Each Worktree has its own built-in terminal with the working directory automatically set to the Worktree root. No need to cd manually.

• The terminal panel is at the bottom of the app and can be resized by dragging
• Switching Worktrees automatically switches to the corresponding terminal session
• Terminal sessions persist throughout the Worktree lifecycle and won't be lost when switching

Multiple Tabs

Each Worktree can have multiple terminal tabs:

• Click the + button in the terminal panel to create a new tab
• Click a tab to switch between terminal sessions
• Click the x button on a tab to close that terminal
• Each tab runs as an independent terminal process

Fullscreen Mode

The terminal supports fullscreen mode for when you need more space:

• Click the maximize icon in the top-right corner of the terminal panel to enter fullscreen
• Press Escape to exit fullscreen mode
• In fullscreen mode, the terminal fills the entire application window

External Terminal

If you prefer your system's native terminal, click the "Open in External Terminal" button in the terminal panel. It will open your default terminal app and navigate to the Worktree directory automatically.

Overview

Voice input is powered by Alibaba Cloud Dashscope Paraformer real-time speech recognition. Speak into your microphone and your speech is transcribed in real time and injected into the current terminal. Great for hands-free scenarios or quick command entry.

Two operation modes are supported:

• Push-to-Talk: Hold Alt+V to speak, release to stop recording and transcribe
• Click to Toggle: Click the microphone icon in the terminal panel to enter standby mode, then hold Alt+V to speak

Configuring Dashscope

Before using voice input, you need to configure a Dashscope API Key:

1. Open the Settings page (gear icon)
2. Scroll to the "Speech Recognition (Dashscope)" section
3. Go to the Dashscope Console to get your API Key
4. Paste the API Key into the input field and click "Save"
5. Click the "Test Connection" button to verify the configuration

Microphone Settings

In the Speech Recognition section of Settings, you can manage microphone devices:

• Select Microphone: A dropdown lists all available audio input devices. You can choose a specific microphone (e.g. external mic, headset mic). Defaults to the system default device
• Microphone Test: Click the "Test" button to see a real-time volume meter. Speak into the mic to confirm it's working. The test stops automatically after 10 seconds
• Connection Test: Click "Test Connection" to verify the API Key and WebSocket address are configured correctly. A green "Connection Successful" message appears on success

Usage Flow

1. Click the microphone icon in the top-right of the terminal panel to enter standby mode (icon turns blue, microphone is active)
2. Hold Alt+V to start speaking -- connects to Dashscope and streams audio in real time
3. Release Alt+V to stop recording -- the transcription is automatically typed into the terminal
4. You can press and release repeatedly for multiple voice inputs while the mic stays in standby
5. Click the microphone icon again to exit standby mode and release the microphone

Voice Commands

In addition to regular text transcription, the following voice command keywords trigger terminal actions when spoken:

Example: Hold Alt+V and say git status, release, then hold again and say enter -- this types git status in the terminal and presses Enter to execute.

AI Voice Refinement

Voice transcriptions often contain filler words ("um", "uh", "like", "you know") and grammatical errors. The AI Voice Refinement feature integrates the Qwen large language model to automatically polish transcribed text:

• Remove Filler Words: Automatically detects and removes meaningless words like "um", "uh", "like", etc.
• Grammar Correction: Converts colloquial expressions into proper command format
• Preserve Intent: The refinement process keeps the original meaning intact without changing command semantics

Mobile Voice Input

In browser remote mode (accessing from phone/tablet), the terminal panel provides a dedicated push-to-talk button:

• Long-press to Talk: Long-press the microphone button at the bottom of the terminal to start recording, release to stop
• Touch Optimized: Button size and interactions are optimized for touchscreens -- operable with one hand
• AI Refinement Included: Mobile voice input also goes through AI refinement processing

Supported IDEs

Worktree Manager supports a variety of popular IDEs and editors:

Switch Default IDE

In the Worktree detail view, click the dropdown arrow next to the IDE button to see the IDE selection list:

• Selecting an IDE makes it the default for the current project
• Next time you click the IDE button, it will open with the last selected IDE
• Different projects can have different default IDEs

Quick Open

In the IDE dropdown menu, each IDE option has a quick-open icon (↗️) on the right:

• Clicking the icon opens the project with that IDE without changing the default IDE setting
• Handy for occasionally opening with a different IDE

Open in File Manager

At the bottom of the IDE dropdown menu, there's an "Open in File Manager" option that opens the Worktree's project directory in your system file manager (Finder / File Explorer).

Overview

Smart Folder Scan automatically detects large folders in your project that are good candidates for linking, helping you quickly configure linked_folders.

Once linked, newly created Worktrees will automatically symlink these folders from the main repository -- no need to reinstall dependencies or rebuild, saving significant disk space and time.

How to Use

1. Go to the Workspace Settings page
2. Find the Linked Folders configuration for your project
3. Click the scan button (magnifying glass icon)
4. The system will automatically scan the project directory and list all linkable folders
5. Check the folders you want to link and confirm

Auto-Detected Folder Types

The scan automatically identifies these common large folders:

Overview

Remote sharing lets you share your current workspace via browser with colleagues. They don't need to install anything -- just open the link to view your Worktrees, use the terminal, and even collaborate on development.

Sharing supports three modes: LAN direct connection (same Wi-Fi / intranet), WMS built-in tunnel (no extra tools needed), and ngrok tunneling (using the ngrok service).

Enable Sharing

In the desktop app, follow these steps to enable sharing:

1. Find the "Share" button at the bottom of the sidebar and click to open the sharing panel
2. Set the port number (recommended range: 49152-65535, also supports dev ports 3000-9999)
3. Set an access password (required, protects your workspace)
4. Click "Start Sharing" -- the system will start a built-in HTTP server
5. Once sharing is active, a LAN access URL will be displayed (e.g. http://192.168.1.100:49152)

Browser Mode Access

When a collaborator opens the shared link:

1. The browser shows a password entry page -- enter the password you set to gain access
2. Once inside, they see the same interface as the desktop app, including the Worktree list and branch status
3. They can use the built-in terminal (streamed in real time via WebSocket)
4. They can join collaboration and share terminal sessions with the desktop user
5. All operations sync in real time via WebSocket with minimal latency

ngrok Internet Tunneling

If your collaborator isn't on the same LAN, you can use ngrok for internet tunneling to access via a public URL:

Step 1: Install ngrok and Get a Token

1. Go to ngrok.com and create a free account
2. Copy your Authtoken from the ngrok Dashboard

Step 2: Configure the Token in the App

1. Open the Settings page (gear icon)
2. Scroll to the bottom and find the "Internet Sharing (ngrok)" section
3. Paste the Authtoken into the input field and click "Save"

Step 3: Enable the Internet Tunnel

1. First enable LAN sharing as described above
2. In the sharing panel, click the "Enable Internet" button
3. Wait for the ngrok tunnel to establish (usually takes a few seconds)
4. The generated public URL (e.g. https://xxxx.ngrok-free.app) can be shared with anyone

WMS Built-in Tunnel

In addition to ngrok, Worktree Manager includes a built-in WMS tunnel service that enables public access without installing any extra tools:

1. First enable LAN sharing as described above
2. In the sharing panel, click the "WMS Tunnel" button
3. The system will automatically connect to tunnel.kirov-opensource.com and assign a unique subdomain
4. The generated public URL (e.g. https://your-name.tunnel.kirov-opensource.com) can be shared with anyone

QR Code Sharing

Once sharing is enabled, the sharing panel automatically generates a QR code for the current share URL:

• Scan to Access: Scan the QR code with your phone/tablet to open the workspace directly in a mobile browser
• Embedded Password: The QR code link can embed the access password (via URL fragment), so scanning auto-authenticates without manual password entry
• All Modes Supported: LAN, WMS tunnel, and ngrok modes all support QR code generation

Client Management

The sharing panel lets you view and manage all connected clients in real time:

• Connection List: Shows all connected browser clients with IP address, connection time, and other details
• Kick Session: You can kick individual client sessions -- kicked users must re-enter the password to reconnect
• Password Update: Changing the password automatically kicks all connected clients

Security Considerations

Sharing Troubleshooting

# Check port usage (macOS/Linux)
lsof -i :49152

Global Configuration

Location: ~/.config/worktree-manager/global.json

{
  "workspaces": [
    { "name": "My Project", "path": "/path/to/workspace" }
  ],
  "current_workspace": "/path/to/workspace",
  "ngrok_token": "2abc...xyz",
  "last_share_port": 49152
}

Workspace Configuration

Location: {workspace}/.worktree-manager.json

{
  "name": "My Project",
  "worktrees_dir": "worktrees",
  "linked_workspace_items": [".claude", "CLAUDE.md"],
  "projects": [
    {
      "name": "frontend",
      "base_branch": "main",
      "test_branch": "test",
      "merge_strategy": "merge",
      "linked_folders": ["node_modules", ".next"]
    }
  ]
}