Interceptly Monorepo

High-performance, client-agnostic network & realtime traffic inspector for Flutter applications. Interceptly provides real-time visualization of HTTP requests, responses, and bidirectional WebSocket frames with zero UI jank and minimal memory footprint.

---

Install with AI agent

Paste this into your coding agent (OpenCode, Claude Code, Codex, ...):

Fetch and follow instructions from https://raw.githubusercontent.com/Tuanpluss02/interceptly/main/docs/integration-guide.md

The agent will detect your HTTP clients, add the right packages, wire up the inspector, and verify it works.

---

Architecture Overview

Interceptly is organized as a modular monorepo managed with Melos. The core inspection engine and UI are completely client-agnostic, while lightweight satellite adapter packages provide seamless integration with popular networking libraries.

├── packages/
│   ├── interceptly              # Core engine, UI overlay, isolate processing & storage
│   ├── interceptly_dio          # Adapter for Dio (InterceptlyDioInterceptor)
│   ├── interceptly_http         # Adapter for package:http (InterceptlyHttpClient)
│   ├── interceptly_chopper      # Adapter for Chopper (InterceptlyChopperInterceptor)
│   ├── interceptly_web_socket   # Adapter for WebSocketChannel (InterceptlyWebSocketChannel)
│   ├── interceptly_socket_io    # Adapter for socket_io_client (InterceptlySocketIo)
│   └── interceptly_mcp          # Model Context Protocol server for AI coding assistants
└── packages/interceptly/example # Interactive Flutter showcase app

Packages

Package	Pub	Description
interceptly		Core package: Flutter UI inspector overlay, background isolate pipeline, hybrid disk/RAM storage, throttling buffer, and realtime inspection.
interceptly_dio		Dio Adapter: Non-intrusive Interceptor recording HTTP requests, responses, and errors.
interceptly_http		HTTP Adapter: Stream-teeing http.Client wrapper preserving single-subscription response streams.
interceptly_chopper		Chopper Adapter: ResponseInterceptor and RequestInterceptor capturing Chopper network traffic.
interceptly_web_socket		WebSocket Adapter: WebSocketChannel wrapper capturing bidirectional text/binary frames in real time.
interceptly_socket_io		Socket.IO Adapter: socket_io_client tracker capturing events and enabling composer emission.
interceptly_mcp		MCP Server & CLI: Model Context Protocol server connecting AI assistants (Antigravity, Cursor, Claude Code) to Flutter VM Service.

---

Quick Start

1. Install Packages

Add the core package and the adapter(s) corresponding to your network client:

flutter pub add interceptly

# Add the adapter(s) you need:
flutter pub add interceptly_dio
flutter pub add interceptly_http
flutter pub add interceptly_chopper
flutter pub add interceptly_web_socket
flutter pub add interceptly_socket_io

For local monorepo development, path dependencies can also be used:

dependencies:
  interceptly:
    path: packages/interceptly
  interceptly_dio:
    path: packages/interceptly_dio

2. Initialize Interceptly

Initialize Interceptly in your app startup:

import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:interceptly/interceptly.dart';

final navigatorKey = GlobalKey<NavigatorState>();

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(MyApp(navigatorKey: navigatorKey));

  if (kDebugMode || kProfileMode) {
    Interceptly.init(
      navigatorKey: navigatorKey,
      settings: const InterceptlySettings(
        maxEntries: 1000,
        maxFramesPerSession: 1000,
      ),
    );
  }
}

3. Attach Network Adapters

Dio

import 'package:dio/dio.dart';
import 'package:interceptly_dio/interceptly_dio.dart';

final dio = Dio()..interceptors.add(InterceptlyDioInterceptor());

HTTP (package:http)

import 'package:http/http.dart' as http;
import 'package:interceptly_http/interceptly_http.dart';

final client = InterceptlyHttpClient(http.Client());

Chopper

import 'package:chopper/chopper.dart';
import 'package:interceptly_chopper/interceptly_chopper.dart';

final chopper = ChopperClient(
  interceptors: [InterceptlyChopperInterceptor()],
);

WebSocket (package:web_socket_channel)

import 'package:interceptly_web_socket/interceptly_web_socket.dart';

final channel = InterceptlyWebSocketChannel.connect(
  Uri.parse('wss://echo.websocket.events'),
);

// Listen and send frames normally — Interceptly captures them live!
channel.stream.listen((message) => print('Received: $message'));
channel.sink.add('Hello Interceptly!');

Socket.IO (package:socket_io_client)

import 'package:interceptly_socket_io/interceptly_socket_io.dart';
import 'package:socket_io_client/socket_io_client.dart' as io;

final socket = io.io('https://chat.example.com');

// Attach inspector:
socket.attachInterceptly();

