Open a new task or review a PR. Your current work stays right where you left it.
gji is a Git worktree CLI for developers who keep more than one task open.
Each task gets a separate working directory and dependency installation, so
switching tasks doesn't mean packing up your changes first. Keep using your
usual Git commands, editor, and coding tools inside each worktree.
Get started · Documentation · Is gji a fit?
Illustrated workflow. Shell integration is enabled; setup time is omitted.
You need Node.js 18+, Git with worktree support, and zsh, bash, or fish for automatic directory changes.
npm install -g @solaqua/gji
gji initRestart your shell, or load the shell configuration file shown by the wizard. Then, inside a repository you already work in:
gji doctor
gji new feature/try-gji
gji backYou just opened a separate worktree and returned to your previous one. Any
uncommitted files you left there stay there. New worktrees install dependencies
automatically when a supported lockfile is detected, so the first setup can take
time. Use --no-install to skip it for one task.
Installation and shell setup · Complete the first-worktree walkthrough
For example, while working on feature/payments:
gji new feature/search # give another task its own directory
gji pr 1234 # open a real PR from your repository
gji go feature/payments # return to the changes you left openReplace 1234 with a GitHub pull request in your repository. Each task stays in
its own worktree. Navigation moves your shell; it doesn't move changes between
branches or keep files synchronized.
| When you want to… | Run |
|---|---|
| Start a task | gji new |
| Review a PR locally | gji pr 1234 |
| Find an open task | gji or gji go |
| Return to the last worktree | gji back |
| Open the current worktree in an editor | gji open |
| Finish a linked worktree | gji done |
With gji go, press Tab to browse all registered repositories. Worktrees
have predictable paths: ../worktrees/<repo>/<branch>.
- Local files and defaults — copy
.env.local, choose an editor, or adjust dependency setup. - Hooks — run project-specific setup after the built-in dependency install.
- Daily workflow — review, experiment, navigate, and open editors.
- Sync and cleanup — rebase active worktrees and remove finished ones. Cleanup can delete branches; undo does not recover uncommitted files.
- Command reference — options, JSON output, and scripting.
- Troubleshooting — recover from setup, navigation, or install problems.
pnpm install
pnpm test
pnpm buildThe CLI source is in src/. See website/README.md for site
and documentation development.