dif-sh/dif/dif-docs

dif.sh reference

dif keeps each feature flag or A/B experiment as one .md file under dif/experiments/, checked into git with the code it gates. dif validate checks the files, dif build compiles them to dif/generated/client.ts, and @dif.sh/sdk (zero dependencies) assigns variants locally at runtime. No signup, no network call to evaluate a flag.

Add dif to an app

npm install -D @dif.sh/cli          # or: curl -fsSL https://dif.sh/install.sh | sh
npm install @dif.sh/sdk
npx @dif.sh/cli init                        # scaffolds dif/, config, agent files
npx @dif.sh/cli new new-checkout --surface home
# edit dif/experiments/active/new-checkout.md: variants, weights, status: active
npx @dif.sh/cli validate
npx @dif.sh/cli build

dif/generated/ is gitignored, so add "prebuild": "dif build" (and "predev": "dif build") to package.json, or CI and deploys ship without a client.

The flag file

---
id: new-checkout
status: active
owner: sam@acme.com
surface: checkout
hypothesis: >
  Inlining the address form lifts completed checkouts on mobile.
variants:
  -id: "off"
    weight: 90
  -id: "on"
    weight: 10
metrics:
  primary: completed_checkout
created: 2026-07-01
---

A flag is an experiment you ramp toward 100%; an experiment holds a split. Same schema. The first variant is the fallback. Weights must sum to 100.

The call site

import "./dif/generated/client";                  // once, at boot: registers every active flag
import { attributes } from "./dif/generated/audiences";
import { dif } from "@dif.sh/sdk";
dif.init({ userId: () => currentUser?.id ?? null, attributes: () => attributes() });
const checkout = dif("new-checkout", {
  off: () => <OldCheckout />,
  on: () => <NewCheckout />,
});

dif validate warns (W001) when a call site names an id that isn't an active experiment. At runtime, an unknown id or a variant with no matching branch renders the first branch and fires no exposure. For server rendering, use the pure assign(id, { userId, attributes }) export instead of dif(); @dif.sh/react and @dif.sh/svelte wrap both.

Docs (markdown)

• Overview, install, workspace layout: https://dif.sh/docs.md
• File format (frontmatter, audiences, exclusion groups): https://dif.sh/docs/format.md
• CLI (init, connect, new, validate, build, qa, conclude, scaffold-audiences): https://dif.sh/docs/cli.md
• SDK (dif(), assign(), React and Svelte adapters, dif.track()): https://dif.sh/docs/sdk.md
• dif/config.yaml: https://dif.sh/docs/config.md
• Events (cloud vs custom delivery): https://dif.sh/docs/events.md
• Validation codes (E001–E010, W001–W005): https://dif.sh/docs/troubleshooting.md
• dif cloud MCP server and read API (tools, REST endpoints, read tokens, verdicts): https://dif.sh/docs/mcp.md
• Full index: https://dif.sh/llms.txt
• Source: https://github.com/dif-sh/dif

Workflow skills

Install the workflow skills with npx skills add dif-sh/dif: dif-author-experiment (draft and validate a flag or experiment), dif-conclude-experiment (get the result from dif cloud, check the verdict, record the decision and archive), dif-triage-experiments (review every active experiment in the dif cloud overview, then ramp, turn off or conclude the ones that need action, with one PR each in autonomous mode), dif-generate-surfaces (propose dif/surfaces/ from the app's routes). dif init also writes them into .claude/skills/. The conclude and triage skills read dif cloud through its MCP server at https://cloud.dif.sh/mcp (set up with a read token) or a read token in DIF_TOKEN. Setup: https://dif.sh/docs/mcp.md