Migrating from Graphite to stkd

If you’ve been using Graphite and you’re tempted by an open-source alternative that also supports GitLab, you can switch to stkd in about five minutes. This guide walks through the migration without losing your existing stacks.

TL;DR

brew install neul-labs/tap/stkd       # or cargo install stkd-cli
cd path/to/your/repo
gt repo init                          # reads existing Graphite metadata
gt log                                # your existing stacks appear here

That’s it. The gt command is the same; the muscle memory transfers. Below, we cover the nuances.

Why people switch

Graphite is excellent — it pioneered the modern stacked-diff workflow and built a beautiful product around it. People migrate to stkd for four specific reasons:

It’s truly open source. Apache-2.0. You can read the source, fork it, audit it, run it air-gapped. No SaaS dependency, no auth token going to a third party.
GitLab support is first class. Graphite is GitHub-only. stkd supports GitHub.com, GitLab.com, and self-hosted GitLab — handy if your company runs its own GitLab instance.
The MCP server. stkd ships a Model Context Protocol server so Claude Code, Cursor, and other AI agents can drive stacks. Graphite has no equivalent today.
Cost. Graphite is free for individuals but billed per-seat for teams. stkd is free forever, including the optional self-hosted web dashboard.

If any of those don’t matter to you, Graphite is great — keep using it. This article is for the people for whom one or more does matter.

What stays the same

The CLI surface is intentionally compatible:

Graphite	stkd
`gt branch create x`	`gt create x` (alias also accepted)
`gt log` / `gt log short`	`gt log` / `gt log short`
`gt up` / `gt down`	`gt up` / `gt down`
`gt restack`	`gt restack`
`gt submit --stack`	`gt submit --stack`
`gt sync`	`gt sync`
`gt land --stack`	`gt land --stack`
`gt modify --commit`	`gt modify --commit`
`gt continue` / `gt undo`	`gt continue` / `gt undo`

The stacked-branch metadata model — parent/child relationships stored in .git/config under branch.<name>.parent and branch.<name>.parentBase — is identical, so your existing stacks just work.

Step 1: install stkd

# macOS / Linux
brew install neul-labs/tap/stkd

# Rust
cargo install stkd-cli

# Node ecosystem
npm install -g stkd-cli

# Python ecosystem
pip install stkd-cli

Verify:

gt --version
# stkd 0.1.0

You can have both @withgraphite/graphite-cli and stkd-cli installed at the same time — they both expose gt, but only one wins on your PATH. If you want to test stkd without removing Graphite, install stkd via cargo (puts it in ~/.cargo/bin) and prepend that to PATH for the duration of your test.

Step 2: initialize the repo

In each repo where you have a Graphite stack:

cd path/to/repo
gt repo init

This is non-destructive. stkd reads the existing branch.<name>.parent config that Graphite already wrote, and stores its own additional config under the same keys (so Graphite still works if you ever switch back). Run gt log and your existing stacks should appear unchanged.

Step 3: re-link your provider (GitHub or GitLab)

stkd uses the standard provider auth flow — there is no SaaS to log into:

# GitHub
gh auth login              # if you don't already have a token
gt auth                    # stkd reads gh's stored credentials

# GitLab (cloud or self-hosted)
glab auth login            # or use a personal access token
gt auth --gitlab-host=gitlab.example.com

stkd reuses your existing gh or glab token under the hood. There’s no separate “stkd account.”

Step 4: smoke-test the workflow

In an existing stack, run:

gt log              # confirm your stack is visible
gt up               # navigate up the stack
gt submit --dry-run --stack    # confirm intended PR updates without pushing

If --dry-run shows what you expect, run it for real:

gt submit --stack

stkd will update the same PRs Graphite was managing — same numbers, same descriptions, same branches. The provider API doesn’t care which client made the change.

What’s different (and why)

A handful of small differences, mostly improvements:

`gt tui` — interactive stack browser

stkd ships with an interactive terminal UI (built with Ratatui). It’s a much faster way to navigate stacks than typing commands. Try gt tui once and you’ll wonder how you lived without it. See A tour of the stkd TUI.

`gt mcp` — AI agent integration

stkd-mcp exposes every stack command as an MCP tool. Add it to Claude Code’s config and the agent can gt_create, gt_submit, etc., natively — no shelling out. Graphite has no equivalent.

The optional web dashboard

stkd ships an optional, self-hostable web dashboard (REST + WebSocket) that gives your team a Graphite-web-like view of stacks, PRs, and merges — except you run it on your own infra, with your own auth. Spin it up only if you want it:

docker run -p 8080:80 ghcr.io/neul-labs/stkd-server

See Self-hosting the stkd dashboard.

No telemetry by default

Graphite ships with anonymized telemetry on by default (you can disable it). stkd ships with telemetry off — there is no telemetry endpoint. If you want crash reports, you can enable STKD_TELEMETRY=1 to send them to a self-hosted Sentry of your choice.

Apache-2.0 license

Graphite’s CLI is source-available; stkd is permissively licensed under Apache-2.0. You can vendor it, modify it, redistribute it. The license includes a patent grant.

Rolling back

If stkd doesn’t work for you, rolling back is trivial — Graphite’s CLI reads the same metadata stkd reads:

brew uninstall neul-labs/tap/stkd
brew install withgraphite/tap/graphite       # or whatever you used originally

Your stacks survive unchanged. There is no lock-in.

When stkd is not the right move

A few honest caveats:

You rely on Graphite’s web-app code-review features (in-app diff review, queue management, merge queue). stkd’s optional dashboard is more minimal — it shows stacks and PR status but doesn’t replace GitHub’s or GitLab’s review UI.
You depend on Graphite’s auto-submitter or background merge bot. stkd doesn’t have a hosted background service. You’d self-host the dashboard or run merges from CI.
You’re on a small team and Graphite Free covers you. If you’re inside the Graphite Free tier and don’t need GitLab or AI integration, the switch is mostly philosophical (open source vs SaaS). Switch only if that philosophy matters to you.