DEV Community: Paul Contreras

I built Observe: a system monitor for your terminal

Paul Contreras — Mon, 13 Jul 2026 09:54:32 +0000

A live terminal monitoring cockpit for CPU, memory, disk, network, ports, and busy processes.

When something slows down on my machine, I usually open several commands to check CPU, memory, disk usage, network activity, ports, and running processes.

I wanted a simpler way to see everything in one place, so I built Observe.

Observe is an open-source terminal dashboard that shows what your machine is doing in real time.

It includes:

CPU, memory, disk, and network usage
Processes using the most resources
Listening ports
Disk I/O and swap pressure
Docker container activity
Simple warnings for possible bottlenecks

There is no account, database, agent, or initial configuration. Everything runs locally, and your system metrics are not uploaded anywhere.

Install

Using Homebrew:

brew install pol-cova/homebrew-tap/observe

Or using Go:

go install github.com/pol-cova/observe@latest

Then run:

observe

You can also monitor a remote machine over SSH:

observe --ssh user@host

Or save a diagnostic snapshot:

observe snapshot --output diagnostics.json

Observe is written in Go and released under the MIT license.

You can find the source code here: https://github.com/pol-cova/observe

Feedback, issues, and contributions are welcome.

What if your little moments became a song? I built Boppi with Gemini + Strudel 🎵

Paul Contreras — Sun, 12 Jul 2026 10:49:10 +0000

This is a submission for Weekend Challenge: Passion Edition.

TL;DR: Boppi turns everyday moments into tiny songs.

Add a photo, a short caption, and a vibe. Gemini understands the feeling behind the moment and creates a musical plan with melody, bass, and rhythm. Strudel then turns that plan into a song you can hear and share.

You can create a Bop alone or invite friends into a private room and combine your moments into one song.

Built with Next.js, Bun, Convex, Gemini, Strudel, and Vercel.

Try Boppi → https://boppi.vercel.app

What I Built

What was one little thing you loved today?
Maybe it was finally making a good coffee.
Maybe it was the rain while you were coding.
Maybe it was playing a game with your friends, seeing a really nice sunset, or finding a song you could not stop replaying.

When I saw the theme of this challenge, I first thought about building a normal music generator. You write a prompt, AI generates a song, and that is it.

But I wanted to make something more personal and social.

I also wanted it to be small enough that someone could understand it immediately and actually enjoy using it.

That became Boppi.

Little moments. One tiny song.

Boppi lets you turn a real moment from your day into a short song called a Bop.

You add:

One photo
A short caption
A vibe

For example:

Photo: my desk while it rains outside
Caption: late night coding
Vibe: calm

Gemini looks at the photo, reads the caption, and understands the feeling behind it.

It then creates a musical direction for the moment:

Mood: focused and calm
Tempo: 88 BPM
Melody: soft and repetitive
Bass: warm and slow
Rhythm: light keyboard-like percussion

Strudel uses that direction to perform the final song directly in the browser.

The result is a short, playful soundtrack made from something that actually happened to you.

The aha moment

The main experience is not just pressing a button and waiting for an AI song.

Boppi shows how your moment is becoming music.

For example:

Your rainy window became the atmosphere.

Your keyboard became the rhythm.

Your late-night energy became the bass.

Your caption inspired the melody.

Each layer appears and starts playing one by one.

Then everything joins together into the final Bop.

That reveal is the part I built the product around.

The song does not need to be perfect or three minutes long. It only needs to create the feeling:

“Wait, this actually sounds like my moment.”

Create a Bop alone

Sometimes you just want to capture something for yourself.

In Solo mode, you add one photo, caption, and vibe. Boppi turns it into a personal tiny song.

You can then share it using a public page:

RAINY DEBUGGING

a tiny song by Paul

calm · focused · 88 BPM

[ Play Bop ]

It is a different way to share a moment.

Instead of only saying:

“This was my day.”

You can say:

“This is what my day sounded like.”

Create a Bop with friends

Boppi also has private rooms.

You create a room, send the invite link to your friends, and everyone contributes one moment.

There are no followers, public profiles, likes, or infinite feeds.

Just one small room and one shared song.

For example:

Paul
late-night coding

Andrea
morning coffee

Mateo
football with my dad

Sofia
the sky looked unreal

Gemini analyzes the group as a whole and gives every moment a musical role:

Paul’s coding became the rhythm.

Andrea’s coffee became the bass.

Mateo’s football match became the percussion.

Sofia’s sunset became the melody.

Strudel combines all four parts into one shared Bop.

The final result is something that only exists because those specific people shared those specific moments.

That is what makes the social part interesting to me.

You are not posting for strangers or trying to get likes. You are making a tiny creative memory with people you care about.

Why this fits the Passion Edition

When we talk about passion, we normally think about big things.

The project you spend every night building.

The team you always support.

The hobby you have practiced for years.

But I think passion also appears in smaller moments.

It is the coffee you keep trying to improve.

The game you always play with the same friends.

The music you listen to while working.

The sunset that makes you stop walking for a second.

The random thing that made your day a little better.

Boppi is about noticing those moments and turning them into something you can keep and share.

It does not ask:

“What is the most important passion in your life?”

It asks something much simpler:

“What did you love today?”

Demo

Try the live app → https://boppi.vercel.app

Solo Bop

Add a photo.
Write a short caption.
Choose a vibe.
Watch the musical layers appear.
Listen to your Bop.
Share it.

Room Bop

Create a private room.
Invite your friends.
Everyone adds one moment.
Gemini finds the connection between them.
Every moment receives a musical role.
Strudel performs the shared song.

At end you can see the archives of your bops

Code

The source code is available on GitHub:

Repository → https://github.com/pol-cova/boppi

How I Built It

Boppi uses:

Next.js for the web application and UI
Bun for package management and local development
Convex for private rooms, moments, and real-time updates
Gemini for multimodal understanding and composition planning
Strudel for generating and performing the music
Vercel for deployment

