Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.termpad.com/llms.txt

Use this file to discover all available pages before exploring further.

Worktrees are the core feature of Termpad—isolated workspaces where you run AI agents in parallel. Each worktree has its own copy of your codebase, terminal, and branch, so multiple AI agents can work simultaneously without interfering with each other.

​
Why Worktrees Matter

Traditional AI coding workflows are sequential: give an AI a task, wait for it to finish, review, then start the next. This wastes time. With worktrees, while one AI builds a feature, you can have others tackling different tasks in parallel.
ComponentIsolation
Git worktreeEach worktree has its own copy of the codebase
TerminalSeparate terminal instance per worktree
BranchEach worktree works on its own branch
PortsConfigurable port assignments to avoid conflicts
Worktrees share the same git history, but file changes are isolated until you merge.

​
Prerequisites

  • A project added to Termpad
  • Understanding of what you want the worktree to accomplish

​
Creating a New Worktree

1

Select your project

Click on the project in the sidebar where you want to create a worktree.
2

Click Add Worktree

Click the Add Worktree button.
3

Enter a branch name

Type a descriptive branch name. Good naming conventions:
  • feature/login-page
  • fix/null-pointer-error
  • refactor/api-client
  • experiment/new-caching
4

Choose a base branch

By default, new branches are based on origin/main. Select a different base if needed.
5

Wait for setup

Termpad creates the worktree and runs your setup script. This may take a moment depending on your script.

​
Worktree Anatomy

Each worktree includes:
ComponentDescription
Git worktreeIsolated copy of your codebase on a separate branch
Main terminalWhere you run your AI agent (Claude, Gemini, etc.)
User terminalsAdditional terminals for dev servers, tests, etc.
File changesShows uncommitted changes in this worktree
Diff viewerReview changes before committing

​
Using an Existing Worktree

If you want to import worktrees that already exist:
1

Open Add Worktree

Click the Add Worktree button.
2

Click the Import tab

Select the Import tab in the dialog.
3

Select worktrees to import

Termpad auto-detects all existing worktrees. Choose which ones to import/add.

​
Worktree Workflow

A typical worktree workflow:
1

Create worktree

Create a new worktree with a clear purpose.
2

Launch AI agent

Start Claude Code, Gemini, or your preferred tool:
claude
3

Give the AI a task

Describe what you want to build or fix.
4

Monitor and assist

Answer questions, review progress, redirect as needed.
5

Review changes

Use the diff viewer to review what the AI created.
6

Commit and push

Stage, commit, and push your changes.
7

Create PR

Open a pull request for code review.
8

Delete worktree

Clean up the worktree when you’re done.

​
Managing Multiple Worktrees

Create additional worktrees to work in parallel:
1

Create more worktrees

Repeat the worktree creation process for each task.
2

Switch between worktrees

Click any worktree in the sidebar to switch to it.
3

Monitor status

The sidebar shows status indicators:
  • Active (running processes)
  • Waiting (needs input)
  • Idle (no activity)

​
Deleting a Worktree

When a worktree’s work is complete:
1

Commit your work

Make sure all changes are committed and pushed.
2

Delete the worktree

Click the options icon on the worktree, then click Remove worktree.
3

Cleanup

Termpad runs cleanup scripts and removes the worktree.
Deleting a worktree removes all uncommitted changes in that worktree. Always commit first!

​
Best Practices

​
Choose independent tasks

For best results, choose tasks that don’t overlap:
  • Worktree 1: Build login page
  • Worktree 2: Build settings page
  • Worktree 3: Add API rate limiting
These tasks touch different files and won’t conflict.

​
One task per worktree

Keep worktrees focused on a single task. This makes:
  • Progress easier to track
  • Changes easier to review

​
Use descriptive branch names

Your branch name should describe the work:
TypeExample
Featurefeature/user-authentication
Bug fixfix/login-redirect-loop
Refactorrefactor/extract-api-client
Experimentexperiment/graphql-migration

​
Clean up finished worktrees

Don’t let old worktrees accumulate. Delete them when:
  • The PR is merged
  • You’ve decided not to pursue the work
  • The experiment is complete
This frees up disk space and keeps your workspace tidy.