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.