claudeers.
// Productivity

desk-buddy

Lump: a little desk buddy on an ESP32-S3 glass prism display that shows what your Claude sessions are up to. Built with Claude Code.

// Productivity[ cli ][ api ][ desktop ][ web ][ claude ]#claude#3d-printing#desk-buddy#esp32#productivity◷ MIT$open-sourceupdated 5 days ago

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up desk-buddy (git-clone project) into my current project.
Found on https://claudeers.com/desk-buddy
Repo: https://github.com/joebentham/desk-buddy
Homepage/docs: —
Detected install method: git-clone → git clone https://github.com/joebentham/desk-buddy
Category: productivity. Platforms: cli, api, desktop, web.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
unknown; community-verified: false. Confirm the source before running anything.
// or clone
git clone https://github.com/joebentham/desk-buddy

// compatibility

Platformscli, api, desktop, web
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageHTML

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

Lump, a desk buddy for Claude

Lump, an orange blob with a curly cowlick, dancing in sunglasses under a disco ball inside the glass cube display

Lump is a little blob who lives in a tiny glass prism display on your desk and shows you what your Claude sessions are up to, so you can look away from the screen while Claude works.

  • Working while Claude Code is busy, waving for attention when a session needs you (a permission prompt, a question, a plan to approve), and celebrating when it's done.
  • Corner counters show how many sessions are working, waiting on you, or finished and unread.
  • His colour warms from tangerine to red as you get close to your Claude usage limits.
  • Tap the glass and he plays one of a dozen gags: electric shock, ring of fire, wolf howl, banana peel, cartoon bomb and more.
  • Optional extras: turns blue before calendar meetings, holds up a letter when a Slack VIP messages you, a tiny ocarina voice and sound effects for the gags, sleeps at night, and runs over Wi-Fi with over-the-air updates.

Lump was built with Claude Code, drawings included: Claude draws every frame in code, in a scratchy hand-drawn style, in one web page (design/lump.html), and a script bakes it into a file the ESP32 plays back at 24 fps.

What you need

  • The display: Waveshare / SpotPear ESP32-S3-LCD-1.3 "prism" (ESP32-S3R8, 16 MB flash, 8 MB PSRAM, 240×240 ST7789 behind a glass cube, motion sensor for taps). Lump was built on this AliExpress listing, colour option ESP32-S3-LCD-1.3-C (about $20). Keep its stock case: the mount is sized for it.
  • A USB-C data cable for the first flash. After Wi-Fi setup he only needs power.
  • A Mac. The bridge that connects Claude to Lump is macOS-only (launchd, a small Swift helper, afplay). The firmware itself doesn't care.
  • Claude Code, plus optionally the Claude desktop app (for Chat and Cowork states).
  • PlatformIO (brew install platformio), Python 3, and the Xcode command line tools (xcode-select --install).
  • Optional: a 3D printer for the monitor mount, which holds him on the back of your monitor, peeking over the top.

Setup

git clone https://github.com/joebentham/desk-buddy.git
cd desk-buddy

1. Flash the board. Plug it in with a data cable, then:

tools/flash.sh

This builds the firmware and writes it plus Lump's drawings (~11 MB; the drawings take about 5 minutes). It uses a paced esptool upload because macOS drops bytes from big bursts to this board's USB-serial chip, so plain pio run -t upload fails.

2. Install the bridge. A small Python service that listens to Claude and drives Lump, plus a helper that reads the Claude app's window (Chat and Cowork have no hooks). Both run as login items.

tools/install_bridge.sh

When macOS asks, allow deskbuddy-appwatch under System Settings → Privacy & Security → Accessibility. Everything it installs lives in ~/.desk-buddy.

3. Hook up Claude Code. Adds small async hooks to ~/.claude/settings.json that tell the bridge what each session is doing, and a status line that feeds him your usage limits. It backs up your settings first and keeps any hooks you already have.

python3 tools/install_hooks.py

Start a Claude Code session and Lump should wake up.

4. Optional: Wi-Fi. With the cable still plugged in (2.4 GHz networks only):

~/.desk-buddy/venv/bin/python tools/wifi_setup.py

Your Wi-Fi password goes straight into the board over USB and is never saved on the Mac. After this he joins your network as lump.local, keeps time from the internet, and can live on any USB charger, such as a monitor's power-only port. Updates then go over the air:

python3 tools/ota.py

Optional extras

Put these in ~/.desk-buddy/config.json. The bridge re-reads it, so no restart is needed.

KeyWhat it does
calendar_icsYour calendar's private iCal link. He fades to blue over the 10 minutes before a meeting and plays a "meeting time" alert.
my_emailWith calendar_ics: skip meetings you've declined.
slack_tokenA Slack user token (xoxp-…) from your own private Slack app with read-only scopes im:read im:history mpim:read mpim:history users:read search:read. DMs and @-mentions send a paper plane round him. The token is never logged.
slack_vipsNames as Slack shows them. An unread DM from one of them makes him hold up a letter until you've read it.

Sounds: ~/.desk-buddy/sounds.json picks which moments make a noise ("enabled": false mutes him). A second Claude Code config (such as ~/.claude-work) can drive him too: run python3 tools/install_hooks.py --config-dir ~/.claude-work.

