Support repo-local portable context artifacts while keeping one shared gstack installation
- Dominant language
- TypeScript
- Stars
- 133k
- Forks
- 19.9k
- Avg merge
- 18h 46m
- Merged PRs (30d)
- 26
Description
#### Summary
I'd like gstack to support repo-local project context artifacts, while keeping gstack itself as a single shared installation.
The goal is not to vendor or fork gstack into every project. The goal is:
> Keep one gstack installation, but let project-specific outputs — checkpoints, handoffs, plans, review conclusions — live in the project repository.
This would make gstack-generated project context portable across machines and usable by teammates through Git.
#### Background
Team projects usually need to separate two kinds of state:
1. **Machine-local gstack state**
- local cache
- telemetry
- browser/session state
- temporary local history
- user-specific global gstack data
2. **Project-local portable artifacts**
- design documents
- review outputs
- implementation plans
- checkpoints
- handoff notes
- timeline entries
- decisions that affect future development or GitHub work
For the second category, the repository should be the source of truth.
A typical repo-local convention could look like this:
```text
.gstack/designs/
.gstack/reviews/
.gstack/plans/
.gstack/checkpoints/
.gstack/timeline/
.gstack/archive/
```
Anything you need after switching machines, onboarding a teammate, resuming a branch, reviewing a PR, or continuing project work should live in the repo.
#### Current behavior
Currently, `/context-save` writes context files under:
```text
${GSTACK_HOME:-$HOME/.gstack}/projects/$SLUG/checkpoints
```
And `/context-restore` reads from the same location.
This works fine for local recovery. But when a checkpoint contains project-level information, it ends up living only in a user-local directory:
```text
~/.gstack/projects//checkpoints/
```
That creates a portability problem.
For example:
- the latest implementation state
- decisions made during a design or engineering review
- remaining work
- next steps for another machine or teammate
- handoff context before pushing or opening a PR
These are not just local cache. They are project artifacts.
#### Problem
Current behavior can make `~/.gstack/projects//...` the accidental source of truth for project context.
Issues:
1. Saved context does not automatically follow the Git repository.
2. A developer may push code but lose project context when switching machines.
3. Teammates cannot restore the same context from the repo alone.
4. Teams end up writing ad-hoc wrapper scripts or sync conventions.
5. The only obvious alternative is vendoring or forking gstack per project, which creates version drift and upgrade friction.
This matters because gstack's team mode already encourages a single shared installation rather than vendoring gstack into every repo. That's the right direction. But project-specific outputs still need a first-class repo-local home.
#### Requested capability
Add official support for repo-local portable context artifacts, at least for `/context-save` and `/context-restore`.
Possible config shape:
```yaml
checkpoint_store: user | repo | dual
checkpoint_repo_dir: .gstack/checkpoints
```
Or more generally:
```yaml
context_store: user | repo | dual
context_repo_dir: .gstack/checkpoints
```
Proposed behavior:
```text
user:
Keep existing behavior.
Save and restore from ${GSTACK_HOME:-$HOME/.gstack}/projects/$SLUG/checkpoints.
repo:
Save and restore from /.gstack/checkpoints.
dual:
Save to both user-local and repo-local stores.
Restore can search both, ideally showing the source of each checkpoint.
```
Command-level options could look like:
```text
/context-save --repo-local
/context-save --dual-write
/context-restore --from repo
/context-restore --from user
/context-restore --from both
```
Default behavior could remain unchanged for backward compatibility.
#### Non-goals
This is not asking gstack to move all state into the repository.
Specifically, this should not include:
- telemetry
- local analytics
- browser state
- cookies
- temporary session state
- private user data
- global cache
- purely machine-local history
Those should remain user-local.
This is also not asking teams to vendor gstack into each project. The purpose is the opposite: avoid per-project forks or vendored copies while still making project outputs portable.
#### Why this fits gstack
This aligns with gstack's team workflow:
- gstack itself stays centrally installed and upgradeable.
- Projects keep their own durable artifacts.
- Teammates can restore project context from Git.
- Context handoff becomes reviewable and committable.
- Machine-local state and project-local artifacts stay clearly separated.
In short:
```text
gstack installation:
shared / global / auto-upgradable
gstack project outputs:
repo-local when needed for collaboration or future project work
```
This separation would make gstack easier to use in long-running team repositories.
#### Example workflow
A project could define:
```text
.gstack/checkpoints/
```
as the repo-local source of truth for portable checkpoints.
Then:
```text
/context-save auth-refactor-handoff
```
would create:
```text
.gstack/checkpoints/20260423-153012-auth-refactor-handoff.md
```
A teammate — or the same developer on another machine — could clone the repo and run:
```text
/context-restore --from repo
```
or simply:
```text
/context-restore
```
if repo-local restore is the default.
#### Compatibility considerations
A minimal implementation could preserve existing behavior:
- keep user-local storage as the default
- keep the existing checkpoint file format
- keep existing frontmatter fields
- keep existing timestamp sorting behavior
- only use repo-local mode when explicitly configured
- fall back to user-local storage when not inside a Git repo
This avoids breaking existing users while enabling teams to opt into repo-local persistence.
#### Possible acceptance criteria
This feature would be successful if:
1. A repo can opt into repo-local checkpoints.
2. `/context-save` can write portable checkpoints into `.gstack/checkpoints/`.
3. `/context-restore` can read those checkpoints after cloning the repo on another machine.
4. The default user-local behavior remains unchanged.
5. Documentation clearly explains the distinction between:
- machine-local state
- repo-local project artifacts
6. Teams do not need to vendor or fork gstack to make project context portable.
#### Workaround today
Projects can approximate this with wrapper scripts, `GSTACK_HOME`, symlinks, or manual sync from:
```text
~/.gstack/projects//checkpoints/
```
to:
```text
.gstack/checkpoints/
```
An official mode would be cleaner, easier to document, and less error-prone for teams.
Contributor guide
Research direction
Start by tracing the existing /context-save and /context-restore flows and their use of ${GSTACK_HOME}/projects/$SLUG/checkpoints. Define how user, repo, and dual stores interact while preserving the existing file format and fallback behavior. Done means repo-local checkpoints can be saved and restored after cloning, default user-local behavior remains unchanged, and the storage distinction is documented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- developer-experience, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100