The basic pipeline looks like this:

photo + caption + vibe
          ↓
       Gemini
          ↓
structured musical plan
          ↓
validated Strudel patterns
          ↓
       tiny song
          ↓
    shareable Bop

Understanding the moment with Gemini

Gemini receives the user’s photo, caption, and selected vibe.

Instead of asking it to return random music code, I ask it to produce a structured composition plan.

A simplified response looks like this:

{
  "title": "Rainy Debugging",
  "description": "A calm and focused late-night moment",
  "bpm": 88,
  "scale": "D minor",
  "energy": 0.35,
  "mood": "calm",
  "template": "cozy",
  "layers": {
    "melody": {
      "density": "low",
      "movement": "repetitive"
    },
    "bass": {
      "style": "warm",
      "movement": "slow"
    },
    "rhythm": {
      "density": "light",
      "texture": "digital"
    }
  }
}

This was an important decision.

Letting a model generate unrestricted executable Strudel code would make the result less reliable and harder to control.

Instead, Gemini makes the creative decisions while Boppi maps those decisions into tested musical building blocks.

That gives me a balance between AI creativity and consistent output.

Creating the song with Strudel

Boppi contains a small set of handcrafted song templates.

For the first version, I focused on three:

Cozy
Playful
Energetic

Each template has slots for:

Melody
Bass
Rhythm
Atmosphere

Gemini selects the template and controls values such as tempo, density, note movement, and intensity.

Boppi then generates the final Strudel pattern.

A simplified example:

stack(
  note("<d4 f4 a4 c5>")
    .slow(2)
    .sound("triangle"),

  note("<d2 d2 f2 a2>")
    .slow(2)
    .sound("sawtooth")
    .lpf(700),

  s("bd ~ hh ~")
    .gain(0.7)
)
.cpm(88)

Strudel performs everything in the browser, which also makes the reveal feel alive.

The user can see the layers being constructed while hearing them enter the song.

Combining moments inside a room

Convex manages the room state and keeps contributions synchronized.

Each room contains:

room
├── invite code
├── members
├── moments
└── generated Bop

When someone contributes, the room updates immediately for everyone else.

Once the group is ready, Gemini receives all the moments together.

It does not create four unrelated songs. It decides how each contribution can become part of one coherent composition.

One moment might provide the melody.

Another might control the rhythm.

Another might define the atmosphere.

This is what turns the room into a collaboration instead of a simple gallery.

Interesting decisions

No full music editor

I did not want Boppi to become a DAW or a complicated music tool.

The user only chooses a vibe.

The rest of the experience is about discovery.

Tiny songs instead of full songs

A Bop is intentionally short.

It is meant to feel like a musical snapshot, not a finished commercial track.

This also makes it easier to listen to, generate, and share.

No traditional social feed

I wanted something social without recreating another feed.

Private rooms are enough for the main idea.

The song is the social object.

Gemini creates meaning, Strudel creates sound

Gemini does not directly generate the final audio.

It understands the moment and creates the musical intention.

Strudel turns that intention into something you can hear.

Both tools have a clear role in the product.

Prize Categories

Best Use of Google AI

I am submitting Boppi for Best Use of Google AI.

Gemini is not used only to generate a title or add a chatbot to the app.

It powers the central transformation:

real moment → emotional meaning → musical composition

Gemini:

Understands the uploaded photo
Connects the image with the caption
Interprets the selected vibe
Creates the title and description
Selects the tempo, mood, and scale
Plans the melody, bass, and rhythm
Assigns musical roles in friend rooms
Finds a shared direction between different moments

Without Gemini, Boppi would only be a collection of photos.

Gemini is what turns those moments into music.

What I learned

The hardest part was not generating more music.

It was deciding how little control the product actually needed.

My first ideas included editors, timelines, custom instruments, public profiles, reactions, and many other features.

But the more things I added, the less clear the product became.

The final experience is much smaller:

add a moment
hear its song
share it

That constraint made Boppi feel more like a real product and less like a collection of hackathon features.

What comes next

There are a few ideas I would like to explore after the challenge:

Recording a short real-world sound with every photo
Weekly mixtapes made from previous Bops
More musical styles
Collaborative reactions that add a tiny sound
Animated share cards
Daily prompts for friend rooms

For now, I wanted to keep the first version focused on one simple feeling:

A normal moment can become something special when you hear it differently.

Try it

Try Boppi → https://boppi.vercel.app

View the code → https://github.com/pol-cova/boppi

I would love to know what your first Bop would be.

What was one little thing you loved today? 🎵

I built gessi: playful OS-style interfaces with just HTML

Paul Contreras — Thu, 25 Jun 2026 19:58:38 +0000

Meet gessi, a dependency-free CSS and Web Component library for building retro desktops, draggable windows, and expressive interfaces without framework lock-in.

I’ve been working on Gessi, an open-source CSS and Web Component library for building playful web interfaces with plain HTML.

The idea behind it is simple:

Websites do not always have to feel like landing pages.

They can feel like desktops.
They can feel like tiny operating systems.
They can feel like archives, control panels, old computers, personal desks, or interactive product demos.

That is the kind of web I wanted to make easier to build.

So I made Gessi.

A tiny desktop in HTML

Here is the smallest example:

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@pol-cova/gessi/dist/gessi.js"
></script>

<gessi-desktop menu="◆ My OS,File,View,Help" clock="09:41">
  <gessi-window title="hello.html" width="38rem" active draggable>
    <h1>Hello from Gessi</h1>
    <p>This is normal HTML inside a draggable window.</p>
  </gessi-window>
</gessi-desktop>

That is a complete working page.

The script registers the components and loads the styles automatically.

No React runtime.
No build setup.
No package installation.
No framework required.

Just HTML.

What Gessi helps you build

Gessi is made for interfaces that want to feel more expressive than a normal page.

