Install gji
Install the CLI, then enable shell integration once. The integration lets
gji new, gji go, and gji back change the directory of your current shell.
Requirements
- Node.js 20+ to run the npm package.
- Git with worktree support and a local repository to work in.
- zsh, bash, or fish for automatic directory changes.
- Access to your Git remote for fetching branches or pull requests.
New worktrees install dependencies when a supported lockfile is detected. Your
project's package manager must be available; the first install may take time
and uses additional disk space. You can skip it with --no-install.
Install and set up your shell
npm install -g @solaqua/gji
gji init
The wizard installs shell integration and completions, and lets you choose an available editor. Restart your shell, or load the configuration file shown by the wizard, before continuing.
Inside a repository, check the result:
gji doctor
Follow any hints for your shell, Git, or configuration. Then create your first worktree.
Set up a specific shell
For dotfiles or non-interactive setup:
gji init zsh --write
# Or use your shell:
gji init bash --write
gji init fish --write
Use just the command for your shell. To inspect the wrapper without writing it:
gji init zsh
See shell integration for session-only setup and scripts. Without it, worktree commands can still create or resolve directories, but they cannot move the parent shell for you.
Optional: prepare local project files
If a new worktree needs private files from your main worktree, register them:
gji sync-files add .env.local .npmrc
The file list is saved in global per-repository configuration. New worktrees receive those files before dependency setup; existing target files aren't overwritten. See local files.
Keep hooks for additional project setup, such as code generation. Don't add a second install hook if the built-in adapter already installs your dependencies.
Update
npm install -g @solaqua/gji
Restart your shell to reload integration, then run gji doctor again.
If navigation prints a path instead of moving your shell, follow
the navigation troubleshooting steps.