Puffco Peak Pro controls for the Omarchy bar: chamber temperature and battery at a glance, heat and profile controls, LED colors, and usage stats read straight from the device.
QuickPuff is unofficial and not affiliated with Puffco. It speaks the reverse-engineered Lorax Bluetooth protocol, so a Puffco firmware update can break it. It works with the Peak Pro only; Proxy and Pivot are rejected.
Watch the full 3-minute demo (MP4, 5 MB)
 Control |
 Lights |
 Care |
 Usage · Stats |
 Usage · History |
 Device |
- Puffco Peak Pro, every colorway. Heat control, profiles, battery, usage, the fault log and LED colours all work across Peak Pro firmware versions. Firmware before AF stores LED colours in an older format; QuickPuff writes that format the way the Puffco app does, but it has only been tested on newer firmware so far.
- Firmware from before Puffco's current Bluetooth protocol can't connect. Update it once in the Puffco app.
- More than one Peak nearby (or a friend's): choose it with Find nearby
Peaks in the panel, or run
quickpuff scanand thenquickpuff connect --mac AA:BB:.... - Any Bluetooth adapter BlueZ supports (see Bluetooth adapter).
- The Puffco Proxy and Pivot are not supported.
omarchy plugin add https://github.com/Auxxed/quickpuff --enable && ~/.config/omarchy/plugins/auxxed.quickpuff/install.shomarchy plugin add installs the bar widget. install.sh sets up what the
widget needs, all inside your home directory with no root access:
- a Python environment in
~/.local/share/quickpuff/venvwith the Bluetooth libraries from PyPI:bleak,cbor2anddbus-fast - the
quickpuffcommand in~/.local/bin - the
quickpuff-daemonsystemd user service, which holds the one Bluetooth connection the widget and the command share
If you add the plugin without running install.sh, the widget shows
Finish setup, which runs it in a terminal.
Requirements: Python 3.10 or newer, BlueZ, and systemd — all present on a standard Omarchy install.
Then wake the Peak, keep it near the computer, and disconnect the Puffco phone app (the Peak accepts one connection at a time). Click the QuickPuff widget and choose Connect.
If something doesn't work, run quickpuff doctor. It checks Bluetooth, the
background daemon, the bar widget and your Peak, and prints the command that
fixes anything it finds.
omarchy plugin update auxxed.quickpuff && ~/.config/omarchy/plugins/auxxed.quickpuff/install.shUsed this back when it was called OmaPuffco or Ember? Remove the old plugin with
omarchy plugin remove auxxed.omapuffco --yes (or auxxed.ember), then run the
install line above. install.sh stops the old daemon and carries your settings
and dab history across.
install.sh moves your settings and dab history across and swaps the old
widget out, keeping its place in the bar.
~/.config/omarchy/plugins/auxxed.quickpuff/uninstall.shThis stops the daemon, removes the quickpuff command and the Python environment,
and removes the plugin. Your dab history (~/.local/share/quickpuff/dabs.json) and
settings (~/.config/quickpuff) are kept; delete those folders too for a clean
removal.
- Bar — chamber temperature and battery, with ⚡ while plugged in. While battery saver rests the Peak, it keeps showing the last battery reading. Left-click opens the panel, right-click starts a heat cycle, middle-click refreshes.
- Control — Heat, Boost and Stop, with a countdown ring while the Peak heats up and during the session; the four heat profiles (click one to select it, click a value to type it, or nudge it with − and +); vapor level; and boost temperature and time. Below 10% battery, unplugged, it warns that the Peak may refuse to heat.
- Lights — LED on/off, brightness, stealth mode, the selected profile's LED color.
- Usage — today, this week, this month and lifetime counts, a daily chart, streaks, your peak hour, average session length and temperature, and which heat profiles you used over the last 30 days (with each one's usual temperature). History lists every dab with its profile, temperature and heat-up time; tap one to add a note, and tap again any time to edit it.
- Care — Battery Preservation (charge to 80% only, the same setting as the Puffco app's), battery saver (30 seconds after a session or after 10 minutes idle, turns the lantern off and lets the Peak rest), a Q-tip reminder after each dab, and a chamber-clean reminder (every 10–100 dabs); under Goals, an optional daily limit and a weekly recap on Sunday evenings.
- Device — rename the Peak; model, chamber, battery (with time until full while charging), battery capacity and health, firmware, serial and uptime; the fault log of heater, battery and pairing problems (saved per Peak, so it opens instantly after the first read); disconnect so your phone or another computer can connect; power off. Tips has the factory heat presets (490 / 510 / 530 / 545°F) and a short care list.
QuickPuff sends a desktop notification when the Peak reaches temperature, once
when the battery drops to 15% (again only after it recovers or charges), and
when the chamber is due a clean. After each session that reached temperature
it reminds you to Q-tip the chamber while it's still warm; switch that off under
Care or with quickpuff qtip off. If you set a daily limit, it notifies once
the day you reach it, and every Sunday evening it sends a weekly recap (how
many sessions, your most-used profile, and how that compares with the week
before); both live under Care → Goals. Turn the ready and low-battery alerts off with
"notify_ready": false or "notify_low_battery": false in
~/.config/quickpuff/config.json.
After a restart or reboot the daemon reconnects to the last Peak on its own.
Pressing Disconnect (or quickpuff disconnect) stops that until you connect
again.
Battery capacity is what the Peak's fuel gauge has learned the pack holds, shown against the stock Peak Pro battery's rated 1700 mAh.
To go easy on the Peak's battery, QuickPuff checks it every 20 seconds while nothing is heating and the panel is closed, every 3 seconds with the panel open, and several times a second during a heat cycle. Battery health and the counters are re-read once a minute while the panel is open and after each session; the heat profiles when the panel opens.
With battery saver on, QuickPuff also lets go of the Peak when it's done.
The Peak Pro ignores a sleep command over Bluetooth — it acknowledges
ModeCommands.SLEEP and stays in Idle at an unchanged 35 mA — and an open
Bluetooth link keeps its radio busy, so 30 seconds after a session (or after
10 idle minutes) the daemon disconnects and the bar shows the last battery
reading as resting. Opening the panel or running a command reconnects in a few
seconds, and every 15 minutes it checks in to refresh the battery and count new
dabs. While it rests, a dab started with the Peak's own button gets no "ready"
notification; it's counted at the next check-in.
Measured on a Peak Pro (firmware AW, a 1397 mAh pack as its gauge has learned
it) by reading /p/bat/curr, /p/bat/volt and the fractional /p/bat/soc:
| State | Draw | Share of the pack per day |
|---|---|---|
| Bluetooth link up, idle | 45 mA | 77% |
| Link down but something reaching for it (retries, scanning) | ~9.6 mA | 16% |
| Battery saver resting, with its check-ins | ~1.4 mA | 2.4% |
| Left alone entirely | 0.5–0.9 mA | ~1.2% |
Holding the link is the whole cost, and it is roughly 50x what a rested Peak draws. How fast QuickPuff polls over that link barely matters: idle polling every 20 seconds measured 3.23 %/h against 2.88 %/h at the panel-open rate of every 3 seconds, which is the same number inside run-to-run noise. Letting go is the only thing that helps, which is what battery saver does.
For scale, one dab costs 4–9% of the pack. A dab is worth several days of a rested Peak, so idle drain is not what empties it — an open link is.
Powering the Peak off after a dab saves nothing worth having over letting
battery saver rest it: the most it can recover is the ~1 mA a rested Peak
draws. The off state's own draw could not be measured, because the gauge stops
counting coulombs while the Peak is off and re-derives charge from cell voltage
when it wakes; a reading taken across a power cycle reflects that correction
rather than anything consumed. /p/bat/soc is only meaningful between two
readings taken without a power cycle in between.
The Peak keeps its own log of heat cycles. QuickPuff reads it when it connects and
after each session, and counts every cycle that reached temperature;
quickpuff sync does the same on demand. Until the phone app sets the Peak's clock
after a restart, the log's timestamps count from boot. QuickPuff places those using
the Peak's current clock, and skips cycles from before a later restart rather
than guessing their date. For any period the device log no longer covers, the
cycles QuickPuff saw while connected fill in.
Usage is kept per Peak, by serial number. Your Peak brings its stats to any computer running QuickPuff, rebuilt from its own log, and a friend's Peak shows its own stats instead of mixing into yours. The Peak's log holds roughly its last 1,000 events (several weeks of use); older day-by-day history stays on the computer that recorded it. The lifetime total always comes from the Peak.
The widget runs these under the hood; they also work for scripting or outside Omarchy.
quickpuff scan
quickpuff connect # or: quickpuff connect --mac AA:BB:...
quickpuff disconnect # free the Peak for your phone or another PC
quickpuff status
quickpuff heat start|stop|boost
quickpuff profile 0 --temp-f 510 --time 75 --color '#ff6a1a'
quickpuff lantern on
quickpuff brightness 160
quickpuff color '#ff6a1a' --index 0 # a profile's LED color
quickpuff stealth on
quickpuff battery # show the charge on the Peak's own lights
quickpuff preserve on # stop charging at 80% (off: charge to 100%)
quickpuff saver on # rest the Peak after sessions and 10 min idle
quickpuff clean --every 30 # remind after N dabs (10–100)
quickpuff clean done # reset the cleaning countdown
quickpuff qtip on|off # Q-tip reminder after each dab
quickpuff sessions --limit 20 # recent dabs with their notes
quickpuff note d1473 "great flavor" # add or edit a dab's note (no text clears it)
quickpuff limit 5 # notify after 5 dabs in a day (0 = off)
quickpuff recap # this week so far; `recap on|off` for Sundays
quickpuff stats # today / week / month / year / lifetime
quickpuff sync # pull usage history from the Peak's log
quickpuff faults # faults the Peak recorded
quickpuff doctor # check Bluetooth, the daemon and your Peak
quickpuff waybar # status JSON for the bar widget
quickpuff offQuickPuff uses the first powered adapter BlueZ reports. To pin a specific one when
you have several, set it in ~/.config/quickpuff/config.json (bluetoothctl list
shows what you have):
{ "adapter": "hci1" }git clone https://github.com/Auxxed/quickpuff.git
cd quickpuff
./install.sh # links the checkout in as a development plugin
~/.local/share/quickpuff/venv/bin/pip install pytest
~/.local/share/quickpuff/venv/bin/python -m pytestKeep virtual environments outside the checkout: omarchy plugin refuses
symlinks inside a plugin folder, and a venv is full of them.
The tests cover the CBOR and color codec, audit-log decoding, dab-history date
maths, config and profile limits, battery saver resting and waking, the command
queue, notifications and goals, quickpuff doctor, the CLI parser, the daemon
liveness probe, and the plugin manifest. The Bluetooth layer itself needs real
hardware, so it's exercised by hand against a Peak Pro.
Protocol work builds on Fr0st3h/PuffcoBLE and the OldGrowthCrypto Linux/BlueZ fork; audit-log decoding follows puff.social.