# Triclops

**A local-AI operator for three wireless security chips, running on a Raspberry Pi.**

Triclops turns a Raspberry Pi into a single brain that drives a **Flipper Zero**, an **AWOK "Biscuit" (ESP32-C5)**, and an **ESP32 Marauder** — over Bluetooth and USB — from plain English. A small local language model translates your orders into exact device commands; every capability of all three chips is exposed as a typed, schema-validated tool, callable from a chat dashboard or any **MCP** client. Transmit/attack commands are gated behind an explicit human confirm.

Everything runs **on-device and offline**. No cloud.

> ⚠️ **Authorized use only.** Triclops orchestrates wireless-security hardware (Wi-Fi/BLE scanning, and transmit features like deauth, beacon spam and captive portals). Use it **only** on networks and devices you own or are explicitly authorized to test, in an isolated lab. You are responsible for complying with all applicable laws. See [Responsible use](#responsible-use).

---

## What it does

- **Talk to it.** "Scan wifi on the marauder", "screenshot the flipper", "what's the biscuit's battery" → the local model maps each to one exact command.
- **238 granular tools**, auto-generated from each device's own source of truth — not hand-written.
- **Three transports, one interface:** Flipper RPC (BLE), Biscuit GATT (BLE), Marauder CLI (USB).
- **MCP server** — expose all 238 tools to Claude or any Model Context Protocol client over HTTP.
- **Live dashboard** — three link-status cards, a chat box, a per-command feed, screen mirror.
- **Safety by construction** — 57 transmit/attack/destructive tools are danger-gated; the AI can *propose* them but never *fires* them without a human confirm.

```
          ┌─ Browser / phone (your Wi-Fi) ─────────────┐
          │  Dashboard: 3 link cards · chat · feed      │
          └──────────────┬──────────────────────────────┘
                         │                 ┌─ any MCP client (Claude, …) ─┐
                         │                 └──────────────┬───────────────┘
   ┌─────────────────────┴────────── Raspberry Pi ────────┴────────────────┐
   │  Dashboard (FastAPI)          MCP server (streamable-HTTP, :8008/mcp)  │
   │          └───────────┬───────────────────┘                            │
   │                 dispatch.py  (executor, danger-gate, arg validation)   │
   │                      │                                                 │
   │                 registry.py  →  tools.json  (238 typed tool specs)     │
   │                      │                                                 │
   │     ┌────────────────┼─────────────────┐                              │
   │  Flipper           Biscuit           Marauder                          │
   │  (BLE RPC)        (BLE GATT)        (USB CLI)                          │
   │     │  local model: Ollama + Qwen2.5-3B (schema-locked)                │
   └──────────────────────────────────────────────────────────────────────┘
```

## The three chips

| Chip | Link | Protocol | Tools | Source of truth |
|------|------|----------|------:|-----------------|
| **Flipper Zero** (Momentum fw) | Bluetooth LE + USB | Protobuf RPC + text CLI | 72 | compiled from [Momentum's protobuf](https://github.com/Next-Flip/flipperzero-protobuf) + the device's USB `help` |
| **AWOK Biscuit** (ESP32-C5) | Bluetooth LE | `CMD:` text over GATT | 105 | the wiki + the firmware binary's command table |
| **ESP32 Marauder** | USB serial | text CLI | 61 | the device's own live `help` |

**238 tools total · 57 danger-gated.**

| Chip | Breakdown |
|------|-----------|
| Flipper | storage 13 · cli 29 · system 10 · app 9 · gui 6 · desktop 4 · property 1 |
| Marauder | recon 54 · attack 6 · raw 1 |
| Biscuit | recon 38 · control 36 · attack 15 · portal 10 · info 6 |

## How the tool catalog is built (the interesting part)

Triclops never hand-maintains a command list. `registry.py` **generates** `tools.json` from each device's authoritative definition:

- **Flipper** — walks the Protobuf `Main` request messages; every RPC becomes a tool with typed params (enums, nested objects, byte fields) straight from the field descriptors. Plus the USB text CLI (`subghz`, `nfc`, `ir`, `rfid`, `gpio`, …).
- **Marauder** — parses the device's own `help` output; multi-variant commands collapse into flag enums.
- **Biscuit** — the documented `CMD:` protocol, extended with the command table recovered from the firmware binary.

Each tool spec carries: typed params + `required`, a `returns` type (`text`/`json`/`table`/`image`/`stream`), `streaming` + its paired `stop_tool`, `transport`, and a `danger` flag. One registry feeds the model, the dashboard, and the MCP server.

## Hardware

- Raspberry Pi 5 (8 GB recommended; CPU-only inference)
- Flipper Zero (tested on Momentum firmware)
- AWOK Dual C5 "Biscuit" + ESP32 Marauder (e.g. the Dual C5 Touch)
- Bluetooth (built into the Pi) and a USB port for the Marauder

## Setup

```bash
git clone https://github.com/morepriyam/triclops.git
cd triclops
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# compile the Flipper protobufs (needs git + grpcio-tools)
./scripts/build_proto.sh

# configure your hardware
cp config.example.yaml config.yaml
# edit config.yaml: set flipper_addr, biscuit_addr, marauder_port

# local model
curl -fsSL https://ollama.com/install.sh | sh    # or user-space tarball
ollama pull qwen2.5:3b
```

Find your BLE MACs with a scan (`bluetoothctl scan le`) and your Marauder port with `ls /dev/serial/by-id/`.

## Run

```bash
./scripts/run.sh
```

- **Dashboard:** `http://<pi-ip>:8080`
- **MCP endpoint:** `http://<pi-ip>:8008/mcp` (streamable-HTTP)

Add the MCP server to a client, e.g. Claude Code:

```bash
claude mcp add --transport http triclops http://<pi-ip>:8008/mcp
```

Danger-gated tools require `confirm: true` in the call arguments; the model/dashboard surfaces a confirm step.

## Project layout

```
triclops/
├── triclops/
│   ├── config.py        # all tunables (devices, paths, model, ports)
│   ├── devicehub.py     # device layer: Flipper (BLE RPC), Biscuit (BLE), Marauder (serial)
│   ├── registry.py      # generates tools.json from each device's definitions
│   ├── dispatch.py      # executor: validates, danger-gates, runs each tool
│   ├── mcp_server.py    # MCP server (streamable-HTTP) exposing all tools
│   └── server.py        # dashboard backend (FastAPI + WebSocket + local model)
├── web/index.html       # dashboard UI
├── scripts/             # build_proto.sh, run.sh
├── tools.json           # the generated 238-tool catalog
└── config.example.yaml
```

## Responsible use

Triclops is for **security research and education on hardware and networks you own or are authorized to test.** The transmit features it can surface (Wi-Fi deauthentication, beacon/BLE spam, captive portals, RF replay on the Flipper) can disrupt networks and are regulated or illegal to use against third parties in most jurisdictions.

- Run it in an **isolated lab** against **your own** access points and devices.
- The AI never auto-fires a transmit/attack command — a human must confirm each one. Keep it that way.
- Don't point it at networks, people, or devices you don't control. You are solely responsible for how you use it.

The underlying tools are all independently public: the [Flipper Zero](https://flipperzero.one/), [ESP32 Marauder](https://github.com/justcallmekoko/ESP32Marauder), and the AWOK/Biscuit ecosystem. Triclops is an orchestration layer, not a new attack capability.

## Credits

- [Flipper Zero](https://flipperzero.one/) & [Momentum Firmware](https://github.com/Next-Flip/Momentum-Firmware)
- [ESP32 Marauder](https://github.com/justcallmekoko/ESP32Marauder) by justcallmekoko
- Biscuit firmware & [wiki](https://codehedge.github.io/Biscuit-Wiki/) by CodeHedge / AWOK Dynamics
- [Ollama](https://ollama.com/) · [Qwen2.5](https://github.com/QwenLM/Qwen2.5) · [MCP](https://modelcontextprotocol.io/)

## License

MIT — see [LICENSE](LICENSE).