inspector

Flutter app runtime debugging master inspector

항목	내용
Invoke	/inspector
Aliases	/debug, /inspect, /flutter:debug
Category	kobic-development
Complexity	moderate
MCP Servers	flutter-inspector, serena

/inspector — 앱 속을 들여다보는 "진단 의사"#

한마디로#

실행 중인 Flutter 앱 안에서 지금 무슨 일이 벌어지고 있는지 들여다보는 청진기입니다. 화면 전환, 로그인, 화면 데이터, 통신 같은 부분을 의사가 청진기로 몸속을 살펴보듯 실시간으로 진단합니다.

누가·언제 쓰나요#

앱이 이상하게 동작하는데 원인을 눈으로 확인하고 싶을 때 (화면이 안 넘어감, 로그인이 풀림, 데이터가 안 보임, 통신 오류 등)
개발자/AI 에이전트가 코드를 고치기 전에 실제 실행 상태를 먼저 점검할 때
단, 앱이 디버그 모드로 실행 중이어야 진단이 가능합니다 (실행 조건은 아래 상세 명세 참고).

무엇을 해주나요#

앱의 부위별로 나눠진 9개의 전문 진단기를 통해 실시간 상태를 보여줍니다.

nav — 화면 전환(현재 어느 화면인지, 이동 기록)
bloc — 화면 데이터·상태 관리 흐름
auth — 로그인/인증 상태
network — 서버와 주고받은 통신 기록과 오류
log — 앱이 남긴 기록(로그)
ui — 화면 구성(레이아웃, 화면 밖으로 삐져나온 부분 등)
config — 설정값·기능 on/off 플래그
form — 입력 폼의 값·검증 오류
image — 이미지 캐시·메모리 사용량

어떻게 쓰나요#

# 모든 영역을 한 번에 점검
/inspector --all

# 화면 전환 문제 진단
/inspector nav

# 화면 상태(BLoC)를 자세히 점검
/inspector bloc --verbose

# 통신 오류 분석
/inspector network

진단할 부위 이름(nav, bloc, auth, network, log, ui, config, form, image)을 붙여 부르면 됩니다.
--verbose는 더 자세히, --all은 모든 부위를 한꺼번에 점검합니다.

안에서 무슨 일이 벌어지나요#

대략 4단계로 진단이 진행됩니다.

연결 확인 — 앱과 정상적으로 연결됐는지, 진단 도구를 쓸 수 있는지 확인합니다.
문제 부위 찾기 — 증상에 맞는 부위로 안내합니다(화면 전환→nav, 상태 문제→bloc, 로그인 문제→auth, 통신 문제→network).
상세 분석 — 해당 부위 전문 진단기를 돌려 로그·상태를 추적하고 문제를 짚어냅니다.
해결·확인 — 코드 수정안을 제안하고, 즉시 반영(hot reload)한 뒤 다시 점검해 확인합니다.

⚙️ 상세 옵션·실행 명세 (개발자 / AI 에이전트용)

Triggers#

When app debugging is requested
When runtime state inspection is needed
When MCP toolkit-based inspection is needed

Context Trigger Pattern#

/inspector {area} [--options]

Parameters#

Parameter	Required	Description	Example
`area`	No	Inspection area	`nav`, `bloc`, `auth`, `network`, `log`, `ui`, `config`, `form`, `image`
`--verbose`	No	Verbose output
`--all`	No	Inspect all areas

Sub-Inspectors#

9 Specialized Inspectors#

Inspector	Role	Key Tools
`/inspector/nav`	GoRouter navigation	nav_get_current_route, nav_get_history
`/inspector/bloc`	BLoC state tracking	bloc_list_active, bloc_get_state
`/inspector/auth`	Authentication status	auth_get_status, auth_get_user
`/inspector/network`	HTTP request logging	network_get_logs, network_get_errors
`/inspector/log`	App log management	log_get_recent, log_get_errors
`/inspector/ui`	Widget tree inspection	ui_get_widget_tree, ui_find_overflow
`/inspector/config`	Settings/feature flags	config_get_all, config_get_feature_flags
`/inspector/form`	Form validation debugging	form_get_state, form_get_errors
`/inspector/image`	Image cache/memory	img_get_cache_stats, img_analyze_warnings

Prerequisites#

Flutter App Run Conditions#

# Run in debug mode (VM Service enabled)
flutter run --debug \
  --enable-vm-service \
  --host-vmservice-port=8182 \
  --dds-port=8181 \
  --disable-service-auth-codes

MCP Toolkit Integration#

// main.dart
import 'package:mcp_toolkit/mcp_toolkit.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  MCPToolkitBinding.instance
    ..initialize()
    ..initializeFlutterToolkit();

  if (kDebugMode) {
    // Register custom tools
    registerDebugTools();
  }

  runApp(const MyApp());
}

Diagnostic Workflow#

+---------------------------------------------+
|  1. Verify App Connection                     |
+---------------------------------------------+
|  - Test hot_reload_flutter                    |
|  - Check listClientToolsAndResources          |
+---------------------------------------------+
                    |
                    v
+---------------------------------------------+
|  2. Identify Problem Area                     |
+---------------------------------------------+
|  - Screen transition - >   @flutter-inspector-nav|
|  - State issue - >   @flutter-inspector-bloc     |
|  - Login issue - >   @flutter-inspector-auth     |
|  - API issue - >   @flutter-inspector-network    |
+---------------------------------------------+
                    |
                    v
+---------------------------------------------+
|  3. Detailed Analysis                         |
+---------------------------------------------+
|  - Run specialized inspector tools            |
|  - Track logs and state                       |
|  - Identify issues                            |
+---------------------------------------------+
                    |
                    v
+---------------------------------------------+
|  4. Resolution and Verification               |
+---------------------------------------------+
|  - Suggest code fixes                         |
|  - Apply with hot_reload_flutter              |
|  - Confirm with re-inspection                 |
+---------------------------------------------+

Quick Diagnostics#

Screen Transition Issues#

1. /inspector/nav - >   Check current route
2. nav_get_history - >   Track transition history
3. nav_get_params - >   Verify passed parameters

State Management Issues#

1. /inspector/bloc - >   Active BLoC list
2. bloc_get_state - >   Check current state
3. bloc_get_events - >   Event history

API Errors#

1. /inspector/network - >   Request/response logs
2. network_get_errors - >   Check failed requests
3. /inspector/auth - >   Check token status

UI Layout Issues#

1. /inspector/ui - >   Check widget tree
2. ui_find_overflow - >   Search for overflow
3. ui_get_screen_info - >   Screen info

Performance Issues#

1. /inspector/image - >   Image cache analysis
2. img_analyze_warnings - >   Memory warnings
3. /inspector/log - >   Performance related logs

MCP Integration#

Step	MCP Server	Purpose
App connection	flutter-inspector	VM Service connection
Tool query	flutter-inspector	listClientToolsAndResources
Tool execution	flutter-inspector	runClientTool
Code analysis	serena	Related code search

Examples#

Full state check#

/inspector --all

/inspector nav

BLoC state check#

/inspector bloc --verbose

Network error analysis#

/inspector network

References#

Detailed implementation: .claude/agents/flutter-inspector.md
Sub-inspectors: .claude/commands/inspector/
MCP toolkit: package/mcp_toolkit/