xunholy/promptzero

English 简体中文 日本語 Deutsch Français Español Português

Talk to your Flipper Zero like a person — it builds the payload, deploys it, and runs it

A natural-language operator for the Flipper Zero and ESP32 Marauder.
Sub-GHz, NFC, RFID, IR, BadUSB and WiFi — driven by Claude, gated by a risk engine.

Quick start  What it does  Modes  Safety  Docs

[!CAUTION] Authorised use only. PromptZero generates and runs RF, NFC, RFID, and HID payloads — illegal outside contexts you own or have written authorisation to test. Read SECURITY.md for the safety model and threat boundary. The project is under active development; APIs and tools change between minor versions.

Built end-to-end with Claude. Review generated payloads before deployment.

Describe what you want in a sentence. PromptZero talks to your Flipper Zero (and an optional ESP32 Marauder WiFi devboard) over USB serial or BLE, generates the payload, deploys it to the SD card, and runs it — every risky action passing a consent gate and landing in an audit log on the way.

promptzero> make me a Starbucks WiFi captive portal
  Generated and deployed evil_portal to /ext/apps_data/evil_portal/index.html
  Evil portal started on Marauder devboard

promptzero> scan for nearby WiFi networks and deauth the strongest one
  Found 12 access points. Strongest: "NETGEAR-5G" (-31 dBm, channel 6)
  Selected AP 0. Deauth attack running...

promptzero> create a BadUSB payload that opens a reverse shell on Windows
  Generated and deployed badusb to /ext/badusb/generated_payload.txt
  Ready to execute - plug into target and run

promptzero> identify this device: /tmp/remote.jpg
  That's a Samsung BN59 series TV remote using the Samsung32 IR protocol.
  I can generate a complete remote file. Want me to create it?

Quick start

Prerequisites — a Flipper Zero on modded firmware (Momentum / Unleashed / RogueMaster), an Anthropic API key, and a USB cable.

# 1. Install (Linux/macOS, amd64/arm64) — pinned to release artifacts (immutable per tag)
curl -fsSL https://github.com/xunholy/promptzero/releases/latest/download/install.sh | sh

# 2. Configure
export ANTHROPIC_API_KEY="sk-ant-..."

# 3. Run
promptzero

promptzero> what's connected?
  Flipper Zero — firmware 0.99.1, hardware v7.4
  Battery 84 % | SD card 4.1 GB free / 7.4 GB total

That's the whole onboarding. From here, type natural-language instructions or /help to see slash commands.

[!TIP] Defensive posture (one-flag safety rail): add --read-only to refuse any tool that writes, transmits, or executes. Pure reads / scans / queries still dispatch; anything risk-Medium or above is refused at the boundary.

promptzero --read-only          # blue-team / forensics / training

Other paths: Windows users grab the .zip from the releases page. WSL2 needs USB passthrough — see Transports → WSL2. For wireless BLE, config files, personas, environment variables, and self-upgrade: Configuration reference.

What it does

PromptZero controls everything through natural language — one agent, a live tool registry that grows release-over-release, and a risk gate in front of anything that touches the world.

Subsystem	Capabilities
Flipper Zero	Sub-GHz TX/RX, IR TX/RX, NFC detect/emulate, RFID read/write/emulate, iButton, GPIO, BadUSB, storage, app launcher
ESP32 Marauder	WiFi scan, deauth, beacon spam, probe flood, PMKID capture, evil portal, BLE spam, BT scanning, skimmer detection, wardriving, MAC spoofing
AI generation	Evil portal HTML, BadUSB DuckyScript, Sub-GHz .sub, IR .ir, NFC .nfc from natural language — plus parametric builders for typed parameters
Intelligence	Image analysis via Claude vision (file path → device ID + attack vector), SD card discovery
Audit	SQLite audit log with MITRE ATT&CK technique tags, session export, statistics

Run promptzero and type /tools for the live registry.

Under the hood — the agent layer

PromptZero's agent ships prompt caching, cost-tier model routing (recon on Haiku, exploit on Opus), prompt-injection quarantine, reflexion-on-error with structured ToolError, a <device-state> oracle injected each turn, and OpenTelemetry GenAI spans. The LLM is a component, not a library: model and provider swaps are first-class, and no prompt is load-bearing. See docs/ for architecture details.

Modes

CLI — promptzero

The default. An interactive REPL.

promptzero> scan the SD card and show me what signals I have saved
promptzero> transmit the garage door signal
promptzero> read the NFC tag on my desk

Slash commands (run /help for the full list with descriptions):

• Conversation — /help, /reset, /quit
• Session — /sessions, /save <name>, /resume <id>, /forget <id>
• Info — /status, /tools [query|page <n>], /history [N], /audit {stats|find|tail|top|session|query|export}, /stats [section], /cost, /budget [set <USD>|off], /debug
• Operator — /persona [name], /mode [name], /watch [pause|resume], /webhooks [test <name>], /validate <path>, /attack {set|clear} <techniques>, /campaign {validate|run} <file>, /rewind [snapshot], /report [session] [json] [save], /rules [list|pause|resume|test]
• Device — /reconnect

Keystrokes during a turn:

