gstack Setup Install Guide: Get Running in Five Minutes

What Is This gstack Setup Install Guide?

This gstack setup install guide walks you through everything you need to get gstack skills running inside Claude Code. gstack extends Claude Code with powerful slash-command skills like /browse for browser automation, /conductor for parallel AI coding, /qa for automated testing, /ship for deployment workflows, and more. The entire installation is self-contained inside the .claude/ directory -- nothing touches your PATH, nothing runs in the background, and nothing pollutes your global environment.

Whether you are setting up gstack for yourself on a single machine or rolling it out across your engineering team, this guide covers both paths. The process takes under five minutes for a solo install and requires only one additional copy command to share with teammates.

Requirements

Before beginning the gstack setup install guide, make sure you have the following three dependencies installed on your system:

gstack works on macOS and Linux, supporting both x64 and arm64 architectures. The /browse skill compiles a native binary (approximately 58 MB) during setup, which is why Bun is required. If you only need skills that do not require the browser binary, Bun is still needed for node_modules installation.

Step 1: Install gstack on Your Machine

This step installs gstack into your user-level Claude Code skills directory at ~/.claude/skills/gstack. Every Claude Code session on your machine will have access to the skills after this step.

Clone and Run Setup

Open your terminal and run the following two commands:

# Clone gstack into your Claude Code skills directory
git clone https://github.com/gstacks/gstack.git ~/.claude/skills/gstack

# Run the setup script to install dependencies and compile the browser binary
~/.claude/skills/gstack/setup

The setup script handles everything automatically:

1. Installs node_modules via Bun (these are gitignored and never committed)
2. Compiles the /browse binary -- a native executable of approximately 58 MB that runs headless Chromium
3. Creates symlinks so Claude Code can discover the skill files
4. Verifies the installation completed successfully

The entire process typically takes 30 to 60 seconds depending on your internet connection and machine speed. Once complete, you can open Claude Code in any project directory and the gstack skills will be available as slash commands.

Step 2 (Optional): Add gstack to Your Repo for Teammates

If you want every developer on your team to have access to gstack skills when they work on a specific project, you can copy the skills into your project's repository. This is the recommended approach for teams because it means git clone gives everyone the skill files immediately.

Copy Skills Into Your Project

# From your project root, copy gstack skills into the repo
cp -Rf ~/.claude/skills/gstack .claude/skills/gstack

This copies the actual files into your repository -- not a Git submodule. The files are real, committed source code. When a teammate clones your repo, they get the skill files as part of the normal checkout. There is no submodule initialization step, no extra git clone, and no dependency on an external repository being available.

What Teammates Need to Do

After cloning a repo that includes gstack skills, each teammate runs the setup script once:

# After cloning the project repo
.claude/skills/gstack/setup

This builds the /browse binary and installs node_modules on their machine. The build artifacts are gitignored, so they do not bloat the repository. Each developer compiles the binary locally, which ensures it matches their operating system and architecture.

Verifying Your Installation

After completing the gstack setup install guide steps, verify everything works by opening Claude Code and running a skill:

# Open Claude Code in any project directory
claude

# Test that the /browse skill works
/browse goto https://example.com

# Take a snapshot to confirm the browser binary is working
/browse snapshot

If the /browse command returns page content, your installation is complete. You can also verify other skills are registered by checking what slash commands Claude Code recognizes. All gstack skills, including /qa, /ship, /review, and /plan, should appear in the skill list.

What Gets Installed: A Detailed Breakdown

Understanding what the gstack setup install guide places on your system helps with debugging and gives you confidence that nothing unexpected is happening. Here is a complete accounting of what gets installed:

Everything lives inside the .claude/ directory hierarchy. No files are placed in /usr/local/bin, no shell profiles are modified, and no background processes are launched during installation. The /browse binary only starts a Chromium daemon when you explicitly invoke the /browse command, and that daemon auto-shuts down after 30 minutes of inactivity.

Upgrading gstack

gstack provides two methods for keeping your installation up to date. Choose the one that fits your workflow.

Method 1: The /gstack-upgrade Command

The simplest way to upgrade is to run the built-in upgrade skill from within Claude Code:

# Inside Claude Code, run:
/gstack-upgrade

This pulls the latest changes from the gstack repository, rebuilds the browser binary if needed, and updates all skill files in place. It is equivalent to running git pull && ./setup in the gstack directory, but packaged as a single command for convenience.

Method 2: Automatic Upgrades

If you want gstack to check for updates automatically, add the following to your configuration file:

# ~/.gstack/config.yaml
auto_upgrade: true

With auto_upgrade enabled, gstack checks for new versions at the start of each Claude Code session. If an update is available, it pulls and rebuilds silently. This is the recommended setting for developers who want to stay on the latest version without thinking about it.

Upgrading Project Copies

If you used Step 2 to add gstack to your project repository, upgrading requires copying the updated files again:

# First, upgrade your machine-level installation
/gstack-upgrade

# Then copy the updated files into your project
cp -Rf ~/.claude/skills/gstack .claude/skills/gstack

# Commit the updated files
git add .claude/skills/gstack
git commit -m "Upgrade gstack skills to latest version"