Lump on your Mac (for when you're away from the desk)

A little Lump for your screen that mirrors the desk one. On a MacBook with a notch he sits in a small black wing beside the camera; otherwise he's a menu bar item. There's no pop-out and no text. He's just a reminder of what the desk Lump is doing.

python3 tools/lumpbar/bake.py      # shrink his drawings (needs Google Chrome; re-run after editing lump.html)
zsh tools/lumpbar/build.sh         # builds ~/Applications/Lump.app and starts it

The Mac can't tell how far away you are, so it uses your monitor as a stand-in. While your desk monitor is plugged in and the desk Lump is online, you're "at your desk" and the Mac one hides. Right-click him to:

  • pick My Desk Monitor: the screen the desk Lump sits by (the default is any external display), or
  • show him All the Time (handy if you don't use a monitor, or if the desk Lump is by your laptop).

Can't see him? Open Lump (Spotlight works) and he appears with that menu open, even at your desk. Once you close it he hides again if you're at your desk. The same goes for the very first launch. To start him at login, add Lump.app under System Settings › General › Login Items.

Make him your own

All of Lump is drawn in code in design/lump.html: his body, faces, moods, transitions and every tap gag. To preview and edit:

python3 tools/export_frames.py 8767

Open http://localhost:8767/lump.html#gags in a browser. The page reloads when you save, and the "Tap gags" gallery lets you pause and step through frames. When you're happy, run the EXPORT_JS snippet from tools/export_frames.py in the page's console. It bakes every frame into firmware/data/lump.bin, then python3 tools/ota.py --art (Wi-Fi) or tools/flash.sh (cable) puts it on the board.

Two tips: keep repeating effects on a 12-tick beat, so frames are shared between moods and the file stays small (it has a 12 MB budget). Keep faces simple: dot eyes, small mouths, and let props sell the gag.

How it fits together

Claude Code hooks ─┐
status line ───────┤                           USB serial or Wi-Fi
Claude app window ─┼─▶ bridge (Mac, :47823) ─────────────────────▶ ESP32 prism: Lump
calendar / Slack ──┘   one mood for all sessions                   plays baked frames, senses taps
PathWhat's there
firmware/src/main.cppThe frame player: moods, transitions, taps, offline mode, Wi-Fi, OTA. The serial protocol is documented at the top.
firmware/data/lump.binLump's baked frames (written to their own flash partition)
design/lump.htmlLump himself: every drawing and animation
tools/buddy_bridge.pyThe bridge: Claude hooks, app state, usage, calendar, Slack, sounds → one mood
tools/appwatch/Swift helper that reads Chat/Cowork state from the Claude app's accessibility tree
tools/lumpbar/Lump on your Mac: frame baker (bake.py) and the notch/menu bar app (main.swift)
tools/flash.sh, tools/ota.py, tools/wifi_setup.pyGetting firmware and drawings onto the board
enclosure/OpenSCAD source for the adjustable monitor mount, with ready-to-print STLs
tests/Bridge tests (no board needed): ~/.desk-buddy/venv/bin/python -m unittest discover -s tests

The bridge's debug endpoints help when you're poking at him: curl 127.0.0.1:47823/status, or curl -X POST --data "e tap" 127.0.0.1:47823/cmd to send a raw command. To play an animation on demand (from a hotkey, a menu bar app or Shortcuts), curl -X POST --data disco 127.0.0.1:47823/play; curl 127.0.0.1:47823/play lists the names.

License

Code and 3D models: MIT. Lump himself (the character, his drawings, animations and sounds): CC BY-NC 4.0. Build one, remix him, share it; just don't sell him.

// faq

What is desk-buddy?

Lump: a little desk buddy on an ESP32-S3 glass prism display that shows what your Claude sessions are up to. Built with Claude Code.. It is open-source on GitHub.

Is desk-buddy free to use?

desk-buddy is open-source under the MIT license, so it is free to use.

What category does desk-buddy belong to?

desk-buddy is listed under productivity in the Claudeers registry of Claude-compatible tools.

6 views
★ 23 stars
unclaimed
updated 5 days ago

// embed badge

desk-buddy on Claudeers
[![Claudeers](https://claudeers.com/api/badge/desk-buddy.svg)](https://claudeers.com/desk-buddy)

// retro hit counter

desk-buddy hit counter
[![Hits](https://claudeers.com/api/counter/desk-buddy.svg)](https://claudeers.com/desk-buddy)

// reviews

// guestbook

0/500

// related in Productivity

🔓

Agent skills for Obsidian. Teach your agent to use Obsidian CLI and open formats including Markdown, Bases, JSON Canvas.

// productivitykepano/★ 52,609◷ MIT[ claude ]
🔓

Open source repository of plugins primarily intended for knowledge workers to use in Claude Cowork

// productivityanthropics/⟨Python⟩★ 34,871◷ Apache-2.0[ claude ]
🔓

Garry's Opinionated OpenClaw/Hermes Agent Brain

// productivitygarrytan/⟨TypeScript⟩★ 33,099◷ MIT[ claude ]
🔓

An open-source alternative to Claude Cowork (powered by opencode)

// productivitydifferent-ai/⟨TypeScript⟩★ 24,523◷ NOASSERTION[ claude ]
→ see how desk-buddy connects across the ecosystem