• Ctrl+C — cancel the current turn entirely.
• Ctrl+G — abort the current streaming tool (e.g. subghz_receive, wifi_scan_ap) but let the agent continue with the partial result.
• Ctrl+R — reverse-incremental history search.
• Ctrl+L — clear screen.

Web UI — promptzero --web

A dark-themed browser interface at http://localhost:8080: the chat surface, a live Flipper viewport, a file browser, the audit log, a report builder, and — when a Marauder is connected — a TFT display panel.

[!IMPORTANT] Auth. Set web.token in your config or PROMPTZERO_WEB_TOKEN in env. The browser picks up #token=… from the URL fragment on first load and caches it in sessionStorage. Empty token + non-loopback bind → the server prints a red warning. PromptZero speaks plain HTTP — terminate TLS at a reverse proxy (Caddy / Traefik / nginx) or a Tailscale / Cloudflare tunnel.

Host it with Docker. Multi-arch images (distroless, signed, with SBOM + provenance) are published to ghcr.io/xunholy/promptzero on every release — see docs/deploy/docker.md.

Health probes. GET /healthz (liveness, 200 ok) and GET /readyz (readiness, JSON subsystem snapshot) are unauthenticated for headless / systemd / k8s deployment; device connectivity is reported but does not gate readiness (a Flipper/Marauder may attach after startup).

Voice — promptzero --voice

Push-to-talk in CLI mode. Press Enter with no text to record (requires sox); audio is transcribed via OpenAI Whisper, then processed as a normal command.

Ubuntu/Debian:  apt install sox
macOS (brew):   brew install sox
Arch:           pacman -S sox

MCP — promptzero --mcp

Runs as a Model Context Protocol server over stdio. Add to Claude Desktop / Claude Code:

{
  "mcpServers": {
    "promptzero": {
      "command": "/path/to/promptzero",
      "args": ["--mcp"]
    }
  }
}

[!IMPORTANT] MCP risk gate. Risk-High and Risk-Critical tools are refused by default — set PROMPTZERO_MCP_ALLOW_HIGH=1 and / or PROMPTZERO_MCP_ALLOW_CRITICAL=1 to allow them. All MCP calls (allowed or denied) are recorded in the audit log. See Safety model below.

Safety model

PromptZero is dual-use offensive tooling. The safety story is the project's social licence to exist — every spec carries a risk tier, and the tier decides what dispatches freely and what has to be confirmed.

 scans, reads and queries — dispatched freely.
 data writes and signal emulation.
 active RF transmit, tag writes and script execution — operator confirmation required.
 brute-force and destructive attacks — operator confirmation required.

• Consent gate. High and Critical tools require operator confirmation. The CLI shows a boxed preview (frequency / modulation / hex) with a 2-second delay; positive consent (y, all, confirm) is rejected before the delay opens. Negative decisions (n, r for revise, Esc) bypass the delay.
• MCP refuses by default. No MCP client can run High+ tools without explicit env-var opt-in (see above).
• Audit-log fail-closed. If no audit log is initialised, the agent refuses High+ actions rather than running them silently.
• Prompt-injection quarantine. Tool outputs (scanned SSIDs, captured packets, image content, SD filenames) are wrapped before being fed back into the model so they can't override the system prompt.
• No auto-deploy of generated payloads. BadUSB scripts deploy without execution by default.

Read SECURITY.md for the full threat model, scope / out-of-scope, and how to report a vulnerability.

Compatibility

Firmware support

Firmware	Status
Momentum (formerly Xtreme)	Primary target
Unleashed	Supported
RogueMaster	Supported
Official (OFW) 1.x	Supported with a reduced feature set — region-locked Sub-GHz, no rolling code

[!NOTE] Official firmware locks Sub-GHz TX to region-specific ISM bands and blocks rolling-code protocols. Modded firmware unlocks the full CC1101 range (300–348 / 387–464 / 779–928 MHz) and enables TX for all 52 supported protocols.

The ESP32 Marauder devboard requires firmware v1.11.1+ over USB CDC ACM (/dev/ttyACM1 for the official Flipper WiFi devboard, baud 115200). For BLE wireless (no cable, all tools work, ~10× slower than USB) and per-platform pairing, see the Transports reference.

Documentation

• docs/ — handbook with task-oriented scenarios, prompt patterns, and reproducible transcripts.
• docs/reference/tools.md — a curated reference of the core tools' schemas, risk levels, and the prompts that fire them reliably. Run /tools (or tool_search) for the complete live registry.
• docs/reference/transports.md — serial, BLE, WSL2 setup.
• docs/reference/configuration.md — config file, env vars, personas, rules, self-upgrade.
• SECURITY.md — threat model and disclosure policy.
• examples/ — copy-paste templates: config, rules, four operator personas (red team / blue team / CTF / hardware lab).
• CHANGELOG.md — what's in each release.

Build & contribute

See CONTRIBUTING.md. Short version:

git clone https://github.com/xunholy/promptzero.git
cd promptzero
task dev:setup
task build
task test

Licence

AGPL-3.0-or-later. Hosting a modified PromptZero as a network service requires publishing source changes under the same licence.

_{The Claude usage/cost badge is an estimate aggregated from the maintainer's local Claude Code transcripts (task claude-usage); it reflects that machine's sessions only.}

_{Built with Claude by xunholy.}