
In-app debug overlay capturing network traffic, creating request mocks, toggling feature flags and device info. Masks sensitive fields by default and pairs securely with desktop for inspection.
🇧🇷 Português · 🇺🇸 English
Bugsy é uma biblioteca Kotlin Multiplatform (Android + iOS) que funciona como um "Flipper/Chucker" de bolso embutido no próprio app: um overlay de debug que captura requests de rede, permite criar mocks para simular respostas (sucesso, erro, lentidão) sem depender do backend, mostra feature flags, informações de device, e permite revelar/mascarar dados sensíveis, com uma política de segurança "quando em dúvida, mascara" para nunca vazar segredos (tokens, senhas, CPF) por acidente.
| Android | iOS |
|---|---|
Publicado no Maven Central sob o group io.github.gabriela-miranda-leite.
3 artefatos consumidos separadamente por build type:
dependencies {
// Overlay completo (traz :core transitivamente) só em debug.
debugImplementation("io.github.gabriela-miranda-leite:bugsy-ui:0.1.0-alpha")
// Mesma API pública, zero instrumentação, em release.
releaseImplementation("io.github.gabriela-miranda-leite:bugsy-noop:0.1.0-alpha")
}Bugsy também roda em apps Swift puro (sem KMP), via Bugsy.xcframework:
# Debug: Bugsy completo
./gradlew :ui:linkDebugFrameworkIosSimulatorArm64 :ui:iosSimulatorArm64AggregateResources
# Release: artefato no-op (mesma API, sem instrumentação)
./gradlew :bugsy-noop:linkReleaseFrameworkIosSimulatorArm64A tarefa de recursos (...AggregateResources) gera as strings e fontes do overlay e só existe no
alvo Debug — sem ela o app pode usar recursos desatualizados e crashar ao abrir o overlay. Para
rodar em device físico, troque iosSimulatorArm64 por iosArm64.
// AppDelegate.application(_:didFinishLaunchingWithOptions:)
Bugsy.shared.initialize(
config: BugsyConfig(
trigger: .shake,
shakeThresholdG: BugsyConfig.companion.DEFAULT_SHAKE_THRESHOLD_G,
flagsProvider: { [] },
allowRevealingSecrets: true // false esconde o botão "Copiar com valores reais"
)
)
// ...depois de criar a window:
BugsyIosOverlayKt.startBugsyIosOverlay()Para o app reagir na hora quando uma flag mudar (no overlay ou no Bugsy Desktop), observe a notificação
BugsyIosOverlayKt.BUGSY_FLAGS_DID_CHANGE_NOTIFICATION e leia a flag de novo com
Bugsy.shared.flagManager.value(key:); o userInfo traz a key. Ela começa com startBugsyIosOverlay().
Bugsy.initialize precisa rodar antes de qualquer URLSession ser criada (ele registra o
NSURLProtocol do Bugsy). Em release, linke o framework de :bugsy-noop, não o de :ui — ele
não contém o interceptor. Veja sample-ios/README.md para o passo a
passo completo, incluindo a cópia dos recursos do overlay no Xcode.
Bugsy é uma lib nativa (Kotlin/Swift) e não tem binding JS hoje — não dá para import direto
num app React Native. Para usar em RN seria necessário escrever um módulo nativo (Turbo
Module/Native Module) encapsulando as chamadas Bugsy.* do lado Android e iOS. Esse wrapper
ainda não existe; é trabalho futuro.
Mesma situação do React Native: não há plugin Flutter hoje. Para integrar seria necessário um Platform Channel (ou Federated Plugin) chamando o Bugsy nativo em cada plataforma. Esse plugin ainda não existe; é trabalho futuro.
// Application.onCreate()
Bugsy.initialize(
trigger = Trigger.Shake,
flagsProvider = { listOf(DebugFlag("darkModeEnabled", "Dark mode", false)) },
)
// Client OkHttp (Android)
OkHttpClient.Builder()
.addBugsyInterceptor()
.build()No iOS, chame startBugsyIosOverlay() uma vez no startup do app para observar Bugsy.isVisible.
Na aba "Mocks" do overlay dá para criar regras que interceptam requests por método e padrão de URL (regex) e respondem com um status, headers e body customizados, sem precisar subir ou alterar o backend. Cada regra pode ter um delay simulado, ser desativada temporariamente ou configurada para disparar só uma vez ("one shot"). É possível criar uma regra já preenchida a partir de um request real capturado ("Create mock from this response"), e exportar/importar o conjunto de regras como um arquivo JSON para compartilhar entre devices ou com o time.
| Android | iOS |
|---|---|
Cliente desktop (macOS, Windows, Linux) que pareia com o celular por Wi-Fi para ver requests,
mocks, flags e informações de device numa tela maior. Baixe o instalador do seu sistema na
página de Releases e veja o
passo a passo completo de instalação e pareamento em
bugsy-desktop/README.md
(English version).
settings.gradle.kts
├─ :core (KMP lib — captura, redação, lógica)
├─ :ui (KMP lib — overlay Compose Multiplatform, depende de :core)
├─ :bugsy-noop (KMP lib — mesma API pública de core+ui, zero instrumentação)
├─ :bugsy-desktop (app desktop Compose — ver bugsy-desktop/README.md)
└─ :sample-android (app Android de demonstração, não publicado)
core — captura de requests (interceptor OkHttp no Android, NSURLProtocol no iOS),
redação de headers e mascaramento de campos sensíveis do body, feature flags e os triggers
(shake, botão flutuante, notificação) que abrem o overlay.ui — overlay Compose Multiplatform: lista de requests, detalhe de request/response,
mock rules (criação, edição, import/export em JSON), flags e device info.bugsy-noop — artefato para builds de release: mesma API pública de core+ui, sem
nenhuma instrumentação.Headers (authorization, cookie, x-api-key, ...) e campos de body (password, cpf,
token, secret, ...) sensíveis são mascarados por padrão antes de qualquer dado chegar à UI ou
ao cURL exportado. Dados reais só ficam disponíveis em memória, nunca em log, e só se
explicitamente revelados na tela de settings do overlay.
Em release, bugsy-noop substitui ui/core por um artefato sem nenhum comportamento — o
gate real, porém, é que o interceptor/NSURLProtocol só é ativado se o host for debuggable,
mesmo quando o artefato completo está no classpath.
O mascaramento de body (BodyFieldMasker) tem defesa em profundidade:
SIGSEGV (não dá pra capturar), então medir a profundidade com um loop antes de
parsear recursivamente é a única saída segura.UNMASKABLE_PLACEHOLDER é o último recurso.MutableStateFlow com update {} troca o conjunto de campos sensíveis de
forma atômica, enquanto interceptors de rede leem em outras threads.O CurlGenerator tem testes de injeção shell com um parser POSIX escrito no próprio teste,
cobrindo URL com aspas simples, header com '; rm -rf ~; echo ', body com $(whoami) e método
com ; rm -rf ~ — provando que nenhum dado de tráfego não confiável injeta comando no terminal
de quem exporta o cURL.
A conexão entre o celular (Android e iOS) e o Bugsy Desktop usa TLS com o certificado fixado, e o
pareamento cifra o token. Nos pareamentos por código e por lista, você confere um código de 4
dígitos nas duas telas. O que é e o que não é protegido está em
docs/seguranca-do-pareamento-desktop.md
(English version).
Este projeto foi desenvolvido com apoio de IA (Claude Code),
com revisão humana de cada PR. O fluxo de desenvolvimento, validação local e release está
documentado em docs/fluxo-de-desenvolvimento.md
(English version).
🇧🇷 Português · 🇺🇸 English
Bugsy é uma biblioteca Kotlin Multiplatform (Android + iOS) que funciona como um "Flipper/Chucker" de bolso embutido no próprio app: um overlay de debug que captura requests de rede, permite criar mocks para simular respostas (sucesso, erro, lentidão) sem depender do backend, mostra feature flags, informações de device, e permite revelar/mascarar dados sensíveis, com uma política de segurança "quando em dúvida, mascara" para nunca vazar segredos (tokens, senhas, CPF) por acidente.
| Android | iOS |
|---|---|
Publicado no Maven Central sob o group io.github.gabriela-miranda-leite.
3 artefatos consumidos separadamente por build type:
dependencies {
// Overlay completo (traz :core transitivamente) só em debug.
debugImplementation("io.github.gabriela-miranda-leite:bugsy-ui:0.1.0-alpha")
// Mesma API pública, zero instrumentação, em release.
releaseImplementation("io.github.gabriela-miranda-leite:bugsy-noop:0.1.0-alpha")
}Bugsy também roda em apps Swift puro (sem KMP), via Bugsy.xcframework:
# Debug: Bugsy completo
./gradlew :ui:linkDebugFrameworkIosSimulatorArm64 :ui:iosSimulatorArm64AggregateResources
# Release: artefato no-op (mesma API, sem instrumentação)
./gradlew :bugsy-noop:linkReleaseFrameworkIosSimulatorArm64A tarefa de recursos (...AggregateResources) gera as strings e fontes do overlay e só existe no
alvo Debug — sem ela o app pode usar recursos desatualizados e crashar ao abrir o overlay. Para
rodar em device físico, troque iosSimulatorArm64 por iosArm64.
// AppDelegate.application(_:didFinishLaunchingWithOptions:)
Bugsy.shared.initialize(
config: BugsyConfig(
trigger: .shake,
shakeThresholdG: BugsyConfig.companion.DEFAULT_SHAKE_THRESHOLD_G,
flagsProvider: { [] },
allowRevealingSecrets: true // false esconde o botão "Copiar com valores reais"
)
)
// ...depois de criar a window:
BugsyIosOverlayKt.startBugsyIosOverlay()Para o app reagir na hora quando uma flag mudar (no overlay ou no Bugsy Desktop), observe a notificação
BugsyIosOverlayKt.BUGSY_FLAGS_DID_CHANGE_NOTIFICATION e leia a flag de novo com
Bugsy.shared.flagManager.value(key:); o userInfo traz a key. Ela começa com startBugsyIosOverlay().
Bugsy.initialize precisa rodar antes de qualquer URLSession ser criada (ele registra o
NSURLProtocol do Bugsy). Em release, linke o framework de :bugsy-noop, não o de :ui — ele
não contém o interceptor. Veja sample-ios/README.md para o passo a
passo completo, incluindo a cópia dos recursos do overlay no Xcode.
Bugsy é uma lib nativa (Kotlin/Swift) e não tem binding JS hoje — não dá para import direto
num app React Native. Para usar em RN seria necessário escrever um módulo nativo (Turbo
Module/Native Module) encapsulando as chamadas Bugsy.* do lado Android e iOS. Esse wrapper
ainda não existe; é trabalho futuro.
Mesma situação do React Native: não há plugin Flutter hoje. Para integrar seria necessário um Platform Channel (ou Federated Plugin) chamando o Bugsy nativo em cada plataforma. Esse plugin ainda não existe; é trabalho futuro.
// Application.onCreate()
Bugsy.initialize(
trigger = Trigger.Shake,
flagsProvider = { listOf(DebugFlag("darkModeEnabled", "Dark mode", false)) },
)
// Client OkHttp (Android)
OkHttpClient.Builder()
.addBugsyInterceptor()
.build()No iOS, chame startBugsyIosOverlay() uma vez no startup do app para observar Bugsy.isVisible.
Na aba "Mocks" do overlay dá para criar regras que interceptam requests por método e padrão de URL (regex) e respondem com um status, headers e body customizados, sem precisar subir ou alterar o backend. Cada regra pode ter um delay simulado, ser desativada temporariamente ou configurada para disparar só uma vez ("one shot"). É possível criar uma regra já preenchida a partir de um request real capturado ("Create mock from this response"), e exportar/importar o conjunto de regras como um arquivo JSON para compartilhar entre devices ou com o time.
| Android | iOS |
|---|---|
Cliente desktop (macOS, Windows, Linux) que pareia com o celular por Wi-Fi para ver requests,
mocks, flags e informações de device numa tela maior. Baixe o instalador do seu sistema na
página de Releases e veja o
passo a passo completo de instalação e pareamento em
bugsy-desktop/README.md
(English version).
settings.gradle.kts
├─ :core (KMP lib — captura, redação, lógica)
├─ :ui (KMP lib — overlay Compose Multiplatform, depende de :core)
├─ :bugsy-noop (KMP lib — mesma API pública de core+ui, zero instrumentação)
├─ :bugsy-desktop (app desktop Compose — ver bugsy-desktop/README.md)
└─ :sample-android (app Android de demonstração, não publicado)
core — captura de requests (interceptor OkHttp no Android, NSURLProtocol no iOS),
redação de headers e mascaramento de campos sensíveis do body, feature flags e os triggers
(shake, botão flutuante, notificação) que abrem o overlay.ui — overlay Compose Multiplatform: lista de requests, detalhe de request/response,
mock rules (criação, edição, import/export em JSON), flags e device info.bugsy-noop — artefato para builds de release: mesma API pública de core+ui, sem
nenhuma instrumentação.Headers (authorization, cookie, x-api-key, ...) e campos de body (password, cpf,
token, secret, ...) sensíveis são mascarados por padrão antes de qualquer dado chegar à UI ou
ao cURL exportado. Dados reais só ficam disponíveis em memória, nunca em log, e só se
explicitamente revelados na tela de settings do overlay.
Em release, bugsy-noop substitui ui/core por um artefato sem nenhum comportamento — o
gate real, porém, é que o interceptor/NSURLProtocol só é ativado se o host for debuggable,
mesmo quando o artefato completo está no classpath.
O mascaramento de body (BodyFieldMasker) tem defesa em profundidade:
SIGSEGV (não dá pra capturar), então medir a profundidade com um loop antes de
parsear recursivamente é a única saída segura.UNMASKABLE_PLACEHOLDER é o último recurso.MutableStateFlow com update {} troca o conjunto de campos sensíveis de
forma atômica, enquanto interceptors de rede leem em outras threads.O CurlGenerator tem testes de injeção shell com um parser POSIX escrito no próprio teste,
cobrindo URL com aspas simples, header com '; rm -rf ~; echo ', body com $(whoami) e método
com ; rm -rf ~ — provando que nenhum dado de tráfego não confiável injeta comando no terminal
de quem exporta o cURL.
A conexão entre o celular (Android e iOS) e o Bugsy Desktop usa TLS com o certificado fixado, e o
pareamento cifra o token. Nos pareamentos por código e por lista, você confere um código de 4
dígitos nas duas telas. O que é e o que não é protegido está em
docs/seguranca-do-pareamento-desktop.md
(English version).
Este projeto foi desenvolvido com apoio de IA (Claude Code),
com revisão humana de cada PR. O fluxo de desenvolvimento, validação local e release está
documentado em docs/fluxo-de-desenvolvimento.md
(English version).