# FlagShark — Complete Reference

> FlagShark is an automated feature flag lifecycle management platform that integrates with GitHub to detect, track, and clean up stale feature flags using deterministic tree-sitter AST parsing.

FlagShark monitors pull requests, identifies feature flag additions and removals via syntax-aware AST parsing (not regex or AI), tracks flag lifecycle in a dashboard with health scores, and automatically creates safe cleanup PRs to remove dead code. It supports 13 languages, 8+ flag providers, and installs as a GitHub App in 30 seconds.

- Website: https://flagshark.com
- Documentation: https://flagshark.com/docs
- GitHub App: https://github.com/apps/flagshark
- Contact: https://flagshark.com/contact
- Security: joe@flagshark.com

---

## What Is FlagShark?

FlagShark is an automated feature flag lifecycle management platform that integrates with GitHub to detect, track, and clean up stale feature flags across your codebase using deterministic tree-sitter AST parsing. It monitors pull requests, identifies when flags are added or removed, and creates safe cleanup PRs to eliminate technical debt.

### How Does FlagShark Work?

FlagShark works in four steps, from installation to your first cleanup PR in under 3 minutes:

1. **Install the GitHub App** — Connect FlagShark to your GitHub repositories in under 30 seconds. No code changes, no CI pipeline modifications required.
2. **Automatic flag detection** — FlagShark monitors every pull request, parses code diffs using tree-sitter AST parsing, and identifies feature flag additions and removals.
3. **Lifecycle tracking** — Every detected flag is tracked in a dashboard with health scores, age metrics, and ownership data so your team always knows which flags need attention.
4. **Automated cleanup PRs** — When flags become stale, FlagShark creates safe cleanup pull requests that deterministically remove dead code while preserving business logic.

### Who Is FlagShark For?

- Engineering teams using feature flags in production
- Platform and DevOps teams managing flag infrastructure
- Engineering managers tracking technical debt
- Teams using LaunchDarkly, Unleash, Split.io, or custom flag implementations

### What Makes FlagShark Different?

1. **Tree-sitter AST parsing, not regex** — FlagShark parses your code into abstract syntax trees for accurate detection. No false positives from comments, strings, or variable names.
2. **100% deterministic transforms** — Cleanup PRs use deterministic code transformations, not AI-generated suggestions. The output is always syntactically valid and semantically correct.
3. **PR-based workflow** — FlagShark never modifies your code directly. Every change comes as a standard pull request that your team reviews and merges through your existing workflow.

---

## Supported Languages

FlagShark uses tree-sitter parsers for accurate syntax-aware detection across 13 programming languages:

- Go
- TypeScript
- JavaScript
- Python
- Rust
- C#
- Java
- Kotlin
- Ruby
- PHP
- Swift
- C++

## Supported Flag Providers

FlagShark works with all major feature flag platforms and custom implementations:

- LaunchDarkly
- Unleash
- Split.io
- PostHog
- Flagsmith
- ConfigCat
- Flipt
- Custom implementations (via YAML config)

Flag providers are configured via a `.flagshark.yaml` file in your repository. You can define custom flag patterns for proprietary solutions.

---

## Pricing

### Free — $0/forever
- 1 seat, 3 repositories, 50 flags/month, 30-day data retention
- Includes: Real-time flag detection, flag lifecycle tracking, PR comments and health scores
- No credit card required

### Team — $99/month (Most Popular)
- 5 seats included (+$12/extra seat), 15 repositories included (+$4/extra repo), unlimited flags/month, 90-day data retention
- Annual billing: $950/year (20% discount)
- Includes everything in Free plus: Automated cleanup PRs, Slack and LaunchDarkly integration, role-based access control

### Business — $249/month
- 15 seats included (+$10/extra seat), 50 repositories included (+$3/extra repo), unlimited flags/month, 1-year data retention
- Annual billing: $2,390/year (20% discount)
- Includes everything in Team plus: Custom webhooks and API access, SSO and SCIM available, priority support available

### Enterprise — Custom pricing
- Unlimited seats, unlimited repositories, unlimited flags/month, unlimited data retention
- Includes all features, dedicated account manager, custom SLA, custom onboarding
- Contact joe@flagshark.com

