Support $CLAUDE_CONFIG_DIR for custom config paths
- Dominant language
- TypeScript
- Stars
- 133k
- Forks
- 19.9k
- Avg merge
- 18h 46m
- Merged PRs (30d)
- 26
Description
## Problem
Claude Code supports `$CLAUDE_CONFIG_DIR` to override the default `~/.claude` directory. However, gstack hardcodes `~/.claude/skills/gstack` throughout the codebase (480 occurrences across 50 files). When a user runs Claude Code with a custom `$CLAUDE_CONFIG_DIR`, gstack silently references the default `~/.claude` directory instead — reading the wrong memories, settings, and project config, and writing state to the wrong location.
## Scope of affected files
### Source-of-truth files (7 — must change)
| File | Role |
|------|------|
| `scripts/gen-skill-docs.ts` | Defines `skillRoot`, `binDir`, `browseDir` on lines 42-45; embeds paths into all generated preamble/postamble templates |
| `setup` | Install script — creates symlinks in `~/.claude/skills/`, rewrites paths for kiro/codex |
| `scripts/skill-check.ts` | Validates generated output contains correct host paths |
| `browse/src/find-browse.ts` | Binary discovery — searches `~/.claude/skills/gstack/browse/dist/browse` |
| `bin/gstack-global-discover.ts` | Session discovery across `~/.claude/projects` |
| `bin/dev-setup` | Creates `.claude/skills/gstack` dev symlink |
| `bin/dev-teardown` | Cleans up dev symlinks |
### Template files with their own hardcoded paths (~17 `.tmpl` files)
Several templates (notably `gstack-upgrade/SKILL.md.tmpl` with 19 refs, `codex/SKILL.md.tmpl` with 5, `autoplan/SKILL.md.tmpl` with 7) contain literal `~/.claude/skills/gstack` in bash blocks beyond what the generator injects. These need fixing too.
### Auto-fixed (no direct changes needed)
28 generated `SKILL.md` files — regenerated from templates when sources are fixed.
### Also need updates
- 6 test files (verify path correctness in generated output)
- 8 documentation files (CLAUDE.md, ARCHITECTURE.md, etc.)
## Proposed fix
Replace hardcoded `~/.claude` with `${CLAUDE_CONFIG_DIR:-$HOME/.claude}` at each layer:
1. **`gen-skill-docs.ts`** — change `skillRoot`, `localSkillRoot`, `binDir`, `browseDir` to use the dynamic pattern
2. **`setup`** — resolve install target via `${CLAUDE_CONFIG_DIR:-$HOME/.claude}`
3. **`find-browse.ts`** — check `$CLAUDE_CONFIG_DIR` when searching for the browse binary
4. **`bin/dev-setup`, `bin/dev-teardown`** — same pattern
5. **`.tmpl` files** — replace literal `~/.claude/skills/gstack` with the dynamic pattern in bash blocks
6. Regenerate all SKILL.md files
## Relation to #289
Issue #289 (host integration contract RFC) proposes a broader abstraction for multi-host support. `$CLAUDE_CONFIG_DIR` support is a concrete, narrower fix that can land independently — it fixes a real bug for Claude Code users today without waiting for the full host adapter architecture. The fix naturally aligns with #289's direction since it makes path resolution dynamic rather than hardcoded.
## Impact
Users running Claude Code with a custom `$CLAUDE_CONFIG_DIR` will have gstack silently reference the default `~/.claude` directory. This means gstack reads the wrong memories, settings, and project config — and writes state (sessions, analytics, skill data) to the wrong location. No error or warning is shown.
Contributor guide
Assessment
This issue has not been assessed yet.