A fast git project manager. Clone, jump, and organise repos from the terminal.

---

Features

• Instant project switching — jump to any repo by name with fuzzy matching
• Structured organisation — repos are cloned into a consistent owner/repo layout
• GitHub shorthand — gx clone user/repo just works
• Shell integration — tab completion and auto-cd for zsh, bash, fish, and PowerShell
• Open in any editor — gx open launches VS Code, nvim, or whatever you use
• AI agent scaffolding — gx init generates .claude/ configs tailored to your project's language
• Installation health checks — gx doctor verifies the binary, shell integration, config, and index
• Single binary — zero runtime dependencies, compiled from Rust

Quick Start

# Install (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/joshuaboys/gx/main/install.sh | sh
exec $SHELL   # reload to pick up PATH and shell integration

# Clone a repo and cd into it
gx clone user/repo

# Jump back to it later
gx myproject

Windows PowerShell:

irm https://raw.githubusercontent.com/joshuaboys/gx/main/install.ps1 | iex

That's it. Shell integration and tab completion are set up automatically.

Install

The installer downloads the gx binary (verifying its SHA-256 checksum), puts it on your PATH, and sets up shell integration with tab completion.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/joshuaboys/gx/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/joshuaboys/gx/main/install.ps1 | iex

The Windows installer verifies gx-windows-x64.exe against the release SHA256SUMS manifest, installs it to %LOCALAPPDATA%\gx\bin, and adds that directory to your user PATH. x86_64 only; ARM64 Windows is not published yet.

Git Bash can use gx shell-init bash once gx.exe is on PATH. WSL should use the Linux installer above.

Note: Shell integration is required for gx to cd into projects. The installer sets this up automatically. If you installed manually, add eval "$(gx shell-init)" for bash/zsh, gx shell-init | source for fish, or Invoke-Expression (& gx shell-init powershell | Out-String) for PowerShell.

Manual install

Requires a Rust toolchain (1.75+).

git clone https://github.com/joshuaboys/gx
cd gx
cargo build --release
cp target/release/gx ~/.local/bin/          # Unix
# copy target\release\gx.exe %LOCALAPPDATA%\gx\bin\   # Windows

Add shell integration to your config file:

zsh (~/.zshrc) / bash (~/.bashrc):

eval "$(gx shell-init)"

fish (~/.config/fish/conf.d/gx.fish):

gx shell-init | source

PowerShell ($PROFILE):

Invoke-Expression (& gx shell-init powershell | Out-String)

oh-my-zsh (legacy)

If you already use gx as an oh-my-zsh plugin, it still works:

ln -s /path/to/gx/plugin ~/.oh-my-zsh/custom/plugins/gx
# add gx to plugins=(...) in ~/.zshrc

The plugin file now delegates to gx shell-init internally.

Usage

Jump to a project

gx myproject        # exact match
gx myproj           # fuzzy match fallback

Tab completion works for all indexed project names.

Clone a repository

gx clone user/repo              # GitHub shorthand
gx clone https://github.com/user/repo
gx clone git@github.com:user/repo.git

Repositories are cloned to ~/Projects/src/<owner>/<repo> by default and the shell cds into the new directory.

One-off destinations

Pass an optional path to land a single clone outside the configured layout, without changing any config:

gx clone user/repo put-it-here  # -> ./put-it-here
gx clone user/repo /tmp/scratch # -> /tmp/scratch

Relative paths resolve against the current directory, the same as git clone. The clone is still indexed — under the destination's directory name, so gx put-it-here jumps back to it. Everything else is unchanged: missing parent directories are created, an existing clone at the destination is skipped, and projectDir / structure are left alone.

List projects

gx ls

Open in editor

gx open myproject               # uses default editor
gx open myproject --editor code # override editor
gx open                         # open current directory

Editor resolution order: --editor flag > gx config editor > $VISUAL > $EDITOR > nano

Scaffold AI agent config

gx init                    # auto-detect project type
gx init --type rust        # override detection
gx init --force            # overwrite existing .claude/

Creates .claude/CLAUDE.md and .claude/commands/ with plan and review slash commands. Supports project types: typescript-bun, typescript-node, rust, go, python, generic.

Rebuild index

gx rebuild

Rescans the project directory and rebuilds the project index.

Check installation health

gx doctor

Reports whether the gx binary is on PATH, shell integration is configured, config/index paths exist, and indexed projects point at existing directories.

Configuration

gx config                         # show current config
gx config set projectDir ~/code   # change project directory
gx config set structure flat      # use repo-only layout
gx config set structure owner     # use owner/repo layout (default)
gx config set structure host      # use host/owner/repo layout
gx config set editor code         # set default editor

Config is stored at ~/.config/gx/config.json.

Directory structures

owner (default)	flat	host
~/Projects/src/ owner/repo/ owner/other-repo/	~/Projects/src/ repo/ other-repo/	~/Projects/src/ github.com/owner/repo/ gitlab.com/owner/other-repo/

Uninstall

rm ~/.local/bin/gx

Remove the # gx block from your shell config file (~/.zshrc, ~/.bashrc, or ~/.config/fish/conf.d/gx.fish).

More

• Use cases & examples — real-world workflows, scripting recipes, and shell aliases
• Contributing — development setup and guidelines

Acknowledgements

gx draws inspiration from these projects:

• ghq — the original structured repository manager. ghq pioneered the host/owner/repo directory layout and index-based project lookup that gx builds on.
• gclone — a git clone helper with automatic directory organisation, shorthand URL parsing, and shell auto-cd. gx's clone workflow and shell integration owe a lot to gclone's approach.

License

MIT