Skip to main content

Keep your tasks open

Use a worktree for each task you need to leave and return to. The commands below assume shell integration is loaded.

Start a feature​

gji new feature/search

This creates a branch and worktree, runs supported dependency setup, and takes your shell to that directory. Your previous worktree keeps its files.

To open an editor at the same time:

gji new feature/search --open --editor cursor

Choose code, zed, or another installed editor CLI as needed. Once you save a default with gji open --editor cursor --save, --editor is optional.

By default, new branches start from the main worktree. To include commits from the worktree you are currently in:

gji new feature/search-tests --from-current

This uses its HEAD; it doesn't carry uncommitted files. To deliberately move those files into a new worktree, use --take. Add --copy to leave them in the original worktree as well:

gji new feature/search-fix --take
gji new feature/search-copy --take --copy

Choose one of those commands for the outcome you need.

Review a PR without packing up your changes​

gji pr 1234
# Or: gji pr https://github.com/org/repo/pull/1234

Use a real PR number or URL from your repository. The review gets its own worktree and dependency setup. Return with:

gji back

To open the hosted page for the PR in your current worktree:

gji pr open

Use gji pr open --select to choose a PR from another linked worktree.

Find the work you left open​

gji # see the repository hub
gji go # choose a destination
gji go feature/payments # go to a known branch
gji back # return to the previous worktree

The chooser starts in the current repository. Press Tab to include all registered repositories. Search by branch, path, PR, or task text with /. Use repo/branch when several repositories have the same branch name:

gji go api/main

For a longer navigation history, use gji history and gji back 2. Use gji root to return to the main repository checkout.

Open your editor and label the task​

gji open
gji task "Add payment retries"

The task description appears in interactive pickers, so a branch name doesn't have to carry all the context. Clear it with gji task --clear.

gji open targets the current worktree. Use gji open --select to choose another, or gji open feature/payments to name it directly. For VS Code, Cursor, or Windsurf, --workspace generates a .code-workspace file before opening.

Give experiments their own files​

gji new --detached

Detached worktrees let you investigate without naming a branch first. Create a branch with Git before you need a named place for commits. --detached cannot be combined with --from-current.

For coding agents, create a separate worktree for each task, then start your usual tool in that directory. Worktrees separate files; they don't isolate shared services, databases, or listening ports.

Reuse a worktree when you don't need another directory​

gji new feature/next-task --branch-only

This requires a clean current worktree. It refreshes the configured remote default branch and creates the new branch in place, without another worktree or dependency setup. Use --no-fetch to use the local default branch instead.

Use this for sequential work. Use a separate worktree when a task needs to stay open while you work elsewhere.

Update or finish a task​

gji sync

This fetches and rebases the current branch onto the configured default branch. When a task is finished, review its files and branch state before removing it:

gji done feature/search

Cleanup can remove both the worktree and its branch. See sync and cleanup for --keep-branch, previews, and the limits of undo.