### Add-Ons
- SSO (SAML/OIDC): $150/month (included in Enterprise)
- Directory Sync (SCIM): $150/month (included in Enterprise)
- SSO + SCIM Bundle: $250/month (17% savings, included in Enterprise)
- Priority Support: $99/month (included in Enterprise)
- Audit Log Export: $49/month (included in Enterprise)

---

## Security

FlagShark is built with security-first principles.

### Key Security Features

- **No source code storage** — Code is analyzed in isolated AWS Lambda environments and discarded after processing. Only flag metadata (names, file locations, lifecycle status) is persisted.
- **Minimal GitHub permissions** — Three permissions only: Contents (Read) to analyze code, Pull Requests (Write) to create cleanup PRs, and Metadata (Read) for repository info. No access to secrets, environment variables, or admin settings.
- **Isolated processing** — Each repository analysis runs in an isolated AWS Lambda environment. Your code never mixes with other customers.
- **Encryption** — AES-256 encryption at rest, TLS in transit, AWS KMS for secrets management.

### Compliance

- SOC 2 Type II: In progress
- GDPR Ready: Data deletion available on request
- Data Retention: Scan results auto-delete after 30 days; flag lifecycle data retained while account is active

### Data Handling

**What we store:** Flag metadata (names, file paths, status), repository identifiers, processing timestamps, PR creation records, GitHub usernames (for flag attribution).

**What we never store:** Source code, secrets or credentials, environment variables, private developer information.

---

## Frequently Asked Questions

### Getting Started

**What is FlagShark?**
FlagShark is an automated feature flag lifecycle management platform. It integrates with GitHub to detect stale feature flags in your codebase and generates cleanup pull requests to remove them safely. Think of it as automated technical debt reduction for your feature flag infrastructure.

**How does FlagShark detect feature flags?**
FlagShark uses tree-sitter AST (Abstract Syntax Tree) parsing to analyze your code with 100% accuracy. Unlike regex or AI-based approaches, AST parsing understands your code's actual structure, ensuring real flag usage is identified without false positives.

**What programming languages are supported?**
FlagShark supports 13 languages: Go, TypeScript, JavaScript, Python, Rust, C#, C++, Java, Kotlin, PHP, Ruby, Swift, and Objective-C.

**What feature flag providers do you support?**
LaunchDarkly, Unleash, Split.io, Optimizely, Flagsmith, ConfigCat, PostHog, Flipper (Ruby), and custom implementations. You can configure custom flag patterns via .flagshark.yaml for proprietary solutions.

**How do I sign up?**
Sign up using your GitHub account for instant access, or create an account with email and password. GitHub sign-in is recommended as it streamlines the repository connection process.

### How It Works

**How does FlagShark determine if a flag is safe to remove?**
FlagShark analyzes multiple signals: flag age, PR history, and code context using tree-sitter AST parsing. Flags that have been at 100% rollout for extended periods are identified as stale candidates. For LaunchDarkly users, flags removed from LaunchDarkly but still in code are also detected.

**Will FlagShark work with our CI/CD pipeline?**
Yes. FlagShark operates via GitHub webhooks and creates standard pull requests. It integrates seamlessly with GitHub Actions, Jenkins, CircleCI, or any CI/CD system — no pipeline changes required.

**How long does it take to see results?**
You'll see your complete flag inventory and health scores within minutes of installation. Most teams create their first cleanup PR the same day. Significant codebase improvements are typically visible within 1-2 weeks.

**Can we mark critical flags to prevent removal?**
Yes. FlagShark supports "permanent flag" protection. Mark any flag as critical, and it will be excluded from cleanup recommendations and stale alerts.

**Does FlagShark work with monorepos?**
Yes. FlagShark handles multi-workspace setups with hundreds of repositories. Organize repos into teams with role-based access control, and use bulk operations for cleanup at scale.

**Do you support GitLab or Bitbucket?**
Currently GitHub-only via native GitHub App integration. GitLab and Bitbucket are on the roadmap.

### Security & Privacy

