Last updated 2026-05-07

Quick Start

From an empty terminal to a stacked diff, a green local CI run, and a PR — in about five minutes. Add the optional secrets step when the workflow needs production-like credentials.

1. Install

Pick whichever you prefer — both install the same release binary:

# Homebrew (macOS / Linux)
brew install elloloop/tap/stax


# Or, one-line installer
curl -fsSL https://raw.githubusercontent.com/elloloop/stax/main/install.sh | sh


stax --version

2. Clone a repo

stax clone elloloop/stax
cd stax

stax clone wraps git clone, then sets up a private .stax/ workspace inside the checkout (added to .git/info/exclude, never committed).

3. Start a feature

stax feature "user auth"

Creates a branch (feature/user-auth), records the feature name in .stax/features.json, and switches to it. Use fix, docs, or chore instead of feature for those change types.

4. Save logical changes as stacked diffs

# edit code, then:
stax diff "Add login form"


# more edits:
stax diff "Add JWT validation"


stax diffs

Each stax diff stages everything, generates a Conventional-Commit-style title (via the local LLM helper or the explicit message you provide), and commits. The output of stax diffs shows the stack: 

D1  feat(user-auth): Add login form          (3 files, 87 +/-)
D2  feat(user-auth): Add JWT validation      (2 files, 41 +/-)

5. Start the local runner

The runner is the local CI engine. Run it once per workspace:

stax runner start
# ✓ Runner started (PID 41234)
#   http://localhost:4800

The runner stays up in the background. Use stax runner stop to terminate it; stax runner status to check.

6. Optional: configure repo-backed secrets

For production deploys, the recommended source of truth is an encrypted SOPS file committed to git. Stax manages the scaffold, age recipients, verification, export, and runner sync. 

brew install sops
stax secrets keygen
stax secrets pubkey


stax secrets init --env production
stax secrets edit --env production
stax secrets verify
stax secrets sync runner

The default scaffold creates infra/secrets/prod.enc.yaml, .sops.yaml, infra/secrets/recipients.md, and .stax/vault.json. Add teammates by committing recipient changes with stax secrets add-recipient.

7. Trigger a workflow

stax workflows           # list everything in .github/workflows/
stax run ci              # trigger the "ci" workflow
stax runs                # see in-progress + recent runs
stax log <run-id>        # full log
stax log <run-id> -f     # follow live

Workflows run in an isolated sandbox (a git worktree by default — or an APFS copy-on-write clone on macOS). Concurrent runs do not collide.

8. Watch in the dashboard

stax dashboard

Opens the Next.js dashboard at http://localhost:3000. It streams jobs, steps, logs, and artifacts over the runner's SSE feed in real time. The dashboard also includes repo-secrets status, recipients, verify/sync actions, GitHub issue sync, and deployment-log configuration.

9. Submit and land

stax sync       # rebase the stack on latest origin/main
stax submit     # opens a PR via gh CLI
# ... reviews / iterations: edit, stax diff, stax submit ...
stax land       # squash-merges into main and cleans up

10. Optional: mirror production deployments

Enable GitHub sync in the dashboard's Issues view and set a deployment issue number. Stax always writes matching local records to .stax/deployments.jsonl; when configured, it also posts a structured comment to the GitHub issue for tracked environments such as production or prod.

What you just used

  • CLI — stax feature, diff, submit, land for the stacked-diff loop; runner, run, workflows, runs, log for CI; dashboard to launch the UI; secrets for git-backed SOPS + age secrets.
  • Runner — listening on :4800, parsing your .github/workflows/ files, and executing them in a sandbox.
  • Dashboard — reading the runner's REST API for list views and SSE for live updates.

Next steps