How to Install gstack: Add Pro Workflows to Claude Code

Getting gstack up and running is one of the most frictionless tool installations in the AI developer ecosystem. There is no package manager, no build step, no dependency resolution, and no environment variables to configure before you can run your first command. The entire process is a single git clone followed by a setup script — and if you already have Claude Code and Git installed, you can go from zero to /plan in under sixty seconds.

This guide covers both the global install (recommended for personal use) and the project-level install (for teams who want to share a consistent skill set through version control). It also walks through verifying the installation, understanding the directory structure, configuring optional settings, and running your first gstack command. For background on what gstack is and why its gear-based persona system produces better AI output, see the gstack overview.

Prerequisites

Before installing gstack, confirm that three things are in place:

Claude Code must be installed and functional. gstack installs into Claude Code’s ~/.claude/skills/ directory and surfaces as slash commands within Claude Code sessions. Without Claude Code, gstack has nowhere to live. If you have not yet installed Claude Code, follow the official Anthropic installation instructions and verify that you can open a Claude Code session before continuing.

Git must be available on your system. The installation uses git clone to pull the gstack repository into your skills directory, and future updates use git pull. Confirm Git is installed by running:

git --version
# git version 2.43.x

If Git is not installed, download it from git-scm.com and follow the platform-specific installer.

Operating system path awareness matters because the skills directory location differs across platforms:

Throughout this guide, Unix-style paths (~/.claude/skills/) are used. Windows users running native Command Prompt should substitute %USERPROFILE%\.claude\skills\. Windows users running Git Bash or WSL can use the ~ shorthand exactly as shown.

No other prerequisites exist. gstack requires no Python runtime, no Node.js, no Docker, and no external API keys beyond your existing Claude Code subscription. This is a meaningful contrast to tools like OpenDevin, which requires Docker, a running daemon, and at least 8GB of RAM before you can run a single task. Compare the two approaches in the OpenDevin installation guide to appreciate how lightweight the gstack model is.

Global Install (Recommended)

The global install places gstack in your user-level Claude Code skills directory. All Claude Code sessions you open — across any project, in any directory — will automatically have access to all 13 gstack commands.

Run these two commands:

git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack && ./setup

The first command clones the gstack repository into ~/.claude/skills/gstack/. If the skills/ directory does not yet exist, Git creates it automatically. The clone is small — gstack contains only configuration files and prompt templates, not compiled code — so it completes in a few seconds regardless of connection speed.

The second command runs the setup script bundled with gstack. This script handles any initialization tasks, such as creating the ~/.gstack/ configuration directory and writing the default config.yaml file. The setup script is idempotent: running it multiple times is safe and will not overwrite any configuration changes you have made.

After both commands complete, the installation is done. Open a new Claude Code session and type / to see all available slash commands. You should see the gstack commands — /plan, /qa, /ship, /code-review, and the rest — listed alongside any other commands you have installed.

Windows (Command Prompt):

git clone https://github.com/garrytan/gstack.git %USERPROFILE%\.claude\skills\gstack
%USERPROFILE%\.claude\skills\gstack\setup

Windows (Git Bash or WSL):

git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack && ./setup

Project-Level Install (Team Sharing)

The project-level install places a copy of gstack inside your project repository under .claude/skills/gstack/. When a teammate clones your repository, they get the exact same version of gstack that you are using — no separate installation required.

This approach is ideal for teams where consistency matters. Every engineer uses the same /code-review gear definition, the same /qa test protocol, and the same /plan output structure, because they are all running the same files that live in version control.

Start from your global install (you must have already completed the global install, as the setup script is what creates the configuration baseline):

# Copy the gstack skills into your project's .claude directory
cp -Rf ~/.claude/skills/gstack .claude/skills/gstack

# Remove the .git directory — this copy should not track the upstream repo
rm -rf .claude/skills/gstack/.git

# Run setup to initialize the project-level configuration
cd .claude/skills/gstack && ./setup

The rm -rf .claude/skills/gstack/.git step is important. If you leave the .git directory in place, your project repository will treat gstack/ as a git submodule, which creates complications when teammates clone the repo. Removing .git turns it into a plain directory that your project’s own git history tracks directly.

After copying, commit the files to your repository:

cd /path/to/your/project
git add .claude/skills/gstack
git commit -m "add gstack skills for team workflow standardization"
git push

Teammates who pull this commit will have gstack available in their Claude Code sessions when they open the project, without needing to run any separate installation commands.

When to choose global vs project-level:

Verifying the Installation

After installation, verify that Claude Code can see the gstack commands before doing anything else. Catching a misconfiguration early saves debugging time later.

Step 1: Open a new Claude Code session. Skills are discovered at session startup, so if you had Claude Code open during installation, close it and reopen it. If you are working in a project with a project-level install, open Claude Code from within that project directory.

Step 2: Type / in the Claude Code input. The slash command palette will appear listing all available commands. Scroll through the list and confirm you can see gstack commands:

/plan
/design-review
/code-review
/qa
/ship
/browser
/retrospective
/post-ship-docs
/standup
/rfc
/incident
/metrics
/changelog

