Garry Tanandcapy-ai[bot]
9e3308f65a
* fix(harness): print error lines again; register qm stops before QM's pack cap instead of claiming QM works Bun gives every thrown Error an own numeric 'line' property, which shadowed HarnessError.prototype.line(), so every refused gstack-harness command crashed with 'e.line is not a function'. The printer is now report(). QM imports a skill pack by cloning the whole repository and refuses past 32 MiB / 5,000 files (Harness Evals preflight, HARN-5); gstack's repository is 73 MiB in 4,280 files. register qm now measures first and stops with HARNESS_QM_PACK_TOO_LARGE before any request; QM's own cap refusal maps to the same code. docs/hosts.md lists QM as not available yet. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * s Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(harness): read QM's recorded import error for the cap; refuse to size a non-git checkout; skip symlinks like QM Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * chore: drop a stray a/SKILL.md committed by a scratch experiment Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * docs: no doc implies QM registration works (document-release audit) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * docs(install): stable's 72-hour rule also excepts a regression fix (#3533) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --------- Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
5.3 KiB
Install details
The README covers the two-step install. This page holds the details: what setup needs and how long it takes, the team-mode hook, the hooks setup registers in Claude Code, agent harness registration, and how to remove gstack.
How long setup takes
./setup took 31 seconds after the clone on a 4-vCPU Linux cloud machine (v1.91.13.0, clean HOME, including the binary build and the Chromium download). Slower networks and laptops take longer.
Requirements, in detail
Requirements: Claude Code, Git, Bun v1.4.2+ (the tested version; setup refuses Bun older than 1.3.3, which would let compiled tools read a project's .env, and warns in between), Node.js (Windows only). Recommended on macOS: the Aside browser (macOS 15+) — browser skills, /make-pdf, and /diagram drive it first, with your real logged-in sessions. Without it, ./setup builds gstack's own bundled browser and the same skills use that. /cso additionally needs a Bun release with all four --no-compile-autoload-* build flags plus a native toolchain: a static-capable C compiler on Linux, Xcode command-line tools on macOS, or Visual Studio 2022 Build Tools with Desktop development with C++ on Windows. If those are absent, setup installs everything else, removes stale CSO helpers, and /cso reports not assessed with the prerequisite.
When qualified CSO runtime images are published, setup gives each automatic preload a 30-second window plus a bounded setup allowance for the declared catalog. For slower registries, set an integer such as GSTACK_CSO_IMAGE_PULL_TIMEOUT_SECONDS=120 (accepted range: 5–300 seconds). One image timing out does not consume the remaining images' windows; setup reports partial progress and a later run resumes from exact digests already present in local Docker. The complete preload is capped at one hour.
Team mode
From inside your repo, (cd ~/.claude/skills/gstack && ./setup --team) && ~/.claude/skills/gstack/bin/gstack-team-init required switches you to team mode and bootstraps the repo so teammates get gstack automatically (the README has the full paste, which also commits the change).
No vendored files in your repo, no version drift, no manual upgrades. Every Claude Code session starts with a fast auto-update check (throttled to once/hour, network-failure-safe, completely silent). Team mode follows the stable channel: the tagged release cut Monday and Thursday mornings, never more than once every 72 hours except for a security or regression fix, not every merge to main. gstack-config set update_channel main follows every merge instead; see releases.md.
Swap required for optional if you'd rather nudge teammates than block them.
required blocks skills with a hook that runs on Node.js, so every teammate needs Node.js on PATH, on every OS. With Claude Code 2.1.295 or later the hook also blocks when it can't run (no Node.js, or a missing .claude/hooks/check-gstack.cjs); older Claude Code lets skills through in that case.
Hooks that ./setup registers
./setup registers up to three hook families in ~/.claude/settings.json, every one pointing at the canonical install. In team mode it registers the SessionStart auto-update hook (gstack-session-update; ./setup --no-team skips it). It asks before registering the AskUserQuestion PreToolUse (preference enforcement) and PostToolUse (deterministic answer capture) hooks that /plan-tune uses at runtime; ./setup never writes them silently. docs/uninstall.md lists the same families when telling you what to remove by hand.
./setup also registers one default-on Stop hook:
gstack-timeline-stop (closes dangling session-timeline entries when a session
is interrupted; fail-open — 2s internal budget, always exits 0, can never block
a session). Opt out persistently with ./setup --no-timeline-stop-hook — the
choice lands in the timeline_stop_hook config key, survives upgrades, and an
explicit "no" removes a live registration. GSTACK_TIMELINE_STOP_HOOK=no and
gstack-config set timeline_stop_hook no work too (flag > env > config).
./setup --no-team skips it for that run, gstack-settings-hook remove-source --source gstack-timeline-stop removes it by hand, and gstack-uninstall
removes it too.
Hook registration is canonical-only: every hook command points at the stable
~/.claude/skills/gstack install, never the tree setup ran from, so deleting
a worktree or Conductor workspace can't leave dead hooks erroring in your
sessions. Every ./setup run also heals first: gstack-settings-hook prune-stale --repoint removes dead gstack hook entries, re-points stale ones
at the stable install, and collapses duplicates, printing one line (and
writing a backup beside the file) only when it changed something.
Agent harnesses
Run inside OpenClaw, Hermes or a Dot, ./setup also registers gstack's skills
with that harness, in the harness's own skills folder, and prints every path
it wrote. It never does this when --host names another host or with
--local. Turn it off with ./setup --no-harness-auto or
GSTACK_HARNESS_AUTO=0. Per-harness details, any other harness, and why QM is not available yet: hosts.md.
Uninstall
See uninstall.md.