This overwrites the old skill files with the new ones. Since these are real committed files (not a submodule), the diff in your pull request will show exactly what changed, making it easy to review before merging.

Uninstalling gstack

To completely remove gstack from your system, delete the symlinks and the gstack directory:

# Remove symlinks that Claude Code uses for skill discovery
rm -f ~/.claude/skills/gstack-*

# Remove the gstack installation directory
rm -rf ~/.claude/skills/gstack

# Optionally remove the config directory
rm -rf ~/.gstack

If you added gstack to a project repository (Step 2), also remove it from there:

# From your project root
rm -rf .claude/skills/gstack
git add .claude/skills/gstack
git commit -m "Remove gstack skills"

After uninstalling, Claude Code will no longer show gstack slash commands. No other tools or configurations on your system are affected because gstack never modifies anything outside its own directories.

Troubleshooting Common Issues

This section of the gstack setup install guide covers the most frequently encountered issues and their solutions.

Skills Not Showing Up in Claude Code

If you run /browse or another gstack command and Claude Code does not recognize it, the most likely cause is that the symlinks were not created correctly during setup.

# Check that symlinks exist
ls -la ~/.claude/skills/

# If symlinks are missing, re-run setup
~/.claude/skills/gstack/setup

Also confirm that Claude Code is reading from the expected skills directory. Restart Claude Code after running setup to ensure it picks up the new skill files.

Browser Binary Not Found

If /browse reports that the binary cannot be found, the compilation step during setup likely failed. This usually happens when Bun is not installed or is an older version.

# Verify Bun is installed and meets the version requirement
bun --version

# If Bun is missing, install it
curl -fsSL https://bun.sh/install | bash

# Re-run setup to compile the binary
~/.claude/skills/gstack/setup

The /browse binary requires Bun v1.0 or later. If you have an older version, upgrade Bun first and then re-run the setup script.

Project Copy Is Stale

If the gstack skills in your project repository are outdated compared to your machine-level installation, teammates may encounter bugs that have already been fixed. The solution is to re-copy from your updated machine-level installation:

# Upgrade your machine installation first
/gstack-upgrade

# Overwrite the project copy with the latest version
cp -Rf ~/.claude/skills/gstack .claude/skills/gstack

# Commit and push so teammates get the update
git add .claude/skills/gstack
git commit -m "Update gstack skills to latest"
git push

Consider enabling auto_upgrade: true in your config to avoid this situation. When automatic upgrades are enabled, your machine-level installation stays current, and you only need to remember the cp step for project copies.

Bun Not Installed

The setup script will fail early if Bun is not found on your system. Bun is required because gstack compiles the /browse skill into a native binary using Bun's build toolchain. Install Bun with one of these methods:

# Option 1: Official installer (macOS and Linux)
curl -fsSL https://bun.sh/install | bash

# Option 2: Homebrew (macOS)
brew install oven-sh/bun/bun

# Option 3: npm (if Node.js is already installed)
npm install -g bun

After installing Bun, re-run the gstack setup script. Verify the installation succeeded by checking that the binary exists at ~/.claude/skills/gstack/browse/.

Permission Errors on macOS

If you encounter permission errors when running the compiled binary, macOS Gatekeeper may be blocking it. Because the binary is compiled locally on your machine (not downloaded from the internet), this is uncommon. If it does happen:

# Remove the quarantine flag from the compiled binary
xattr -d com.apple.quarantine ~/.claude/skills/gstack/browse/browse

Architecture Overview: How gstack Skills Load

Understanding how Claude Code discovers and loads gstack skills helps explain why the installation steps are structured this way. For a deeper look at all available skills, visit the complete gstack skills catalog.

When Claude Code starts a session, it scans the ~/.claude/skills/ directory for skill definition files. Each skill file declares the slash command name, a description, and the executable or script that handles the command. The symlinks created during gstack setup point Claude Code to the skill definitions inside the gstack directory.

For project-level installations (Step 2), Claude Code also scans the project's .claude/skills/ directory. Project-level skills take precedence over machine-level skills, which means your team can pin a specific version of gstack in the repository while individual developers can test newer versions on their machine.

Best Practices for Teams

After completing the gstack setup install guide, here are some recommendations for team rollouts:

• Commit the gstack directory to your repo -- This eliminates the "works on my machine" problem. Every developer who clones the repo gets the same skill files. They just need to run ./setup once to compile locally.
• Document the setup step in your README -- Add .claude/skills/gstack/setup to your project's getting-started instructions alongside other setup commands.
• Assign an owner for upgrades -- Designate one developer to periodically run /gstack-upgrade and push the updated files to the repo. This avoids duplicate upgrade commits.
• Use auto_upgrade for individual machines -- Developers who want the latest features can enable auto_upgrade: true in their personal ~/.gstack/config.yaml without affecting the pinned project version.
• Test skills with /browse first -- The browser automation skill is the most complex to set up because of the compiled binary. If /browse goto https://example.com works, everything else will work too.

For teams adopting AI-assisted development workflows, combining gstack with parallel coding via /conductor and comparing it against other AI coding tools can help you decide how to integrate these skills into your daily workflow.