If all 13 commands appear, the installation is complete and working correctly.

Step 3: Run a quick smoke test with /plan. Type /plan followed by a brief description of something you are working on. Even a single sentence like “I want to add a search feature to a notes app” is enough. A functioning gstack installation will respond with a structured product plan output from the Founder gear. If you see an error or an unexpected generic response, refer to the troubleshooting notes below.

If commands do not appear:

• Confirm the directory path is exactly ~/.claude/skills/gstack/ (not ~/.claude/gstack/ or ~/.skills/gstack/)
• Run ls ~/.claude/skills/ and verify gstack is listed as a directory
• Ensure the setup script ran successfully — re-run cd ~/.claude/skills/gstack && ./setup and check for any error output
• Restart Claude Code completely (not just a new session tab, but a full application restart)

Directory Structure

Understanding the gstack directory layout helps you navigate the project when you want to customize commands or diagnose issues.

After a successful global install, ~/.claude/skills/gstack/ contains:

~/.claude/skills/gstack/
├── bin/
│   └── gstack-config        # CLI tool for reading/writing config.yaml
├── skills/
│   ├── plan.md              # /plan command definition (Founder gear)
│   ├── code-review.md       # /code-review command definition (EM gear)
│   ├── qa.md                # /qa command definition (QA gear)
│   ├── ship.md              # /ship command definition (EM gear)
│   ├── design-review.md     # /design-review command definition
│   ├── browser.md           # /browser command definition
│   ├── retrospective.md     # /retrospective command definition
│   ├── post-ship-docs.md    # /post-ship-docs command definition
│   ├── standup.md           # /standup command definition
│   ├── rfc.md               # /rfc command definition
│   ├── incident.md          # /incident command definition
│   ├── metrics.md           # /metrics command definition
│   └── changelog.md         # /changelog command definition
├── setup                    # initialization script
└── README.md

The skills/ subdirectory contains one Markdown file per slash command. Each file defines the behavioral prompt for that command — the system instructions that tell Claude which gear persona to adopt and how to structure its output. These files are human-readable and can be edited directly if you want to customize a command’s behavior.

The bin/gstack-config script is a shell utility for reading and writing config.yaml without manually editing YAML. It is covered in detail in the Configuration section below.

gstack also creates a separate directory at ~/.gstack/ (outside the skills directory) to store user-level configuration:

~/.gstack/
└── config.yaml              # user configuration file

This separation keeps your configuration safe when you update gstack via git pull — the update only touches files inside ~/.claude/skills/gstack/, never ~/.gstack/config.yaml.

Configuration

gstack’s behavior can be tuned through a YAML configuration file at ~/.gstack/config.yaml. The setup script creates this file with sensible defaults the first time it runs.

The default configuration looks like this:

auto_upgrade: true
update_check: true
gstack_contributor: false

auto_upgrade: true — When enabled, gstack will automatically apply updates from the upstream repository when you pull new changes. If you prefer to control exactly when updates take effect, set this to false and update manually.

update_check: true — When enabled, gstack periodically checks whether a newer version is available and notifies you inside Claude Code. This is a lightweight check that only reads version metadata — it does not download anything. Set to false if you are on a restricted network or prefer not to see update notifications.

gstack_contributor: false — Set this to true if you are actively contributing improvements to gstack. It enables additional development utilities and verbose logging that are useful when testing changes before submitting a pull request.

Editing Configuration with gstack-config

Rather than opening config.yaml in a text editor, you can use the gstack-config CLI tool bundled with gstack:

# Read a single config value
~/.claude/skills/gstack/bin/gstack-config get auto_upgrade
# true

# Write a config value
~/.claude/skills/gstack/bin/gstack-config set auto_upgrade true

# List all config values
~/.claude/skills/gstack/bin/gstack-config list
# auto_upgrade: true
# update_check: true
# gstack_contributor: false

Using gstack-config is safer than direct YAML editing because it validates the key names and value types before writing. Typos in config.yaml can cause gstack to silently fall back to defaults, so the CLI tool helps avoid that class of error.

If you want to add gstack-config to your shell path for easier access, add this line to your ~/.bashrc, ~/.zshrc, or equivalent:

export PATH="$HOME/.claude/skills/gstack/bin:$PATH"

After adding this, restart your shell or run source ~/.bashrc. You can then invoke gstack-config directly:

gstack-config list
gstack-config set update_check false

Running Your First Command

With gstack installed and verified, the fastest way to experience the system is to run /plan on a real task. The /plan command activates the Founder gear and produces a structured product plan before any code is written — a deliberate step that prevents the common failure mode of building something nobody actually needs.

Open a Claude Code session in a project you are actively working on, or simply start a new session. Then invoke /plan with a brief description of what you want to build:

/plan Add a user-facing export feature: let users download their data as a CSV file

The Founder gear will respond with a structured breakdown that typically includes:

• Problem statement — What user need does this solve and why does it matter?
• Scope definition — What is in scope for this iteration and what is explicitly out of scope?
• User stories — Concrete examples of how a real user would use this feature
• Success criteria — How you will know the feature is working correctly
• Trade-offs and risks — What could go wrong, what decisions need to be made
• Implementation sequence — A logical order for tackling the work