You can use it to build things like:

a personal website that feels like a desktop
a portfolio that opens projects inside windows
a retro product demo
a media archive with folders and panels
an experimental blog layout
a tiny browser-based operating system
a playful docs or internal tool interface
a landing page that feels more like an app

The goal is not to replace your whole stack.

The goal is to give you a set of reusable interface pieces so you can build something more memorable without starting from zero.

Components included

Gessi includes the common pieces needed for small desktop-like interfaces:

desktops
draggable windows
minimizable and zoomable windows
dialogs
nested child windows
menus
toolbars
docks
tabs
trees
desktop icons
control panels
alerts
notifications
tooltips
meters
responsive maps
carousels
image effects
pixel patterns
classic OS-inspired themes

You can combine these pieces to create different kinds of browser-based environments.

For example, the docs include complete examples like:

Product OS
Classic OS
Media OS

Each one uses the same idea: normal HTML content wrapped inside reusable Gessi components.

Multiple visual systems

Gessi currently includes five visual systems:

neo
minimal
retro
old-tech
classic-os

The idea is that your structure can stay mostly the same while the visual style changes.

You can start with something clean and minimal, then move into a more nostalgic or old-tech look without rebuilding the whole interface.

Why I made it framework-independent

I wanted Gessi to work in as many projects as possible.

You can use it with:

a single static HTML file
Astro
Eleventy
Hugo
Jekyll
server-rendered templates
React
Vue
Svelte
any project that only wants the CSS layer

The components are built with Web Components and use light DOM.

That means your content remains normal HTML. It exists before JavaScript runs, stays available to your own CSS, and still has a readable fallback if the interactive layer does not load.

Gessi handles the reusable interface behavior and visual chrome.

Your project still owns the content, layout, and personality.

It also works with npm

You can install it from npm:

npm install @pol-cova/gessi

Then import the CSS and components:

import "@pol-cova/gessi/css";
import "@pol-cova/gessi/components";

The component module is safe to import during SSR, and it does not inject CSS when used through a bundler.

Why this exists

A lot of modern websites are starting to feel very similar.

Same cards.
Same dashboards.
Same layouts.
Same generic sections.

There is nothing wrong with that. Those patterns are useful, and I use them too.

But I also think the web is more fun when interfaces have personality.

I wanted a small library that makes it easier to build websites that feel unusual, nostalgic, playful, or simply less generic.

That is what Gessi is trying to become.

The project is early

Gessi already has working components, examples, and documentation, but it is still early.

There is a lot of room to improve the project.

Some areas I would love help with:

new components
better component APIs
Markdown and MDX support
a first-party pixel icon set
more themes
a public custom-theme API
accessibility and keyboard testing
Firefox and WebKit testing
examples with real static-site generators
documentation improvements
design feedback

You do not need to contribute a huge feature.

A small bug report, browser test, accessibility fix, documentation correction, or example of something you built would already be valuable.

Try Gessi

Documentation: https://pol-cova.github.io/gessi/
GitHub: https://github.com/pol-cova/gessi
npm: https://www.npmjs.com/package/@pol-cova/gessi

If Gessi helps you build something weird, nostalgic, playful, or simply less generic, I would genuinely love to see it.

Feel free to try it, open an issue, share feedback, or contribute to the project.

Why I Redesigned StrictBlock to Make Focus Feel Easier

Paul Contreras — Sun, 21 Jun 2026 06:43:55 +0000

I rebuilt StrictBlock (my app) from the ground up.

StrictBlock is an iPhone app blocker and focus app designed to help people stop procrastinating, protect deep work, and build better focus habits.

For this relaunch, I did not want to just “refresh the UI.” I wanted to redesign the full product experience around one question:

How can I make starting a focus session feel simple, strict, and useful?

The new version focuses on reducing friction. Users can create focus profiles for study, work, sleep, deep work, or Pomodoro sessions, then start blocking distracting apps and websites with less setup.

I also redesigned the app around accountability. StrictBlock now includes streaks, trophies, weekly reports, widgets, session journaling, and consequences for ending sessions early.

As a developer, this redesign was a good reminder that productivity apps are not only about features. They are about behavior. The UI, the flow, the defaults, and the friction all shape whether someone actually stays focused.

StrictBlock is now live with a complete redesign.

Would love feedback from other builders, iOS devs, and product engineers.

Try it here: Download strictblock on appstore

Can You Beat Gemini Before Sunset? I Built a Solstice Puzzle Duel

Paul Contreras — Sun, 21 Jun 2026 05:17:03 +0000

This is a submission for the June Solstice Game Jam

What I Built

I built Color Queens: Solstice Duel, a small logic puzzle game where you race Gemini before the sun sets.

The idea started with one simple question:

Can human logic beat an AI in a puzzle duel?

Many games let players compete against bots, but I had rarely seen a game where the opponent is actually a LLM. That curiosity became the starting point for this project. I wanted to see what would happen if an LLM was not just powering dialogue behind the scenes, but actively participating in the gameplay as a rival.

In the game, you and Gemini receive the same board. Your goal is to place queens across colored regions while following the rules: one queen per color, no attacks, no row conflicts, no column conflicts, and no diagonal conflicts.

For the June Solstice theme, I added a light and shadow layer. The board is not only about placing queens correctly, it is also about balancing daylight before sunset. As time passes, the mood shifts from warm daylight into night, so the solstice becomes part of the pressure of the game.

I also added Pride-inspired boards because Color Queens is already about color, identity, and pattern. I wanted those boards to feel joyful and intentional, not just decorative.

The main goal was to make something that feels simple to understand, but still has a strong hook:

You are not just solving a puzzle. You are dueling Gemini.

Video Demo

Code

The project is built as a web game so anyone can try it without installing anything.

Live demo:
Try now! colorqueens.xyz

Source code: https://github.com/pol-cova/colorqueens-game

How I Built It

