Peek for Carbons

This page is for the human at the Mac. Peek shows bubbles from your Silicons at the edges of your screen, speaks for them, and lets you answer with your voice, your keyboard or a click. Nothing here needs a terminal after the install.

Install#

curl -fsSL https://peek.teamofsilicons.com/install.sh | sh

You need macOS 26 or newer. The script installs Honeycomb if it is missing, the peek CLI, and Peek.app into ~/Applications, then starts it. Peek has no Dock icon; look for it in the menu bar.

The first time Peek starts, macOS may say a background item was added, or ask you to approve it. Open System Settings → General → Login Items & Extensions and allow Peek. Peek's helper (peekd) runs in the background so Silicons can reach you even when no bubble is open. If you do not approve it, Peek still works while the app is running, and shows a one-time notice.

The eight positions#

Each Silicon owns exactly one position. Position 1 is top centre; the rest follow clockwise.

A shortcut exists only while a Silicon holds that position. The default modifier is ctrl+cmd, because plain cmd+1…8 already switches tabs in most browsers and editors. You can change it in Settings → General → Keyboard → Hotkeys: cmd, ctrl+cmd, opt+cmd, shift+cmd, ctrl+opt+cmd or ctrl+opt. The rest of this page writes the shortcut as ⌃⌘N (N is the Silicon's position); read it with your own modifier if you changed it.

What a bubble shows#

A bubble slides in from the edge of the screen with a small bounce, the way macOS panels do. It has no background, frame or backdrop of its own: only the pieces below float directly over whatever is already on your screen. It has:

• The visual: a circle the Silicon draws itself, in JavaScript. It reacts to the speech, your voice, the pointer and clicks. Clicking it does nothing except let the drawing animate.
• The information arc: text pills and bordered images laid out along a curve that faces the centre of your screen, up to three items. Longer text wraps into a narrow, taller column instead of one wide line, so the bubble stays compact.
• The question arc: when the Silicon asks something, the question curves above the answer controls.
• Mic and keyboard buttons, next to the visual on the side facing the screen edge, when an answer or message is possible.
• A down-arrow to close the bubble.

Peek samples what is behind each bubble (your desktop picture by default) and picks white or black shading so the text stays readable on light and dark backgrounds.

Reading and touching a bubble#

• What you can press looks pressable. Options, buttons, sliders, the text field, the mic, keyboard and down-arrow buttons, and text you can expand sit slightly lifted, with brighter glass and a fine edge, and the pointer becomes a hand over them. Plain labels (a year, a caption that fits, a notice) stay flat. Hover makes the difference obvious.
• Everything you can press is springy. On hover it lifts and grows a little with a bounce; pressing squashes it, and it springs back when you let go. Plain labels never move.
• Cut-off text shows in full on hover. Any text that ends in "…" (a pill, a caption, an option label, the question) shows its complete text in a glass overlay beside it as soon as you hover, with no delay.
• Long text opens in place. Click a long text that does not fit and it opens right where it is, in a small glass popup that bounces open and shows all of it. Click it again, click anywhere else or press Esc to close it.
• Long text grows away from the edge. At every one of the eight positions the narrow text column grows toward the middle of the screen, never off it, and leans with the arc only as much as stays easy to read.

When the Silicon speaks and shows something, the bubble slides back 1.5 seconds after the speech ends. A show without speech stays for a few seconds, longer for more text. An ask stays until you answer or dismiss it. If the speech cannot be played (for example, its language has no voice), the words appear as a pill instead.

Answer a question#

Sliders move smoothly. While you drag, a handle follows your pointer continuously instead of jumping from step to step, and the value above it shows the step it will land on. When you let go it springs to the nearest step. If the slider has a sensible number of steps, each one is marked with a small dot along the track.

With the keyboard. After ⌃⌘N the bubble takes the keyboard: the arrow keys move the highlight between options or nudge a slider, Space toggles a multiple-choice option, and Return answers. Typing a label, a number, "first" or "2" also works; if it matches no option the bubble says "Didn't match an option — tap one or type".

By voice. Click the mic button, or press ⌃⌘N and then \. The bubble shows a live waveform of what it hears. Stop with a click, \ or Return.

• For a text question, the bubble slides away as soon as you stop. Your words are transcribed once and sent as the answer.
• For a choice, slider or range question, the bubble says it is transcribing for a moment, then picks the option you named. If nothing matches, it stays open and says "Didn't match an option — tap one or type". Nothing is sent until an option matches. If transcription takes longer than 8 seconds, the question comes back with "Still transcribing — tap an option or type"; a late match still answers it.
• If the recording was silent, nothing is uploaded, and the bubble stays open with "Didn't hear anything — try again or type".
• If transcription fails, the question comes back with "Couldn't transcribe — type instead". Peek never sends an empty answer.

The first time you use the mic, macOS asks for microphone permission. Peek records only while you are answering. Your recording is sent once to Deepgram to turn it into text (directly, or relayed by peek's backend, which never stores or logs it), and deleted from your Mac once the answer is delivered. See Privacy.

Talk to a Silicon first#

You do not have to wait for a question. Press ⌃⌘N for a Silicon's position: an empty bubble opens with the hint \ to talk · type to write · esc to close. Press \ to speak or start typing, and press Return. The Silicon receives your words as a peek.message.received event, the same way it receives answers. Use this for "remind me about this at 5" or "stop the music". The empty bubble slides back after 12 seconds if you do nothing.

⌃⌘N on a bubble that is already showing brings it forward and pauses its countdown. If a bubble is waiting for that position (because peeks are paused, or it is a hidden test bubble), ⌃⌘N shows it.

Dismiss and cancel#

While a question is waiting, the same Silicon's later bubbles queue behind it, so questions never pile up on screen.

The menu bar and Settings#

The menu bar item lists the eight positions with their Silicons and shortcuts, and offers Pause all peeks (bubbles wait in the helper until you resume; nothing is lost), Simulation…, Settings… (⌘,) and Quit Peek (⌘Q).

Settings has five tabs:

Simulation (menu bar → Simulation…, or General → Open Simulation…) lets you try every combination (position, speak, show, each ask type, mode, appearance, backdrop) with built-in samples. It uses no network, no IAM, no Ting and no Deepgram, and its bubbles are labelled SIMULATION. A voice answer in Simulation is recorded but never transcribed.

Test bubbles come from a Silicon running against a testing environment. They carry a TEST · <environment name> pill and a dashed ring, and show "Sent to test silicon" after you answer. A real bubble always takes priority over a test bubble at the same position.

Ask your Silicon to use peek#

If your Silicon does not use peek yet, paste this to it (or to whoever maintains it):

Add peek to silicon.apps in your silicon.yaml, reconnect, then run
`peek register side <a free position 1-8>` and `peek register drawing ./logo.js`.
Use `peek send --speak "…" --ask '{…}'` for quick yes/no questions and
`peek send --speak "…" --show '{…}'` for glanceable updates.
Answers arrive as Ting events of type peek.ask.answered. Docs: peek docs silicon

Updates and uninstall#

Peek updates itself. The CLI is updated by Honeycomb; the app and its helper update from the newest build any Silicon has installed, never downgrade, and wait until no bubble, recording or question is on screen.

To remove Peek.app, its login item and its helper:

peek app uninstall

honeycomb uninstall 'peek' removes only the CLI; it does not remove the app. Local history and caches live in ~/Library/Application Support/Peek/ and ~/Library/Caches/Peek/; delete those folders to remove them.

Next#

• Privacy: what leaves your Mac.
• Troubleshooting: no bubble, no sound, the mic, shortcuts.