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, and fish
• 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
• Single binary — zero runtime dependencies, compiled from Rust

Quick Start

# Install
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

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

Install

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

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

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 or gx shell-init | source for fish to your shell config.

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/

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

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.

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.

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