I built the game around a local puzzle engine.

The most important decision was this:
Gemini is a player, not the judge.

Gemini can suggest a move, but the game validates that move locally using the same rules that apply to the human player. If Gemini makes an illegal move, the board calls it out.

That made the duel feel more interesting, because the AI is not treated as magically correct. It has to play by the rules too.

The main systems are:

A Color Queens board renderer
A local move validator
A light and shadow solstice rule
A Gemini opponent mode
A backtracking solver
A Turing Tape replay system
A small binary mini-game called Bombe Calibration

The Turing Tape was one of my favorite parts to build. After a puzzle, it shows how the solver thinks step by step: scanning regions, trying cells, rejecting conflicts, accepting candidates, and backtracking when a branch fails.

I wanted the algorithm to feel visible, almost like watching the machine think.

The Bombe Calibration mini-game is a short binary challenge. Before unlocking a hint, the player taps a quick 0 and 1 sequence. It adds a little tension, sound, and movement while keeping the main game focused on logic.

Prize Category

I am submitting this for both additional prize categories.

Best Google AI Usage

Gemini is used directly inside the game as an opponent.
Instead of only using AI to generate text or assets, I wanted Gemini to become part of the core game loop. It receives the current board state, proposes a queen placement, and then the local validator checks whether that move is legal.

That means Gemini can win, fail, recover, or get rejected by the rules.

I liked this approach because it makes the AI interaction playable. It is not just a chatbot on the side. It is part of the duel.

Best Ode to Alan Turing

The game connects to Alan Turing through logic, algorithms, and machine reasoning.

The Turing Tape shows a backtracking solver working through the puzzle one step at a time. It checks constraints, rejects invalid cells, and searches for a valid solution.

The Bombe Calibration mini-game is also a small nod to code-breaking and binary logic.

I wanted the Turing tribute to live inside the mechanics, not just in the story text.

Final Thoughts

This was a fun project because it mixed a few things I really care about: polished puzzle design, AI as part of the experience, and a simple idea that is easy to explain.

Can you beat Gemini before sunset?

That is the whole challenge.

Try the game, race the machine, and let me know who wins. Coming soon on the App Store. Join to the waitlist

Button Remapping: Knowing When to Stop Reverse-Engineering

Paul Contreras — Sun, 14 Jun 2026 10:18:59 +0000

Part 5 of a series on building a native Razer mouse controller for macOS.

Last feature: remap the two side buttons. Make the forward one a left click, or copy, or whatever. Synapse does it, so the mouse can do it, so I just need the command. Right?

This is the part where I spent an evening getting the device to say yes and do nothing, then threw the whole approach away and solved it in a completely different place. I think the second half is the more useful lesson.

The Firmware Hunt

There's no public table for "remap a DeathAdder V2 button." So I built a probe tool: send an arbitrary class/id with arbitrary args, print the full response. Then I swept ranges of commands looking for anything that responded 0x02 (OK) and looked button-shaped.

I found the profile system. Class 0x05 and 0x06 commands all answered. There's a per-button read at 0x05 / 0x8A that echoes back which button you asked about. There's a write at 0x05 / 0x0A. Driver mode, profile slots, the works. It all looked exactly like where button bindings would live.

So I tried the obvious write: button 4, action type mouse, parameter left-click. Sent it.

status: OK

Pressed the button. Nothing changed. Read it back. Unchanged.

Tried it in driver mode first. OK. Nothing. Tried selecting the profile slot before writing. OK. Nothing. Tried five different argument layouts. Every single one came back 0x02. Every single one did nothing.

If you read part 3, you know exactly what this is. 0x02 means the packet was well-formed and understood as a command. It does not mean it did what I wanted. I was writing into a void the firmware was politely accepting.

It got worse. One of my "reset to default" attempts used action type 0x00, which I assumed meant "firmware default." It actually means disabled. I turned my own side button off and didn't realize for a minute why pressing it did nothing at all. (Fix: clear the profile slot entirely and let the firmware take back over. Or just unplug and replug.)

After an evening of this I had a pile of commands that all returned OK and a mouse whose buttons were exactly as unremapped as when I started. The firmware path was a wall. Without capturing real Synapse USB traffic on Windows to see the exact bytes, I was guessing, and the device's "OK" gave me no signal to guess better.

The Pivot

Here's the reframe that fixed it. I don't actually need the mouse to remap the button. I need the button press to do something different on my Mac. Those aren't the same problem, and the second one doesn't involve Razer at all.

macOS lets you intercept input events with a CGEventTap. You watch for mouse button events, and when the one you care about fires, you swallow it and post a different event instead. This is how the commercial Mac mouse utilities do it. None of them reprogram firmware. They all sit in the event stream.

First I just needed to know which button number the OS sees for each side button. A listen-only tap that logs:

let n = event.getIntegerValueField(.mouseEventButtonNumber)
print("otherMouseDown buttonNumber=\(n)")

Pressed both side buttons. The forward one (near the wheel) is #4, the back one is #3. Now I can target them.

Actually Remapping

To change an event, not just watch it, the tap has to be active (.defaultTap), and that needs Accessibility permission, not Input Monitoring. Different permission, different System Settings pane. Worth knowing up front: a listen-only tap needs Input Monitoring, a tap that modifies or drops events needs Accessibility.

The handler: if it's a button I manage and it's mapped to something, swallow the original and synthesize the replacement.

nonisolated private func handle(type: CGEventType, event: CGEvent) -> Unmanaged<CGEvent>? {
    let button = Int(event.getIntegerValueField(.mouseEventButtonNumber))
    let action: MouseAction
    switch button {
    case 4: action = forwardAction
    case 3: action = backAction
    default: return Unmanaged.passUnretained(event)  // not ours
    }
    guard action != .passthrough else { return Unmanaged.passUnretained(event) }

    if type == .otherMouseDown { perform(action, at: event.location) }
    return nil   // swallow the original
}

