dif-sh/dif has 89 GitHub stars and 0 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 19:40 UTC. Last push 2026-11-09.
Measured star growth
- in 24h
- 0
- in 7 days
- Update delayed
- in 15 days
- Update delayed
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
Feature flags and A/B tests as Markdown files in your repo. dif build compiles them to a typed TypeScript client for Next.js, React, and SvelteKit.
Developer ToolsREADME.md
OriginalFeature flags and A/B tests that live in your repo as Markdown files.
One command to install. No signup. No dashboard to rot in.
Contents
- Quickstart
- The eight commands
- Why dif?
- What lands in your repo
- A flag / experiment
- Using the CLI
- Working with agents
- Analytics
- dif.sh Cloud
- Development
- License
Quickstart
npm install -g @dif.sh/cli
No Node? Install the standalone binary
# macOS / Linux: Homebrew
brew install dif-sh/tap/dif
# macOS / Linux: single static binary, no Node required
curl -fsSL https://dif.sh/install.sh | sh
Then, in your repo:
dif init # scaffold dif/, config, agent files
dif connect --key dif_pk_live_... # connect to dif.sh Cloud (optional)
dif new home-hero-cta --surface home # draft an experiment file
# open dif/experiments/active/home-hero-cta.md and set `status: active`
dif validate # check everything
dif build # generate the TS client + context.json
Or use the built-in skills. dif init installs Claude Code skills into
.claude/skills/, so you can drive the same loop in plain English and let the
agent run the commands:
| Skill | Ask for | What it does |
|---|---|---|
dif-generate-surfaces |
"Set up dif surfaces for this app" | Reads your routes and pages, proposes the surface set, writes the files |
dif-author-experiment |
"Add a flag for the new checkout, mobile only" | Drafts the frontmatter, picks weights, runs dif validate |
dif-conclude-experiment |
"Conclude checkout-cta-v2" | Gets the result from dif.sh Cloud, writes the decision from its numbers, archives the file, logs the learning |
dif-triage-experiments |
"Triage my experiments" | Reads the dif.sh Cloud overview, then ramps, turns off or concludes each experiment that needs action, one PR each |
dif-connect-cloud |
"Connect this repo to dif Cloud" | Signs the CLI in with a browser code, links or creates the dif.sh Cloud project, writes its key, runs dif build |
dif new drafts the file with your git email as owner. Open it, write the
hypothesis, set status: active, and run dif build. Then install the
runtime (npm install @dif.sh/sdk, zero dependencies), import the generated
client once at boot, and call dif() at the render site:
import "./dif/generated/client";
import { attributes } from "./dif/generated/audiences";
import { dif } from "@dif.sh/sdk";
dif.init({
userId: () => currentUser?.id ?? null,
attributes: () => attributes(),
});
const cta = dif("home-hero-cta", {
control: () => "Start free trial",
variant_a: () => "Try it free for 30 days",
});
button.textContent = cta();
dif init gitignores dif/generated/, so CI/deploy must run dif build
before the app build or it'll ship without a client. Add "prebuild": "dif build" to package.json and it happens automatically.
The npm packages (@dif.sh/sdk, @dif.sh/react, @dif.sh/svelte) are
ESM-only — there's no require() entry point.
Full documentation lives at www.dif.sh/docs.
The eight commands

