Flipper Dev Toolkit

A Claude Code plugin for Flipper Zero FAP (Flipper Application Package) development. Build, deploy, test, and live-debug FAPs over USB RPC with autonomous agent support across all major firmware variants.

Features

• Auto firmware detection — OFW, Momentum, Unleashed, RogueMaster (deploys to correct path)
• Build wrapper — ufbt/fbt with multi-channel support
• Deploy over USB — no SD card swapping; uses RPC storage
• Screen capture — PNG + ASCII for visual diffs
• Input automation — button presses, long-press, sequences
• Live log streaming — captures crash traces in real time
• Crash decoding — symbolic addresses via arm-none-eabi-addr2line (auto-detected)
• YAML test scenarios — declarative, reusable, CI-friendly
• MCP server — agents can drive the device autonomously
• Three specialized agents — live debugger, test runner, crash forensics

Installation

The plugin lives at ~/.claude/plugins/flipper-dev-toolkit/. Claude Code discovers it automatically.

One-time setup

On first use (run /connect-flipper), the plugin bootstraps a local Python venv with:

• pyserial (USB CDC serial)
• protobuf (RPC message encoding)
• PyYAML (test scenarios)
• mcp (MCP server runtime)

The Flipper protobuf bindings are generated from upstream .proto files on first run.

Manual prerequisite check

python --version   # 3.10 or newer
ufbt --version     # for /build-fap (optional)

Commands

Command	Purpose
/connect-flipper	Detect COM port, identify firmware variant, show device info
/build-fap	Build the current FAP project via ufbt (or fbt)
/deploy-fap	Upload a .fap to the device's app directory
/test-fap	Run a YAML scenario: build → deploy → launch → assert → report
/capture-screen	Capture and display the current device screen
/send-input	Send button presses (single, long, sequence)
/flipper-logs	Stream log output; capture crash traces
/flipper-files	List, upload, download, or delete files on the device

Agents

Agent	When it triggers
fap-live-debugger	"My FAP crashes when…", "I can't reproduce this bug" — reproduces and narrows down root cause autonomously
fap-test-evaluator	Runs and adapts test scenarios; classifies failures (crash vs UI vs logic)
fap-crash-forensics	Given a crash trace, decodes addresses to source lines and ranks hypotheses

Quick start

# In a FAP project directory
/connect-flipper             # discovers /dev/ttyACM0 or COMx
/build-fap                   # ufbt build, writes dist/<arch>/...fap
/deploy-fap                  # uploads to /ext/apps/Tools/ (Momentum) or /ext/apps/Misc/ (OFW)
/test-fap examples/basic-launch.yaml

Test scenario format (YAML)

name: archive-unzipper basic launch
firmware: any           # any | ofw | momentum | unleashed | roguemaster
fap: dist/debug/archive_unzipper.fap
steps:
  - launch: archive_unzipper
  - wait_ms: 500
  - capture: screens/main.png
  - assert_screen_contains: "Archive Unzipper"
  - press: ok
  - wait_ms: 200
  - assert_no_crash: true
on_failure:
  - capture: screens/failure.png
  - dump_logs: logs/last-failure.log

See examples/ for more.

File layout

flipper-dev-toolkit/
├── .claude-plugin/plugin.json
├── .mcp.json                    # MCP server registration
├── skills/                      # 9 skills (1 knowledge + 8 commands)
├── agents/                      # 3 agents (live-debugger, test-evaluator, crash-forensics)
├── scripts/                     # Python: core RPC lib, CLI tools, MCP server
├── references/                  # RPC protocol, crash signatures, firmware variants, etc.
└── examples/                    # Sample test scenarios

Compatibility

• OS: Windows (COMx), macOS/Linux (/dev/tty.usbmodem*, /dev/ttyACM*)
• Python: 3.10+
• Firmware: Official, Momentum (dev/release), Unleashed, RogueMaster
• Hardware: Flipper Zero in normal mode (DFU not supported)

Configuration

Optional settings file: .claude/flipper-dev-toolkit.local.md

# Override autodetect:
port: COM5
firmware: momentum
arm_toolchain: C:\Users\me\.ufbt\toolchain\arm-none-eabi
default_deploy_dir: /ext/apps/Tools

Troubleshooting

Issue	Fix
Port not found	Close qFlipper, Flipper Lab, or any other app that has the device open
RPC handshake failed	Power-cycle the Flipper; ensure firmware ≥ 0.71 (RPC v0.10+)
Crash decoder unavailable	Install ufbt (pip install ufbt) or set arm_toolchain in settings
MCP server didn't start	Check Python is in PATH; run python ~/.claude/plugins/flipper-dev-toolkit/scripts/flipper_mcp_server.py --selftest

License

MIT