perform posts whatever you mapped to: a left click is a synthesized leftMouseDown/leftMouseUp, copy is ⌘C as a key event, and so on. Press the side button, the click happens where your cursor is. It just works, immediately, the first time, with no guessing about byte layouts.

The Tradeoff, Honestly

Software remapping isn't strictly better than firmware remapping. The differences are real:

It only works while my app is running. Firmware remapping would persist on the mouse, even on another computer or in a BIOS screen.
It's Mac-only. The mouse's own memory doesn't know anything changed.

For a menu bar app that launches at login, "only while the app runs" is basically always, so the tradeoff barely bites. And the firmware version had one fatal flaw the software version doesn't: it didn't work.

That's the actual lesson from this whole feature. I spent an evening determined to solve the problem at the layer I'd decided it lived at. The device kept telling me OK and doing nothing, and I kept reading that as "almost there." The fix wasn't a better byte sequence. It was stepping up one layer to where the problem was tractable and the feedback was honest: press button, thing happens, or it doesn't.

Reverse-engineering is fun right up until the point where it's just you and a device that says yes to everything. Knowing when to stop is part of the skill.

Where This Lands

Five parts in, the app does what Synapse does for the things I care about: DPI with presets, static and animated lighting, side button remapping, all from a menu bar icon, no Razer account, no background service phoning home. The protocol work was the interesting half. The honest half was admitting one feature didn't belong in the protocol at all.

The full code is at github.com/pol-cova/RazerControl

Wrapping It in a Menu Bar App (and Three Things That Broke)

Paul Contreras — Wed, 10 Jun 2026 07:16:26 +0000

Part 4 of a series on building a native Razer mouse controller for macOS.

The protocol works from a command line tool. Now I want it living in the menu bar: a little mouse icon, click it, set DPI and color, no Terminal. SwiftUI has MenuBarExtra for exactly this, so it should be quick.

It was not quick. Three separate things broke, none of them about the mouse. This is the part where the OS fights you.

The Crash Before Anything Renders

The starting point. An accessory app (menu bar only, no Dock icon) usually sets that with:

@main
struct RazerControlApp: App {
    init() {
        NSApp.setActivationPolicy(.accessory)
    }
    var body: some Scene { ... }
}

Launched it. Instant crash:

Fatal error: Unexpectedly found nil while implicitly unwrapping an Optional value
RazerControlApp.swift:15

NSApp is NSApplication!, an implicitly unwrapped optional. It's nil this early. The app object's init() runs before the shared application is set up, so NSApp is still nothing and the force-unwrap explodes.

This bites harder on newer projects because the default actor isolation is MainActor, and the timing of init() lands before NSApp exists. You can fight the lifecycle, or you can not use code for this at all.

The fix is a plist key. LSUIElement = YES (in build settings, INFOPLIST_KEY_LSUIElement). It's read by the launch machinery before your App struct is ever created, so there's no race and no NSApp to unwrap. Delete the init() entirely.

INFOPLIST_KEY_LSUIElement = YES

No code, no crash, no Dock icon. The thing I was writing code to do was a setting the whole time.

macOS Won't Let the App Touch the Mouse

App launches now. Connects to the device. Immediately:

TCC deny IOHIDDeviceOpen
RazerControl: device not found

IOHIDDeviceOpen on a mouse needs Input Monitoring permission. The command line tool worked the whole time because it ran from Terminal, and Terminal already had Input Monitoring. A fresh signed .app has nothing.

macOS won't pop the permission dialog on its own. You have to ask, explicitly, with the right call:

let access = IOHIDCheckAccess(kIOHIDRequestTypeListenEvent)
if access == kIOHIDAccessTypeUnknown {
    IOHIDRequestAccess(kIOHIDRequestTypeListenEvent)
} else if access == kIOHIDAccessTypeDenied {
    // user said no earlier — send them to System Settings
}

kIOHIDRequestTypeListenEvent is imported as a plain constant, not a Swift enum case, so it's kIOHIDRequestTypeListenEvent and not .listenEvent. That cost me a compile error and a confused minute.

First launch now shows the system prompt. If the user denied it before, the prompt won't come back, so the app needs to detect that case and point them at System Settings rather than silently failing.

MenuBarExtra Has Two Personalities

The popover opened, but the layout was wrong. Everything stacked vertically like a dropdown menu. My HStack of buttons rendered as separate rows. The color picker wouldn't open. Frame widths were ignored.

MenuBarExtra has two render styles. The default is .menu, which puts your content inside a real NSMenu, so every view becomes a menu item and normal layout doesn't apply. The other is .window, which renders your SwiftUI in an actual floating panel where layout works like everywhere else.

MenuBarExtra("RazerControl", systemImage: "computermouse.fill") {
    MenuBarView()
}
.menuBarExtraStyle(.window)

One modifier. Suddenly HStacks are horizontal, widths apply, the popover looks like a popover. If your menu bar layout is behaving strangely, this is almost certainly why.

The Color Picker That Wouldn't Open

Last one. SwiftUI's ColorPicker renders a little well; click it and the system color panel opens. Except in my app, clicking did nothing.

ColorPicker relies on NSColorPanel. An accessory app (the LSUIElement thing from earlier) can't reliably bring up that panel, because it isn't allowed to become active the normal way, and the menu bar window dismisses the moment focus moves. So the panel either opens behind everything or never shows. The "selection" never happens, so the color never changes. One root cause, two symptoms.

I could have fought the activation policy. Instead I asked what a menu bar RGB control actually needs, and the answer is not a full color wheel. It's a handful of good colors, one tap.

So I replaced the picker with a row of preset swatches:

private let palette: [Color] = [
    .red, .orange, .yellow, .green, .cyan, .blue, .purple, .pink, .white
]
// tap a swatch -> apply immediately, ring the selected one