**Does FlagShark store my source code?**
No. Code is analyzed in isolated AWS Lambda environments and discarded after processing. Only metadata is stored — flag names, file locations, and lifecycle status.

**What GitHub permissions does FlagShark need?**
Three permissions: Contents (Read), Pull Requests (Write), and Metadata (Read). FlagShark never accesses secrets, environment variables, or admin settings.

**Is FlagShark SOC 2 compliant?**
SOC 2 Type II certification is in progress. FlagShark uses AES-256 encryption at rest, TLS in transit, and AWS KMS for secrets management. GDPR-ready with data deletion available on request.

**What if we accidentally remove a critical flag?**
FlagShark creates pull requests — you review and approve before anything merges. Your team has full control to test, discuss, and catch concerns. No automated merging without your approval.

### Pricing

**Is there a free tier?**
Yes. FlagShark Free includes up to 3 repositories, 50 flags, core detection features, and 30-day data retention — free forever. Paid plans start at $99/month.

**Can I try FlagShark before paying?**
Yes. The free tier is available forever with full platform access. You can also start a 14-day trial of Team or Business plans with no credit card required.

**Can I change plans later?**
Yes. You can upgrade, downgrade, or cancel at any time. Changes are prorated.

**Do you offer annual billing discounts?**
Yes. Pay annually and get 20% off (2+ months free) on Team and Business plans.

**How do I calculate the ROI?**
Use the ROI calculator at flagshark.com/tools/roi-calculator to estimate savings based on your team size and flag count. Most teams see ROI within the first month.

---

## Feature Flag Technical Debt

### What Is Feature Flag Technical Debt?

Feature flag technical debt is the accumulation of stale, unused, or forgotten feature flags in your codebase. These flags were added for legitimate purposes — safe deployments, A/B testing, gradual rollouts — but remained in the code long after serving their purpose.

According to Stripe's Developer Coefficient, developers spend 33-42% of their time dealing with technical debt and maintenance. Feature flags contribute to this burden when not properly managed.

### Why Feature Flag Debt Matters

- **Code Complexity** — Each flag adds conditional branches that obscure the code's true behavior
- **Cognitive Load** — Developers spend 10x more time reading code than writing it (Robert C. Martin). Stale flags make reading harder.
- **Hidden Risk** — Dormant flag code can be accidentally activated. The Knight Capital incident showed how reusing a flag bit led to $460 million in losses in 45 minutes.
- **Testing Burden** — Each flag multiplies test scenarios. With N flags, you potentially have 2^N combinations.

### Why Flags Accumulate

- **Success Creates Inertia** — After a successful rollout, teams move to new priorities
- **Fear of Breaking Things** — Removing code always carries some risk
- **Lost Context** — Original developers move on, documentation is sparse
- **No Clear Owner** — Flag cleanup exists in a responsibility vacuum
- **Invisible Cost** — Stale flags don't cause immediate outages; their cost is gradual

### Types of Feature Flag Debt

- **100% Rolled Out Flags** — Features fully released but flag code remains
- **Orphaned Flags** — Referenced in code but not defined in any management system
- **Stale Flags** — Haven't been modified in months
- **Expired Experiment Flags** — A/B tests concluded but both code paths remain

### Best Practices for Managing Flag Debt

1. **Set Expiration Dates** — Most release flags should live for days to weeks, not months
2. **Assign Clear Ownership** — Every flag should have an owner for its entire lifecycle
3. **Automate Detection** — Manual tracking doesn't scale as flag count grows
4. **Remove at 100% Rollout** — When a flag reaches 100%, the flag has served its purpose

---

## Comparisons

### Manual vs Automated Feature Flag Cleanup

Manual flag removal takes an average of 2.5 hours per flag and involves searching the codebase, verifying rollout states, understanding conditional logic, carefully removing code, and updating tests. Teams report that 73% of flags never get cleaned up manually.

Automated cleanup with FlagShark uses AST parsing to instantly find all flag references, automatically detects flags at 100% rollout, applies safe code transformations, and creates automated PRs. What takes a developer 2.5 hours is completed in under 2 minutes with higher accuracy.