// Connect and emit events normally:
socket.connect();
socket.emit('chat_message', {'text': 'Hello Interceptly!'});

AI Agent & MCP Server (interceptly_mcp)

Connect AI coding assistants (Antigravity, Cursor, Claude Code, Windsurf) directly to your running Flutter app to inspect HTTP and WebSocket traffic, retrieve metrics summaries, and simulate network conditions via Model Context Protocol:

dart pub global activate interceptly_mcp
# Or run within the monorepo workspace:
dart run packages/interceptly_mcp/bin/interceptly_mcp.dart

See packages/interceptly_mcp/README.md for tool schema and setup guides.

---

Entry-Point Configuration & Triggers

Interceptly.init Parameters

Parameter	Type	Default	Description
navigatorKey	GlobalKey<NavigatorState>	Required	Global navigator key used to mount overlay and push inspector screen
showFloatingButton	bool	true	Whether to display the draggable floating action button overlay
fabChild	Widget?	null	Optional custom widget rendered inside the floating action button
customTrigger	Stream<void>?	null	Stream triggering inspector opening (e.g. shake detector, volume keys, gesture)
settings	InterceptlySettings?	Default settings	Storage thresholds, body caps, filtering predicates, and timeout durations

Warning

Interceptly.init has no release guard: calling it in a release build ships the inspector to users. Always wrap the call in if (kDebugMode || kProfileMode).

Overlay & Navigation Triggers

• Route Transition Observer: Set navigatorObservers: [Interceptly.navigatorObserver] on MaterialApp to ensure the floating overlay button always remains on top across route changes.
• Custom Trigger Stream: Supply customTrigger: shakeSensorStream to open the inspector on device shake or hardware buttons.
• Custom Button Icon: Pass fabChild: Icon(Icons.bug_report, color: Colors.amber) to customize button appearance.
• Programmatic Control:

  Interceptly.showInspector(context); // Open inspector view directly
  Interceptly.hideFloatingButtonForSession(); // Hide floating button for session
  Interceptly.showFloatingButtonForSession(); // Restore floating button
  final isHidden = Interceptly.isFloatingButtonHiddenForSession;
  Interceptly.detach(); // Remove overlay and cancel subscriptions

Filtering Requests with shouldCapture

You can pass a custom filter predicate to InterceptlySettings.shouldCapture:

InterceptlySettings(
  shouldCapture: (url) {
    // Return false to skip capture entirely
    return !url.contains('/health-check') && !url.contains('/analytics');
  },
)

Note

shouldCapture is executed synchronously on every outbound request before dispatch. It must be fast, non-blocking, and lightweight. Requests returning false are completely ignored and consume zero memory or disk storage.

---

Architecture: Bridge Pattern & Traffic Collectors SPI

All satellite adapters in Interceptly follow a unified Bridge & SPI pattern, delegating coordination to core collectors:

• HttpTrafficCollector & DefaultHttpTrafficCollector: Handles request lifecycle coordination, timing & duration calculation, network simulation (latency, bandwidth throttling, offline exceptions), request body/response body serialization to isolates, and headless engine persistence.
• RealtimeTrafficCollector & DefaultRealtimeTrafficCollector: Handles WebSocket/SSE connection tracking, frame type conversion (text vs. binary), payload serialization, and 60fps throttled ring buffer storage.
• Framework Adapters: Satellite adapters encapsulate framework-specific clients and interceptors, delegating lifecycle events directly to HttpTrafficCollector or RealtimeTrafficCollector.

This design decouples application networking frameworks from Interceptly's internal storage and simulation engines, making it trivial to create custom adapters for any protocol (gRPC, GraphQL, MQTT, Socket.IO) without duplicating code or leaking exceptions.

---

Monorepo Development & Contribution

This repository uses Melos to manage dependencies and multi-package scripts.

For detailed guidelines on branch naming, Conventional Commits, and CI/CD automation, see CONTRIBUTING.md.

Development Guidelines

For architecture specifications, SPI contracts, conventions, and quality rules, see AGENTS.md and the modular guides in docs/development-guide/.

Common Commands

# Bootstrap all packages and link local dependencies
melos bootstrap

# Fast pre-push check (format check, static analysis, core tests)
melos run check

# Auto-format all Dart files across the monorepo
melos run format

# Run static analysis across all packages
melos run analyze

# Run all test suites (840+ tests)
melos run test

# Check pub.dev health score (160/160 points target)
melos run pana

---

Example Application

An interactive Flutter showcase application demonstrating all adapters (Dio, HTTP, Chopper, WebSocket) is provided in packages/interceptly/example:

cd packages/interceptly/example
flutter run

---

License

This project is licensed under the MIT License - see the LICENSE file for details.