AI-native

How do you clean up stale feature flags?

Find the release flags that have been fully on and stable for a while, about 30 days in most tools, then remove each flag check and its old code path in a small pull request, deploy, and only then archive the flag. Code first, archive second, so no running service checks a flag that's gone.

Updated November 17, 2026

What is flag debt?

The cost of flags left in code after they've done their job. Every flag doubles the paths through a piece of code; once a feature is on for everyone, the off path is dead code, its tests test nothing real, and the check is a place where a wrong click could still turn the feature off. Teams whose AI agents create a flag for every change pile up flags faster than anyone remembers them. See what a feature flag is.

Which flags should stay?

Not every old flag is debt. Flagger.gg's guide to flag cleanup separates two kinds:

  • Release flags are temporary. They hide a feature until it's ready. Once one is on for everyone and stable, it should go.
  • Operational flags are permanent. A kill switch for a payment provider or an expensive job is meant to stay, so you can turn the feature off in an incident. Say so in the flag's description, so neither a person nor an agent removes it by mistake.

For what to keep behind a permanent switch, see kill switch or rollback.

How do you find the stale ones?

A release flag is a candidate when it has been on for everyone for a while, or when no code checks it any more. In Flagger.gg, flagger list --state on lists flags fully on in production, each flag's history shows when it got there, and a flag that no app has registered in an environment for 30 days loses its "in code" mark. Flags an agent created through the API that never reach code show "Not in code yet" in the console. With --json, an agent can build the list itself:

flagger list --state on --json | jq -r '.flags[] | [.key, .inCode, .updatedAt] | @tsv'

How do you remove a flag safely?

  1. Confirm it's done: on in production long enough that you wouldn't turn it off, and not an operational flag.
  2. Remove the code: the check, the old path, its declaration and the off-branch tests, in one small pull request per flag.
  3. Deploy, leaving the flag on meanwhile so anything still checking it keeps the feature on.
  4. Archive it once no app registers it. An archived flag is left out of the rules SDKs download, so a check you missed falls back to off, which is why the code goes first.

In Flagger.gg, archiving is for people and admin tokens; agent tokens can't archive.

Can an AI agent do the cleanup?

The code removal, yes: it's mechanical and needs no judgment about the flag itself. Give the agent a token with only the read action, ask it to list long-on flags and open one pull request per flag removing the check and the old path, and have a person archive each flag after the change is merged and deployed. Automated stale-flag detection that opens cleanup pull requests is listed as in development on Flagger.gg. See how AI agents should write pull requests.

How do you stop debt from building up?

Decide the exit when the flag is created. Give every flag an owner, and say in its description whether it's a release flag ("remove after the new checkout is on for everyone") or a permanent one ("kill switch: keep"). Keep one flag per change, since a flag that guards three features is never easy to remove, and declare flags in code; see typed feature flags.

Frequently asked questions

How long should a feature flag live?

A release flag should go once its feature is on for everyone and stable; many tools treat 30 days as stale. Operational kill switches are meant to stay.

Should I archive a flag before removing its code?

No. Remove the code and deploy first, then archive, so no running service checks a flag that no longer exists.

Can an AI agent archive flags in Flagger.gg?

No. Archiving is for people and admin tokens. An agent can do the code removal with a read-only token.

Does Flagger.gg clean up stale flags automatically?

Not yet. Automated cleanup pull requests are listed as in development; today the in-code marks and each flag's history show what to remove.