mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-01 06:24:41 +01:00
Garry Tanandcapy-ai[bot]
44f19d0106
* wip: gstack-harness registrar (GSTA-135) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * wip: harness registration in setup, uninstall, tests Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * wip: harness hosts experimental, troubleshooting codes, kit Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * docs: agent harness registration (GSTA-135) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix: harness hosts run in place from the checkout in --status Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * test: bun-free ledger reader Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * docs: CHANGELOG for harness registration (Unreleased) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(harness): keep edits beside themselves, never follow symlinks, cut only gstack's own context block Review blockers on #3526: uninstall deleted the edit backups under the state root; unregister followed a symlinked folder below the destination; a lone or edited context marker made the cut eat user lines; a re-register adding --context left an unrecorded block. Also: ledger written before the files, --refresh-registered no longer re-runs harness hosts through setup (gstack-harness refresh keeps their mode), bash goes through runBashSync, and setup tests follow openclaw/hermes becoming installs. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(harness): a ledger with no destination row touches nothing (no hang) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * docs: harness registration in README, install and hosts (document-release audit) 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>
61 lines
5.3 KiB
Markdown
61 lines
5.3 KiB
Markdown
# 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](https://docs.anthropic.com/en/docs/claude-code), [Git](https://git-scm.com/), [Bun](https://bun.sh/) 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](https://nodejs.org/) (Windows only). **Recommended on macOS:** the [Aside](https://aside.com) 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 fix, not every merge to main. `gstack-config set update_channel main` follows every merge instead; see [releases.md](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](https://nodejs.org/), 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, QM and any other harness: [hosts.md](hosts.md#agent-harnesses).
|
||
|
||
## Uninstall
|
||
|
||
See [uninstall.md](uninstall.md).
|