No NSColorPanel, no activation problem, and honestly better for a quick menu. Tap red, the logo's red. Done. The "fix" was less code and a nicer interaction than the thing that was broken.

What's Next

Part 5 is the button remapping, which is the part I was most sure would be easy and turned out to be the hardest. I spent an evening trying to reverse-engineer the firmware command for it, got the device to accept my writes, and watched nothing happen. Then I gave up on the firmware entirely and solved it a different way. That story is its own post.

DPI, Color, and Why "OK" Doesn't Mean It Worked

Paul Contreras — Mon, 08 Jun 2026 22:51:45 +0000

Part 3 of a series on building a native Razer mouse controller for macOS.

We have the envelope from part 2. Now the commands that actually do something: DPI and lighting. The DPI one is easy. The color one taught me the most useful lesson in this whole project, which is that the device telling you 0x02 (OK) is not the device telling you it did what you wanted.

Setting DPI

Command class 0x04, id 0x05, data_size 0x07.

The value is the raw DPI, not divided by anything. 800 DPI is 0x0320, split into a high byte and a low byte. The mouse stores X and Y sensitivity separately, so you send the pair twice.

func dpiReport(_ dpi: Int) -> [UInt8] {
    let v = UInt16(dpi)
    var r = [UInt8](repeating: 0, count: 90)
    r[1]  = 0x3F
    r[5]  = 0x07
    r[6]  = 0x04          // class: DPI
    r[7]  = 0x05          // id: set DPI
    r[8]  = 0x00          // stage
    r[9]  = UInt8(v >> 8)   // X high
    r[10] = UInt8(v & 0xFF) // X low
    r[11] = UInt8(v >> 8)   // Y high
    r[12] = UInt8(v & 0xFF) // Y low
    r[88] = r[2...87].reduce(0, ^)
    return r
}

This one is fire-and-forget. You don't need to read a response. Set it, feel the cursor speed change.

Reading DPI Back

There's a matching read command, class 0x04, id 0x85. Same idea, the id just has the high bit set, which is the convention for "get" versions of Razer commands.

I didn't think I needed this until the GUI app shipped and immediately created a bug: every time you opened the app it reset your DPI to 800. The app had a default of 800 and pushed it on connect, stomping whatever you'd actually set.

The fix was to read the device's real DPI on connect instead of forcing a default:

func getDPI() -> Int {
    // send class 0x04 id 0x85, read response
    let resp = request(...)
    return (Int(resp[9]) << 8) | Int(resp[10])
}

The DPI sits in the same byte positions in the response as you'd send it. Read first, then the UI reflects reality instead of overwriting it. Obvious in hindsight. Most of these bugs are.

The Color Command That Lied to Me

This is the part worth reading.

I wanted to set the logo and scroll wheel to a static color. I found a command that looked right, class 0x03, id 0x03, packed in the zone and an RGB triple, sent it. Got 0x02 back. OK. Accepted.

Nothing happened. The LED didn't change.

I checked the CRC. Fine. Checked the transaction ID. Fine. Checked the bytes ten times. The device kept saying 0x02. Accepted, accepted, accepted, and the logo stayed the color it already was.

The problem: 0x03 / 0x03 is not "set color." It's "set LED brightness." I was setting the brightness to a value, the device was happily setting the brightness to that value, and reporting success. It just wasn't a color command at all. I'd been sending a perfectly valid command for the wrong thing.

The real static color command for this device lives in a different family. Class 0x0F, id 0x02, the "extended matrix effect" commands. The layout:

data_size = 0x09
args[0] = 0x01        // varstore
args[1] = led_id      // scroll = 0x01, logo = 0x04
args[2] = 0x01        // effect: static
args[3] = 0x00
args[4] = 0x00
args[5] = 0x01
args[6] = r
args[7] = g
args[8] = b

Sent that. Logo turned green. First time the lighting actually moved.

The lesson stuck with me: a status of 0x02 only tells you the packet was well-formed and the device understood it as a command. It says nothing about whether it was the command you meant. A valid brightness-set and a valid color-set both return 0x02. If you're debugging by status code alone, you can burn an hour sending textbook-correct commands that do the wrong job.

Effects Come for Free

Once you're in the 0x0F / 0x02 family, the other lighting effects are just a different effect byte at args[2]:

Effect	args[2]	data_size
Off	`0x00`	6
Static	`0x01`	9 (+ rgb)
Breathing	`0x02`	9 (+ rgb)
Spectrum	`0x03`	6

Spectrum is the rainbow cycle. You set it once and the mouse firmware animates it on its own, no polling from your app. Breathing pulses a single color. Off goes dark. Same envelope, one byte different. After the static color fight, adding three more effects took about ten minutes.

What's Next

Part 4 leaves the protocol behind and wraps all this in a SwiftUI menu bar app. That sounds like the easy part. It was not. There's a crash that only happens because of a build setting, a permission macOS won't grant without being asked in a specific way, and a color picker that refuses to open. The protocol was more honest than the UI framework.

The Packet Format: 90 Bytes and One Cursed Byte

Paul Contreras — Sun, 07 Jun 2026 06:35:11 +0000

Part 2 of a series on building a native Razer mouse controller for macOS.

In part 1 we found the right HID interface and learned how to push a feature report at it. The report was just 90 zero bytes, which does nothing. This part is about what actually goes in those 90 bytes.

Every Razer config command uses the same fixed layout. Once you have the layout, every feature (DPI, lighting, polling rate) is just different values in the same envelope.

The Layout

[0]      status
[1]      transaction_id
[2-3]    remaining_packets
[4]      protocol_type
[5]      data_size
[6]      command_class
[7]      command_id
[8-87]   arguments (80 bytes)
[88]     CRC
[89]     reserved

When you send a command, byte [0] (status) is 0. When the device replies, it writes a status code back into byte [0]. Same buffer shape both ways.

