Get started
← Blog

Feature flags for AI agents: flags your coding agent can read

Jul 20, 2026

Feature flags for AI agents means keeping your flags where a coding agent can actually read them: in the repo, as files, not in a dashboard the agent cannot open. An agent working in your codebase reads a flag file like any other source, and can add or change one through a pull request.

A coding agent like Claude Code or Cursor works by reading and editing the files in your repo. It cannot log into your feature-flag dashboard. So it does not know a flag exists, and it will delete the dead-looking branch behind a live flag, or write code that references a flag name that was never created. As more of your codebase is written and maintained by agents, the flags they cannot see turn into a steady source of bugs.

This post covers why dashboards are invisible to coding agents, what agent-readable feature flags look like, and how an agent can create and validate a flag on its own.

Key Takeaways

  • Feature flags for AI agents means the flag is a file in the repo, so a coding agent reads it like any other source and can edit it in a pull request.
  • A flag in a hosted dashboard is invisible to an agent: it cannot open the UI, so it deletes branches behind live flags and references flags that do not exist.
  • The AGENTS.md standard, backed by Google, OpenAI, and Cursor, already established that agents read Markdown instruction files in the repo. dif writes flag context into those files.
  • dif build emits a context.json of every active flag and each surface’s learnings, which an agent reads on session start. A dashboard cannot hand it that.
  • Because dif validate runs in CI, an agent that writes a broken flag fails the build, so its work is checked the same way a human’s is.

Why a dashboard is invisible to a coding agent

A coding agent reads your repository. That is the whole mechanism: it opens files, follows imports, and edits source. A hosted feature-flag dashboard is not in the repository, so the agent cannot see it, and three failures follow.

  • It deletes live code. The agent finds a code path gated on a flag, sees no reason for it in the repo, and treats the dead-looking branch as dead code. The reason lived in a dashboard it cannot open, so it removes a branch that is behind a live experiment.
  • It invents flags. Asked to gate a feature, the agent writes if (flags.newThing) against a flag that was never created in the dashboard. Nothing connects the two, so nothing catches the mismatch until runtime.
  • It repeats work. It cannot see that a feature is already behind a flag, so it builds the thing a second time.

Each failure has the same cause: the source of truth for the flag lives somewhere the agent does not read. The agent reads the repo. The flag is not in the repo.

Agent-readable flags are just files

The fix is not an AI feature. It is putting the flag where the agent already looks. When each flag is a Markdown file in the repo, the agent reads it the same way it reads a function.

This is already how agents get their bearings. The AGENTS.md standard, launched by Google, OpenAI, and Cursor and now read by more than 20 coding tools, established a predictable Markdown file in the repo root that agents read to understand a project. Claude Code reads CLAUDE.md the same way. Agents already read Markdown in your repo, so that is where flags belong too.

dif is built on exactly that. dif init writes a managed block into AGENTS.md, CLAUDE.md, and .cursorrules explaining how flags work in this repo. dif build compiles the active flags into a context.json that lists every live flag and each surface’s latest learning, roughly:

{
  "flags": [
    {
      "id": "new-checkout",
      "surface": "checkout",
      "status": "active",
      "variants": ["off", "on"],
      "note": "ramping, 10% on mobile"
    }
  ],
  "surfaces": {
    "checkout": {
      "last_learning": "benefit-led CTA lifted completed_checkout 2.1%"
    }
  }
}

An agent reads that on session start, so it knows which code paths are gated, what is being tested, and what has already been concluded, before it touches a line. That is the part a dashboard cannot give it, and it is the same files-in-the-repo model that makes flags reviewable in a pull request.

Letting an agent create a flag

Because a flag is a file with a schema, an agent can write one. Ask it to gate a feature and it drafts the flag file, adds the dif("flag-id") call at the render site, and the whole change goes through review like anything else it writes.

The safety net is the validator. dif validate runs in CI and checks that the weights total 100, the owner is a real email, and no code references a flag that is not in the repo. When an agent writes a flag, its work is checked exactly like a human’s: a broken flag fails the pull request. The same gate that catches your mistakes catches the agent’s, so it cannot quietly ship a malformed flag. dif also installs agent skills for authoring and concluding experiments, so the agent follows the repo’s conventions instead of guessing at them.

Flags and experiments for AI features

The same files are useful for the AI features you ship, not only the agents that write them. Rolling out a new model, testing two prompts, or gating an agentic feature is a flag or an experiment like any other. The variants are prompt_a and prompt_b, the primary metric is whatever the feature is for, and a guardrail watches latency or cost so a better answer that doubles the bill does not count as a win.

Because it is a file, the change is reviewed and versioned. Because a flag and an experiment share a format, a prompt test that wins becomes the default by editing the weights, without touching the call site. If you are experimenting on AI features, A/B testing for developers covers the lifecycle, and it applies to a prompt the same way it applies to a checkout button.

Getting started

If your codebase is increasingly written by agents, the flags they manage should be where they read. Install the CLI and scaffold a project:

npm install -g @dif.sh/cli
dif init

dif init writes the dif/ directory, the managed AGENTS.md and CLAUDE.md blocks, and the generated client. dif build emits the context.json the agent reads, and dif validate checks its work in CI. The feature flags page shows the workflow, and the docs cover install.

None of this is an AI feature bolted onto a flag tool. It is the ordinary consequence of flags being files: the agent that reads your code reads your flags too, and the validator that checks your flags checks the ones it writes.

FAQ

Can an AI coding agent manage feature flags? Yes, when the flags are files in the repo. A coding agent reads and edits repo files, so it can read a flag, create one, and gate the code, and its change goes through review and CI like any other. It cannot manage flags that live in a dashboard it has no way to open.

Why can’t a coding agent use a feature-flag dashboard? The agent operates on your repository, not a web UI behind a login. A dashboard’s flag state is not in the files it reads, so the agent cannot see which flags exist or why. That is why it deletes branches behind live flags and references flags that were never created.

What is context.json in dif? A file that dif build generates, summarizing every active flag and each surface’s latest learning. A coding agent reads it on session start to know what is gated and what has already been tried, which is context a dashboard cannot pass to an agent.

Can I use feature flags to A/B test AI features like prompts or models? Yes. A prompt test or a model rollout is an experiment like any other: two variants, a primary metric, and a guardrail on cost or latency. In dif it is the same Markdown file as any flag, so the winner ships by editing the weights.

Does dif work with Claude Code and Cursor? Yes. dif init writes managed blocks into CLAUDE.md, AGENTS.md, and .cursorrules, the instruction files those tools already read, and context.json gives them the live flag state. No dashboard integration is needed, because everything is a file.

Is “agent-native” just marketing? It is a concrete mechanism, not a label: flags are files the agent reads, context.json hands it the live state, and dif validate checks the flags it writes. The test is simple. Ask your current flag tool whether a coding agent can read and create a flag without opening a dashboard.