**ROI comparison for a team of 15 developers:**
- Manual cleanup: ~$125,000+/year (including hidden costs)
- FlagShark: ~$1,200/year
- First year savings: $123,000+

### FlagShark vs Uber Piranha

Piranha is Uber's open-source AST-based CLI tool for removing stale feature flags. FlagShark is an automated platform built on similar AST technology but with higher-quality removal, continuous monitoring, lifecycle tracking, and a full dashboard.

**Key differences:**
- Piranha requires manual CI/CD integration; FlagShark installs in 2 clicks
- Piranha requires you to identify which flags to remove; FlagShark detects stale flags automatically
- Piranha outputs raw AST transformations; FlagShark post-processes for cleaner, more idiomatic code
- Piranha has no dashboard or lifecycle tracking; FlagShark provides full analytics
- Piranha supports 7+ languages; FlagShark supports 11 with unified config

**Cost comparison:**
- Piranha: $0 license, but $10,000+ in year-1 engineering time for setup, rule tuning, and maintenance
- FlagShark: ~$1,200/year with zero maintenance

### Build vs Buy

Building a feature flag cleanup tool in-house requires 3-6 months of development, $75k-$150k in engineering costs, and ongoing maintenance forever. Components needed include AST parsing engine, multi-language support, GitHub integration, flag provider integrations, database for lifecycle tracking, dashboard UI, auth/authorization, CI/CD pipeline, and monitoring.

**Cost comparison:**
- Build: $93k-$186k in Year 1 (development + maintenance)
- FlagShark: ~$1,200 in Year 1
- Time to first value: 6+ months (build) vs 5 minutes (FlagShark)

### FlagShark vs Flag Providers

Flag providers (LaunchDarkly, Split, Unleash, Flagsmith) bill based on usage metrics that increase with more flags — MAU, evaluations, seats, API requests. Their business model is fundamentally at odds with flag cleanup. More flags means more evaluations means higher bills.

FlagShark is the only tool aligned with your interests: fewer flags, lower bills, cleaner code. It works across all providers and is vendor-neutral by design.

### FlagShark vs Reflag

Both tools automate feature flag cleanup but take fundamentally different approaches:

- **FlagShark** is a cleanup-only tool that integrates with your existing providers (no migration required). Uses deterministic AST-based code transformation. Supports Go, Python, Java, TypeScript, and 8 more languages. 100% reproducible results.
- **Reflag** is a full platform replacement (requires migration). Uses AI-generated code changes (probabilistic). Focused on the TypeScript/React ecosystem. Non-deterministic outputs.

Choose FlagShark if you already use LaunchDarkly/Split.io, need backend language support, work in a regulated industry, or want to avoid vendor lock-in.

---

## Solutions

### GitHub Integration

Seamless PR-based workflow with automated flag detection and cleanup pull requests. Features include automated PR comments, multi-language support, real-time analysis, and secure GitHub App installation. Setup takes 5 minutes.

### LaunchDarkly Cleanup

Purpose-built for teams using LaunchDarkly. Detects and removes stale feature flags automatically. Includes SDK pattern detection, rollout analysis, safe flag removal, and PR automation. Average savings: $156k/year, 180 flags removed on average in 3 weeks.

### Platform Capabilities

- **Automated Detection** — AST-powered analysis finds feature flags across your entire codebase
- **Safe Removal** — Deterministic code transformation preserves business logic while removing flag checks
- **PR Workflow** — Automated pull requests with detailed analysis, ready for review
- **Continuous Monitoring** — Track flag lifecycle and get alerts when flags are ready for cleanup

### ROI Statistics

- 85% reduction in flag management time
- 90% fewer flag-related bugs
- 3-day average payback period
- $125k+ annual savings
- 5+ hours saved weekly

---

## Glossary

Key feature flag terminology:

