Skip to main content

Daily workflow

This is the core reason to use gji: you stop treating one checkout as shared mutable state for every task.

That becomes even more valuable when you work in parallel across your own changes, pull request review, and AI-assisted experiments.

Start a new feature​

gji new feature/auth-refactor

This creates:

  • a branch
  • a linked worktree
  • an immediate shell handoff when integration is enabled

If you use project hooks, this is also where install/setup automation typically runs.

To open the new worktree in an editor immediately:

gji new feature/auth-refactor --open --editor cursor

Once you have a saved editor (gji open --save), --editor is optional.

Open a pull request in isolation​

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

This is useful when you are already mid-feature and want to review something without stashing or resetting your current checkout.

Open a worktree in an editor​

gji open                              # pick worktree + editor interactively
gji open feature/auth-refactor        # open a specific branch
gji open --editor cursor --save       # use cursor and remember it

gji open is most useful when you want to open a worktree you are not currently in — for example launching a PR review in a new editor window without leaving your current task.

Move between active tasks​

gji warp feature/auth-refactor
gji warp repo-a/main
gji go feature/auth-refactor
gji go main
gji back
gji root
gji ls
gji status

Use:

  • gji warp to jump across all registered repos by branch name or repo/branch
  • gji go to jump to any worktree by branch name or interactive selection
  • gji back to return to the last worktree you were in — like cd - but for worktrees
  • gji back 2 (or any number) to jump further back in history
  • gji history to see your full navigation history
  • gji ls for a detailed worktree list
  • gji ls --compact when you only need branch and path
  • gji status for health, branch state, and ahead/behind information
  • gji root when you just need the primary repo checkout again

Use detached scratch space​

gji new --detached

Detached worktrees are useful when you want temporary investigation space without committing to a branch name yet.

Create the next task in another repo​

gji warp --new fix/copy-regression

This is useful when you know the branch name you want next, but the work belongs in a different registered repo than the one you are currently inside.

Typical day example​

gji new feature/dark-mode
gji pr 184
gji warp repo-a/main
gji go feature/dark-mode
gji back
gji sync
gji status
gji remove feature/dark-mode

The main point is that each task keeps its own files, dependencies, and terminal context.

Parallel work with AI​

If you use coding agents or AI-assisted tooling, worktrees stop being a nice-to-have and start becoming the clean boundary between tasks.

A common pattern looks like this:

gji new feature/checkout-redesign
gji pr 184
gji new --detached
gji ls

That gives you:

  • one worktree for your main implementation
  • one worktree for reviewing or reproducing a PR
  • one detached scratch space for agent-generated experiments or risky validation

Instead of asking one checkout to represent everything, you let each task keep its own state.