The two bytes that pick what the command does are command_class ([6]) and command_id ([7]). Think of class as the subsystem (DPI, lighting, profiles) and id as the specific action inside it. Everything from byte 8 onward is arguments, and what they mean depends entirely on the class/id pair.

data_size ([5]) is how many of the argument bytes are meaningful. If your command uses 3 argument bytes, data_size is 3. Get this wrong and the device usually ignores you.

The CRC

Byte [88] is a checksum. It's an XOR of every byte from index 2 through 87, inclusive.

report[88] = report[2...87].reduce(0, ^)

That's the whole thing. No polynomial, no lookup table, just XOR. If the CRC is wrong the device rejects the packet, and you'll get a status that isn't 0x02 or no response at all.

The range matters. It's 2...87, not 0...89. The status and transaction ID at the front are excluded, and so are the CRC and reserved bytes at the end. I got this wrong the first time by including byte 1 and spent a while convinced my command bytes were the problem.

The Transaction ID

Byte [1] is the transaction ID, and it is the single most annoying byte in the whole format.

It's not part of the command. It doesn't change behavior. It's a tag the device firmware checks before it will even look at the rest of the packet. If it's wrong, the device acts like you said nothing.

The catch: the correct value is different across Razer devices, and nobody documents it per model. For the DeathAdder V2 it's 0x3F. Other devices use 0xFF or 0x1F. There's no command to ask the device what its transaction ID is. You either know it or you guess.

report[1] = 0x3F   // DeathAdder V2

If you're porting this to another Razer mouse and nothing works even though your command bytes look right, this is the first thing to change. Try 0xFF, then 0x1F, then 0x3F. One of them will start returning 0x02.

I hardcoded it. There's no reason to make it configurable in the app, because a wrong value just means a dead command.

A Real Command

Here's the firmware version request, which is the simplest useful command and a good first target because it returns data you can sanity-check:

var report = [UInt8](repeating: 0, count: 90)
report[1]  = 0x3F   // transaction id
report[5]  = 0x02   // data_size
report[6]  = 0x00   // command_class: standard
report[7]  = 0x81   // command_id: get firmware
report[88] = report[2...87].reduce(0, ^)

Send it, wait 300ms, read the response. If the stack is working, byte [0] of the response comes back 0x02, and the firmware version sits in bytes [9] and [10]:

print("firmware: \(response[9]).\(response[10])")
// firmware: 2.0

Seeing 2.0 print instead of 0.0 is the moment you know the whole chain works: right interface, right transaction ID, right CRC, right delay. Everything after this is just changing class, id, and arguments.

What's Next

Part 3 builds the real commands on top of this envelope: setting DPI, reading it back, and the static color command that I got wrong twice before it worked. There's a good lesson buried in that one about why "command accepted" doesn't mean "command did anything."

USB HID on macOS: Talking to Devices with IOKit

Paul Contreras — Mon, 01 Jun 2026 07:44:16 +0000

Part 1 of a series on building a native Razer mouse controller for macOS.

USB HID (Human Interface Device) is the protocol your mouse, keyboard, and gamepad use to talk to the OS. Most of the time it's invisible; The OS handles it and your app gets abstracted events.

But HID also has feature reports: raw byte arrays you can send directly to a device outside of normal input events. Manufacturers use these for configuration. That's how Razer Synapse sets DPI and RGB — and it's what we need to replace it.

On macOS, the API for this is IOHIDManager inside IOKit. No kernel extension required.

Setup

Command Line Tool target in Xcode, macOS, Swift. No sandbox add App Sandbox to entitlements and immediately remove it, or just confirm it's not there. IOKit feature reports fail silently with sandbox on.

Link IOKit.framework under target → General → Frameworks and Libraries.

import IOKit
import IOKit.hid
import Foundation

Finding a Device

IOHIDManager takes a matching dictionary. At minimum, vendor ID and product ID.

let manager = IOHIDManagerCreate(kCFAllocatorDefault, IOOptionBits(kIOHIDOptionsTypeNone))

IOHIDManagerSetDeviceMatching(manager, [
    kIOHIDVendorIDKey:  0x1532,
    kIOHIDProductIDKey: 0x0084
] as CFDictionary)

guard IOHIDManagerOpen(manager, IOOptionBits(kIOHIDOptionsTypeNone)) == kIOReturnSuccess else {
    print("failed to open manager")
    exit(1)
}

guard let devices = IOHIDManagerCopyDevices(manager) as? Set<IOHIDDevice>,
      !devices.isEmpty else {
    print("device not found")
    exit(1)
}

If you don't know your device's PID yet, filter by vendor ID only and print everything:

IOHIDManagerSetDeviceMatching(manager, [kIOHIDVendorIDKey: 0x1532] as CFDictionary)
// ... open manager ...
for d in devices {
    let name = IOHIDDeviceGetProperty(d, kIOHIDProductKey as CFString) as? String ?? "?"
    let pid  = IOHIDDeviceGetProperty(d, kIOHIDProductIDKey as CFString) as? Int ?? 0
    print("\(name): 0x\(String(pid, radix: 16))")
}

The Multiple Interfaces Problem

One physical USB device often enumerates as multiple HID interfaces. A Razer DeathAdder V2 shows up as four:

page: 0x1 | usage: 0x6 | maxFeatureReport: 1
page: 0x1 | usage: 0x6 | maxFeatureReport: 0
page: 0x59 | usage: 0x1 | maxFeatureReport: 64
page: 0x1 | usage: 0x2 | maxFeatureReport: 90

IOHIDManagerCopyDevices returns a Set. devices.first is non-deterministic you have a 1-in-4 chance of hitting the right interface. The wrong interfaces accept your data and do nothing with it. The send call returns 0 (success) and the device response is all zeros.

Print all interfaces first:

