Feature flags are created in minutes and removed never. After a year a codebase carries dozens of permanently-on toggles, dead branches nobody dares touch, and flags referenced in code that no one ever declared. That debt is invisible until it causes an incident.
This agent correlates your flag registry with the actual references in your codebase, classifies every flag, and emits a ranked removal plan — safest and cheapest removals first.
Install
sudo bash install.sh # deps + venv + systemd service
bash install.sh --no-service # venv only
Use
python agent.py scan # flag references found in the code
python agent.py audit # registry x code -> classified findings
python agent.py plan # ranked removal plan (lowest blast radius first)
python agent.py report # human-readable debt report
python agent.py status # config + LLM backend status
python agent.py run --once # one full cycle, writes the report
Point it at your data with FLAGS_REGISTRY and FLAGS_CODE_ROOT — see
CUSTOMIZE.md.
What it detects
| Verdict | Meaning |
|---|---|
ORPHAN |
referenced in code but absent from the registry — nobody owns the behavior |
EXPIRED |
its own expected_removal_date has passed |
ZOMBIE |
declared with zero code references — pure registry rot |
STALE |
100% rolled out for months — the disabled branch is dead code |
RISKY_KILL_SWITCH |
emergency switch with no owner or no code path |
AGED_EXPERIMENT |
experiment past any statistically useful window |
UNOWNED |
no accountable owner |
Each flag gets a weighted score; the total is your debt score. Use
run --once --fail-over-budget as a CI gate.
Bring your own LLM (optional)
Classification is fully deterministic and needs no LLM — the agent is
complete offline. If a coding-agent CLI (Claude Code / Kimi Code / Codex) is
logged in, it is used to review the removal ordering and flag operational
risks, using the prompts in PROMPTS.md. No API key is ever required: your CLI
subscription is the billing relationship.
By design the LLM can only annotate findings the deterministic rules already produced. A hallucinating model cannot invent a flag or change a verdict.
Tests
bash smoke_test.sh # 13 offline tests, no keys, pinned clock
Languages scanned
Python, JS/JSX, TS/TSX, Go, Ruby, Java, Kotlin, PHP, C#, Rust, YAML and JSON,
via 9 built-in SDK call patterns — extend with FLAGS_EXTRA_PATTERNS.