| Command | What it does |
|---|---|
dif init |
Scaffold the dif.sh convention in the current directory. |
dif connect |
Connect the workspace to dif.sh Cloud with a publishable key. |
dif new |
Draft a new experiment, informed by the surface's prior learnings. |
dif validate |
Check the workspace: schema, owners, surface refs, exclusion graph. |
dif build |
Compile active experiments into a typed TS client + context.json. |
dif qa |
Trace the assignment chain for a user and emit a preview URL. |
dif conclude |
Move an experiment to concluded/, draft Decision, append to surface log. |
dif scaffold-audiences |
Idempotently scaffold the starter audience resolvers (locale, device_type). |
Why dif?
A feature flag is part of your codebase. So it should live in your repo.
Every flag and every experiment in dif is one Markdown file, checked into git next to the code it changes. It gets reviewed in a pull request. Its history is the git history. When it is done, the decision and what you learned go in the same file.
The alternative is what most teams have now. Flags live in a web dashboard,
disconnected from the code, and they rot there. Nobody remembers why
new-checkout-v2 exists or whether it is safe to delete, so it sits at 100%
for three years with a dead branch behind it. Experiment results end up in
someone's old Slack thread and the same failed test gets re-run two years
later.
Files also mean assignment can be a pure function. There is no assignment database and no network request to evaluate a flag, and a user never flips between variants across page loads or devices. The same math runs in the Rust CLI and the TypeScript SDK, locked by a shared test fixture that fails CI on both sides if the two implementations drift by a single bucket.
What lands in your repo
A flag / experiment
Both are the same file format. Here is a flag mid-ramp:
---
id: new-checkout
status: active
owner: [email protected]
surface: checkout
hypothesis: >
Inlining the address form will lift completed checkouts on mobile
without moving refunds.
audience:
include:
- device_type: [mobile, tablet]
exclude:
- plan: free
variants:
- id: "off"
weight: 90
summary: Current checkout
- id: "on"
weight: 10
summary: Rebuilt checkout with the address form inlined
metrics:
primary: completed_checkout
guardrails:
- refund_rate
exclusion_group: checkout
created: 2026-07-01
---
## Brief
Ramp to 25% once the guardrails hold for a week.
And an experiment:
---
id: checkout-cta-v2
status: active
owner: [email protected]
surface: checkout
hypothesis: >
A CTA that names the outcome ("Pay $49") beats the generic "Continue"
at the final step.
variants:
- id: control
weight: 50
- id: variant_a
weight: 50
metrics:
primary: completed_checkout
guardrails:
- refund_rate
exclusion_group: checkout
created: 2026-07-01
---
The only structural difference is the weights. A flag is an experiment you are ramping toward 100%. An experiment is one you are holding at a split until the numbers answer the hypothesis. Same schema, same bucketing math, same validator, same SDK call. An experiment that wins becomes a flag you ramp, and a flag you are unsure about becomes an experiment, without touching a line of application code.
(The shared exclusion_group is there because both are live on the checkout
surface at the same time. More on that below.)
Using the CLI
dif validate is a type checker for your experiments. Weights must total
100. Referenced surfaces and audience attributes
must exist. It also scans your application source for dif("...") call sites
and warns when code points at an experiment that is not in the repo. Run it
in CI and a broken flag fails the PR like a broken build.
It catches experiment collisions too. Two active experiments on
the same surface must either share an exclusion_group, which guarantees
each user sees at most one of them, or have audiences that provably cannot
overlap. If dif cannot prove separation, validation fails.
dif qa --user u_8131 --attr device_type=mobile shows which variant that
user gets and why. Add --force checkout-cta-v2=variant_a and it also returns a preview link (?_dif=...) that pins the variant in a browser. Forced assignments don't fire exposure events.
dif conclude records the decision, dates it, moves the file to
dif/experiments/concluded/, and appends a one-line learning to the surface.
The next dif new on that surface reads those learnings into the draft, so
the same failed idea does not get rebuilt by someone new in two years.
dif build compiles everything the runtime needs: a typed client at
dif/generated/client.ts, audience resolvers, event delivery, and
dif/context.json for your agent.
Working with agents
dif init merges a managed block into CLAUDE.md, AGENTS.md, and
.github/copilot-instructions.md, writes a Cursor project rule to
.cursor/rules/dif.mdc, and installs Claude Code skills for authoring
experiments, concluding them, triaging them from dif.sh Cloud results, and
generating surfaces. dif build writes
dif/context.json: every active experiment, plus the most recent learning on
each surface. Re-running dif init is safe: when the files dif owns already
match, it exits 0 and only refreshes the managed blocks.
Use --agents to scaffold only a subset: a comma-separated list of claude
(CLAUDE.md + the .claude/skills/dif-* skills), general (AGENTS.md),
cursor (.cursor/rules/dif.mdc), copilot
(.github/copilot-instructions.md), or none. Omit the flag to install all
four. --agents none writes no agent files (the former --no-agent-files,
now a hidden alias). A dif block left in .cursorrules by an older dif is
refreshed; a new .cursorrules is never created.
After you upgrade dif, run dif init --agents-only to get the new skills and
agent guidance. It rewrites the .claude/skills/dif-* skills and
.cursor/rules/dif.mdc, and refreshes the managed blocks. It never touches
dif/, so your config, surfaces and learnings stay as they are. Combine it
with --agents to refresh a subset.
The same skills, plus a dif-docs reference skill, install into Codex,
Cursor, Copilot, and the other agents the skills CLI
supports, without running dif init first:
npx skills add dif-sh/dif
The conclude and triage skills read results from dif.sh Cloud, through its
MCP server at https://cloud.dif.sh/mcp (set up with a read token) or a read
token in the DIF_TOKEN environment variable. The dif CLI itself makes no network calls. See
MCP and API.
This is the part a dashboard cannot do. In dif the flags are
files, so the agent reads them like any other source and writes them the same
way. Tell it to add a flag for the new checkout and it can draft the file,
gate the code path, and run dif validate to check its own work.
Analytics
You can run dif with no analytics at all. Assignment is local, so flags and
ramps work with nothing configured. Cloud mode is opt-in too: without a
publishable key, dif records nothing to Cloud until you run dif connect.
The SDK logs one console warning that exposures and track() will be dropped,
and flags still evaluate.
When you want more analysis, connect to dif.sh Cloud. Copy the command from cloud onboarding and run it in your repo:
dif connect --key dif_pk_live_... # writes the key to dif/config.yaml, turns on cloud mode
New project? dif init --key dif_pk_live_... scaffolds and connects in one
step. Either way the key lands in dif/config.yaml (it's a publishable key,
safe to commit) and dif build bakes it into the generated client — so init
stays clean, with no env var and no key pasted into code:
import { events } from "./dif/generated/events"; // cloud config + your key
dif.init({
events,
userId: () => currentUser?.id ?? null,
});
If you already have an events pipeline, run dif init --events custom
instead. That scaffolds dif/events/exposure.ts and dif/events/track.ts,
two handlers you own. Forward events to Segment, Amplitude, a webhook, or
whatever you run; dif does not care where they go. There are no bundled
third-party integrations, just those two functions.
Metric tracking is one call either way:
dif.track("completed_checkout");
dif.track("revenue", { value: 49 });
dif.sh Cloud
Cloud handles event ingest, metrics, and statistical analysis. It runs hosted at cloud.dif.sh. Nothing in the core requires it — the files in your repo stay the source of truth.
Pulse — read an experiment while it runs: lift, confidence, exposures, and the hypothesis you wrote in the file sitting right next to the chart.

Suggestions — dif reads your surfaces, your concluded experiments, and the
behaviour in your data, then drafts the next test with a hypothesis and an
expected lift. Copy the brief straight into dif new.

History — every concluded experiment across every surface, with the outcome, the lift, and who approved it. The same learnings that get appended to your surface files.

Development
cli/
crates/dif-core/ # parser, validator, bucketing, codegen (Rust)
crates/dif-cli/ # the `dif` binary
packages/cli/ # @dif.sh/cli, the npm wrapper
packages/sdk/ # @dif.sh/sdk, the runtime SDK (TypeScript, zero deps)
packages/react/ # @dif.sh/react
packages/svelte/ # @dif.sh/svelte
dist/ # install.sh + Homebrew tap template
cd cli
cargo test --workspace # Rust: parser, validator, codegen
cd packages/sdk
npm install && npm test # TS
License
MIT. See LICENSE.