for d in devices {
    let usagePage  = IOHIDDeviceGetProperty(d, kIOHIDPrimaryUsagePageKey as CFString) as? Int ?? 0
    let usage      = IOHIDDeviceGetProperty(d, kIOHIDPrimaryUsageKey as CFString) as? Int ?? 0
    let maxFeature = IOHIDDeviceGetProperty(d, kIOHIDMaxFeatureReportSizeKey as CFString) as? Int ?? 0
    print("page: 0x\(String(usagePage, radix: 16)) | usage: 0x\(String(usage, radix: 16)) | maxFeatureReport: \(maxFeature)")
}

The interface you want for Razer configuration commands is the one with maxFeatureReport: 90 — that matches the 90-byte packet format Razer uses. Filter on it explicitly:

guard let device = devices.first(where: { d in
    (IOHIDDeviceGetProperty(d, kIOHIDMaxFeatureReportSizeKey as CFString) as? Int ?? 0) == 90
}) else {
    print("control interface not found")
    exit(1)
}

For other devices, the right interface depends on the protocol. maxFeatureReport size is usually the clearest signal.

Opening and Sending

After filtering, open the specific interface and send a feature report:

guard IOHIDDeviceOpen(device, IOOptionBits(kIOHIDOptionsTypeNone)) == kIOReturnSuccess else {
    print("could not open device")
    exit(1)
}

var report = [UInt8](repeating: 0, count: 90)
// ... fill report bytes ...

let result = IOHIDDeviceSetReport(device, kIOHIDReportTypeFeature, 0, &report, report.count)

Two things that caused me problems here:

Buffer size. IOHIDDeviceSetReport takes the report ID as a separate parameter (the 0 above). Do not prepend it to the buffer. If maxFeatureReport is 90, your buffer should be exactly 90 bytes. I was sending 91 and getting error -536850432 (0xE0005000) back from IOKit with no further explanation.

Reading the response. The response comes back in a separate IOHIDDeviceGetReport call. The device needs a small delay between send and read — the amount varies, but 200–300ms works reliably:

Thread.sleep(forTimeInterval: 0.3)

var response = [UInt8](repeating: 0, count: 90)
var responseLen = CFIndex(90)
IOHIDDeviceGetReport(device, kIOHIDReportTypeFeature, 0, &response, &responseLen)

Use a fresh buffer for the response so you can tell whether the device wrote anything into it.

Interpreting the Response

For Razer devices, byte [0] of the response is a status code:

Value	Meaning
`0x00`	No response / read stale data
`0x01`	Device busy
`0x02`	Command accepted
`0x05`	Command not understood

0x02 means the full stack is working. 0x05 usually means wrong command bytes or wrong transaction ID for the device family.

If you get all zeros back, you either read too fast, hit the wrong interface, or the buffer size was wrong.

What's Next

Part 2 covers the actual Razer packet format — what goes in those 90 bytes, how the CRC is computed, and what the transaction ID is and why it matters.

LaunchNotes: Simple What's New Screens for SwiftUI Apps

Paul Contreras — Mon, 01 Jun 2026 00:54:33 +0000

Show What's New in Your SwiftUI App with LaunchNotes

Somewhere in the third app I shipped, I got tired of rebuilding the same "What's New" screen.
It's never quite the same codebase, so copy-pasting doesn't work. And it's not interesting
enough to engineer properly each time.

I built LaunchNotes to stop thinking about it.

One view modifier. It compares the current bundle version to what's saved in UserDefaults
and shows a sheet if something changed.

import LaunchNotes

struct ContentView: View {
    var body: some View {
        HomeView()
            .launchNotes {
                LaunchNote(
                    "New Stats",
                    "Track your progress with cleaner charts.",
                    systemImage: "chart.line.uptrend.xyaxis"
                )
                LaunchNote(
                    "Smoother Animations",
                    "The app feels faster now.",
                    systemImage: "sparkles"
                )
            }
    }
}

You can also keep all release history in one place:

.launchNotes {
    LaunchNotesRelease("1.2.0", title: "What's New in 1.2") {
        LaunchNote("New Stats", "Cleaner progress charts.", systemImage: "chart.line.uptrend.xyaxis")
    }
    LaunchNotesRelease("1.1.0") {
        LaunchNote("Search", "Find previous sessions faster.", systemImage: "magnifyingglass")
    }
}

There's also full-screen mode, style presets, custom accent colors, footer actions, and a
manual trigger if you don't want the automatic behavior.

.launchNotes(presentation: .fullScreen, style: .prominent) {
    LaunchNote("New Stats", "Cleaner progress charts.", systemImage: "chart.line.uptrend.xyaxis")
}

Package is at https://github.com/pol-cova/LaunchNotes. Still early — feedback and PRs welcome.

The 5 MB Homework Limit That Turned Me Into an App-Builder

Paul Contreras — Fri, 01 Aug 2025 22:13:33 +0000

This semester I snapped a neat, high-res photo of my handwritten math assignment and went to upload it to my university platform.

Error: “File must be under 5 MB.”
I tried again with a different angle—same error. Then the portal complained about the HEIC format my iPhone uses by default.

What I tried next

Google results sent me to web compressors that wanted my personal photos on their servers (nope).
The first “free” iOS app threw three ads at me before I could pick a file.
A second app asked for $4.99 per month, just to shrink a picture!

I ended up opening Preview on my Mac, exporting, tweaking quality sliders, re-sending to my phone, and finally hitting “Submit” with seconds to spare. The whole thing took longer than writing the homework.

That night I wrote Crunch, an offline photo compressor that fixes the exact pain I felt.

What Crunch does now

Shrinks JPEG, HEIC, PNG images by up to 70 %, totally on-device (no uploads)
Converts formats so HEIC becomes JPG or PDF in one tap
Cleans out location + EXIF data before you share a file
Free: 10 photos a day. Pro: one-time $3.99—no subscriptions, ever

Try Crunch for iOS now: Crunch on AppStore

Follow me on x where I’m sharing progress, mistakes, your feedback will shape the next update—features, pricing, UX, anything.
@3nginuity