- **A/B Testing Flag** — A feature flag used to split traffic between different versions of a feature for experimentation and optimization.
- **Canary Release** — A deployment strategy where new features are gradually rolled out to a small subset of users before full release, controlled by feature flags.
- **Circuit Breaker Pattern** — A feature flag pattern that automatically disables features when they fail, preventing cascading failures.
- **Dark Launch** — Deploying new code to production without making it visible to users, controlled by feature flags for testing in real production environments.
- **Dead Code** — Code that is never executed because the controlling feature flag has been permanently disabled or the feature has been fully rolled out.
- **Feature Flag** — A software development technique that allows teams to enable or disable functionality without deploying new code, also known as feature toggles.
- **Feature Flag Debt** — The accumulated cost and complexity from maintaining obsolete or unnecessary feature flags in a codebase over time.
- **Feature Flag Lifecycle** — The stages a feature flag goes through from creation to removal: development, testing, rollout, full deployment, and cleanup.
- **Flag Retirement** — The process of removing feature flags and their associated code branches after they are no longer needed.
- **Flag Sprawl** — The uncontrolled proliferation of feature flags in a codebase, leading to increased complexity and maintenance burden.
- **Kill Switch** — An emergency feature flag that can instantly disable problematic features in production.
- **LaunchDarkly** — A popular feature flag management platform that provides SDKs, APIs, and a dashboard for controlling feature releases.
- **Long-Lived Flag** — A feature flag intended to remain in the codebase indefinitely, such as kill switches or operational toggles.
- **MAU** — Monthly Active Users, a billing metric used by feature flag providers like LaunchDarkly.
- **Multivariate Flag** — A feature flag that can have multiple values beyond simple on/off states.
- **Operational Toggle** — A long-lived feature flag used for operational control, such as rate limiting or maintenance modes.
- **Percentage Rollout** — A feature flag configuration that enables features for a specific percentage of users.
- **Progressive Rollout** — Gradually increasing the percentage of users who receive a new feature.
- **Release Toggle** — A temporary feature flag used to control the release of new features, typically removed after successful deployment.
- **Stale Flag** — A feature flag that is no longer serving its intended purpose, often at 100% rollout or 0% for extended periods.
- **Targeting Rules** — Conditions that determine which users or segments receive specific feature flag variations.
- **Technical Debt** — The implied cost of additional rework caused by choosing an easy solution now instead of a better approach.
- **Toggle Point** — The specific location in code where a feature flag decision is made.
- **Trunk-Based Development** — A development practice where all developers work on a single branch, using feature flags to control feature visibility.

---

## About FlagShark

FlagShark was built by developers who experienced feature flag debt firsthand. After spending weeks cleaning up hundreds of stale feature flags at a previous company, the team realized this was a problem every engineering team faces — but nobody had built a real solution for it.

### The Problem We're Solving

Feature flag debt is a hidden cost that compounds over time:
- 73% of flags never get removed
- $125k+ annual cost of flag debt per team
- 2.5 hours average time to clean one flag manually

Existing solutions fall short. Flag providers profit from more flags, not fewer. Manual cleanup takes too long and gets deprioritized. AI-based tools guess instead of knowing.

### Our Approach: Precision Over Convenience

1. **AST-Based Detection** — Tree-sitter parsing understands code structure, not just patterns. 100% accurate detection across 13 languages.
2. **Deterministic Results** — No AI hallucinations or probabilistic guesses. The same input always produces the same output.
3. **GitHub Native** — Works with your existing workflow. PRs you can review, CI that runs your tests, and merges when you're ready.

### What We Believe

- **Clean Code Matters** — Technical debt slows teams down. Every stale flag adds complexity.
- **Automation > Manual Toil** — Developers should spend time building features, not hunting for dead code.
- **Security First** — Minimal permissions, no source code storage, isolated processing.
- **Developer Experience** — Seamless GitHub integration, no new tools to learn, no context switching.

---

## Tools

- **ROI Calculator** (https://flagshark.com/tools/roi-calculator) — Calculate your team's savings from automated flag cleanup based on team size, flag count, and developer hourly rate.
- **Technical Debt Calculator** (https://flagshark.com/tools/technical-debt-calculator) — Estimate your feature flag technical debt and its impact on your codebase.

---

## Contact

- Website: https://flagshark.com
- Contact: https://flagshark.com/contact
- Security: joe@flagshark.com
- Enterprise Sales: joe@flagshark.com
- Twitter: https://twitter.com/flagshark
- GitHub: https://github.com/FlagShark