garrytan / garrytan/gstack

Windows: Use Junction (mklink /J) instead of copying to save disk space

Open
#1,877 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
133k
Forks
19.9k
Avg merge
18h 46m
Merged PRs (30d)
26

Description

## Problem

On Windows, the setup script copies entire directories to each agent's skills folder instead of creating symlinks. This wastes significant disk space.

For example, gstack is ~1.8GB. With Claude Code and Codex, this results in:
- gstack source: 1.8GB
- Claude Code copy: 1.8GB
- Codex copy: 1.8GB
- **Total: 5.4GB** (3.6GB wasted)

## Current Behavior

From `setup` script:
```bash
if [ "$IS_WINDOWS" -eq 1 ]; then
rm -rf "$dst"
if [ -d "$src" ]; then
cp -R "$src" "$dst" # Full copy!
fi
fi
```

The comment explains:
> On Windows without Developer Mode (MSYS2/Git Bash): plain ln -snf silently creates a frozen file copy that doesn't refresh after git pull.

## Solution: Windows Junction

Windows has **Junction** (`mklink /J`) which:
- ✅ Works **without** Administrator privileges
- ✅ Is transparent to applications (kernel-level)
- ✅ Cross-drive (C: → D: works)
- ✅ Automatically reflects source changes (git pull updates work)

### Proposed Change

```bash
_link_or_copy() {
local src="$1"
local dst="$2"
if [ "$IS_WINDOWS" -eq 1 ]; then
rm -rf "$dst"
if [ ! -e "$src" ]; then
return 0
fi
# Try Junction first, fallback to copy if it fails
if cmd //c "mklink /J \"$(cygpath -w "$dst")\" \"$(cygpath -w "$src")\"" 2>/dev/null; then
return 0
fi
# Fallback to copy
if [ -d "$src" ]; then
cp -R "$src" "$dst"
else
cp -f "$src" "$dst"
fi
else
ln -snf "$src" "$dst"
fi
}
```

## Benefits

- **Saves ~3.6GB** for users with multiple agents (Claude Code + Codex)
- No manual relinking after `git pull`
- Same functionality, smaller footprint

## Testing

I've been using Junction for gstack skills for weeks without issues:
- Reading SKILL.md works
- Executing scripts in bin/ works
- node_modules access works
- git pull updates automatically reflected

Environment: Windows 11, Git Bash (MSYS2)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.