This output is different from what you get when you just ask Claude to “plan a CSV export feature” without a gear. The Founder gear stays in product strategy mode — it does not start writing code, it does not wander into implementation details unless you explicitly ask, and it does not blend in QA concerns or deployment considerations. You get a clean product plan that you can use to align stakeholders before a single line of code is written.

After reviewing the plan, you can switch gears deliberately:

/code-review

Ask the Engineering Manager gear to review your export implementation after you write it. Then run:

/qa

Let the QA gear analyze your running web app and generate a health score before you ship. This gear-switching pattern — plan first, build second, review third, QA fourth, ship fifth — is the core workflow gstack is designed to support.

Updating gstack

Because gstack is a git clone, updating to the latest version is a single command:

cd ~/.claude/skills/gstack && git pull

Run this whenever you want to pull in new commands, prompt improvements, or bug fixes from the upstream repository. If auto_upgrade: true is set in your configuration, gstack may handle this automatically when updates are available.

After pulling updates, no build step is required. Changes take effect the next time you open a Claude Code session. If you are in an active session, close and reopen it to pick up the new command definitions.

For project-level installs, updates are managed differently — because you removed .git from the project copy, there is no remote to pull from. To update a project-level install:

# Update your global install first
cd ~/.claude/skills/gstack && git pull

# Then copy the updated files into your project
cp -Rf ~/.claude/skills/gstack /path/to/your/project/.claude/skills/gstack
rm -rf /path/to/your/project/.claude/skills/gstack/.git

# Commit the update
cd /path/to/your/project
git add .claude/skills/gstack
git commit -m "update gstack skills to latest version"

This manual process is intentional. Project-level installs prioritize stability and reproducibility over automatic updates — the team should consciously decide when to adopt a new version of gstack.

Frequently Asked Questions

How do I uninstall gstack?

Uninstalling gstack is as simple as deleting the skills directory:

rm -rf ~/.claude/skills/gstack

Also remove the configuration directory if you want a clean slate:

rm -rf ~/.gstack

After deletion, restart Claude Code. The gstack commands will no longer appear in the slash command palette. No registry entries, no PATH modifications (unless you added gstack-config to your PATH manually), and no system configuration files are left behind.

For a project-level install, remove the directory from your repository:

rm -rf .claude/skills/gstack
git rm -r .claude/skills/gstack
git commit -m "remove gstack skills"

Can I have multiple skill sets installed at the same time?

Yes. Claude Code’s ~/.claude/skills/ directory is designed to hold multiple skill packages simultaneously. Each package lives in its own subdirectory, and all commands from all packages appear together in the slash command palette. For example, if you have both gstack and a hypothetical devops-skills package installed:

~/.claude/skills/
├── gstack/        # /plan, /qa, /code-review, etc.
└── devops-skills/ # /deploy, /rollback, etc.

All commands from both packages are available in every Claude Code session. The only conflict to watch for is command name collisions: if two packages define a command with the same name (e.g., both define /plan), Claude Code’s behavior is undefined and you should rename one of them. Check the command names in each package’s skills/ directory before installing multiple packages together.

Does gstack work on Windows?

Yes, gstack works on Windows with a small path adjustment. The skills directory is %USERPROFILE%\.claude\skills\ rather than ~/.claude/skills/. In practice, the easiest way to install on Windows is through Git Bash or WSL, where you can use the same Unix-style commands shown throughout this guide.

Native Command Prompt and PowerShell also work, but the ./setup script requires a shell that can execute shell scripts. Git Bash (which ships with Git for Windows) is the simplest option. Run the following in Git Bash:

git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack && ./setup

The resulting installation is fully functional in Windows Claude Code sessions. The only persistent difference is that the configuration directory lives at %USERPROFILE%\.gstack\config.yaml rather than ~/.gstack/config.yaml, but Claude Code handles this path resolution transparently.

Next Steps

With gstack installed and your first /plan session complete, you have access to the full 13-command workflow system. The most immediately valuable commands to explore after /plan are:

• /code-review — Run this on any pull request or code change before merging. The Engineering Manager gear applies consistent evaluation criteria regardless of who wrote the code or who is reviewing it.
• /qa — Point this at your running development server. The QA gear will execute a test protocol and return a health score with a structured report saved to .gstack/qa-reports/.
• /ship — Use this as your pre-deployment checklist. The Engineering Manager gear verifies the feature is ready without regressions before you push to production.

For a deeper understanding of how the gear personas work and why the structured persona-switching approach produces better AI output than ad-hoc prompting, the gstack overview covers the design philosophy in detail.

If you are evaluating gstack against other AI coding tools, the contrast with OpenDevin is instructive. OpenDevin is a fully autonomous coding agent that operates inside a sandboxed Docker environment and requires several minutes of setup, Docker runtime, and an LLM API key configured separately. gstack is the opposite end of the spectrum: it enhances Claude Code that you already have, installs in under a minute, and keeps you in control of every action while making each action faster and more consistent. Neither approach is universally better — they serve different use cases — but understanding the trade-off helps you choose the right tool for a given task.