HeyMate

Guide · 9 min read

How to use HeyMate as a developer, designer, or learner.

HeyMate is a free, open-source AI buddy for learning desktop apps and websites, currently available for macOS. It lives in your Mac's notch. Hold ⌃ ⌥, ask about anything on your screen, and it answers out loud while its cursor points at what it means. It can also hand real work to Claude Code, Codex, or OpenCode, on the subscription you already pay for.

That is the whole pitch. This guide is about what to do with it on a normal working day, whether you write code, push pixels, or are trying to learn something you know nothing about yet.

The one habit that matters

Stop copying things into a chat box. Keep working, hold the hotkey, and ask the question out loud while the thing is on your screen. HeyMate captures relevant screen context during interactions that need it and sends it with your words to the provider you choose. A walkthrough can capture again between steps. Some CLI integrations write temporary image files; see the privacy details for storage and cleanup. Text-only questions do not need a screenshot.

Everything below is a variation on that habit. Ask first, and only then decide whether the answer should turn into work.

Set up in five minutes

Need the full sign-in steps? Follow connecting Claude or ChatGPT through Codex. Then try the step-by-step screen guidance walkthrough.

  1. Install: curl -fsSL https://sayheymate.vercel.app/install.sh | bash
  2. Grant Microphone, Accessibility, and Screen Recording. Here is why each one is needed.
  3. When HeyMate asks which AI you already pay for, pick Claude or ChatGPT and click sign in. It installs the official CLI if needed and finishes in your browser. Already signed in to claude, codex, or opencode? It uses that.
  4. Hold ⌃ ⌥ and say hey.

For developers

1. Ask about the thing you are staring at

A stack trace in the terminal, a failing CI page, an unfamiliar function in a PR. Hold the hotkey and ask:

  • "What is this error actually telling me?"
  • "Why is this test flaky, based on what is on screen?"
  • "Walk me through what this function does, top to bottom."

You get a spoken answer and a cursor pointing at the exact line, so you never lose your place in the editor. There is also a built-in code explainer skill for longer walkthroughs.

2. Hand off work behind an approval gate

Say "HeyMate agent, add dark mode to this project" or "fix the failing auth test". HeyMate does not just start. The flow is always the same:

  1. The selected CLI reads the task and the workspace with writes disabled and drafts a plan.
  2. HeyMate shows you the plan and waits.
  3. You approve. HeyMate takes an undo snapshot, resumes the same CLI session, and lets it write.

Approved work runs in a helper process, so it keeps going if you quit the app. When it finishes you get a completion receipt, and if you do not like the result, undo restores the snapshot. For work you want to watch, take over in Terminal.

Practical rules that make this work well:

  • Give one outcome per job. "Add a retry to the upload client and a test for it" beats "improve the upload code".
  • Read the plan. The plan is the cheap place to catch a wrong assumption.
  • Use Claude Code or Codex when the job must build or run tests. OpenCode jobs can edit files but cannot run shell commands.
  • Point jobs at an existing project folder when the work belongs in your repo. Otherwise HeyMate makes a sandbox folder under ~/Projects/heymate.

3. Give each part of your project its own mate

A mate is a lasting helper with a name, a job, a personality, its own memory, and a workspace folder. You can create one by saying "make me a mate that reviews my Swift diffs", or from the Mates window where you can also set its brain and folder. Mates are good when a role repeats:

  • Release captain. Checks whether the last CI release finished, whether the download asset exists, and reminds you of the manual step you always forget.
  • Reviewer. Pointed at your repo, it reads before it proposes, and its memory remembers the conventions you keep correcting.
  • Docs writer. Drafts changelog notes and README changes, and never publishes them.

Because each mate keeps its own chat, memory, and folder, a question to the reviewer does not pollute your release notes.

4. Put the boring checks on a routine

A routine runs a mate's task daily at a time you choose, or every N hours, and the result lands in that mate's chat. Good first routines are read-only: "every morning, summarize new issues and failing builds" or "every 6 hours, check the release workflow and tell me only if it is red". Missed runs collapse into one, so you never come back to a backlog, and a routine pauses itself after repeated failures.

5. Let Standing Orders propose, never start

Standing Orders are rules you give HeyMate such as "when a build fails on screen, offer to investigate". HeyMate proposes work when a rule matches, but it never starts anything unasked. You stay the approver.

6. Plug in the tools you already use

Connectors cover Apple Calendar, Reminders, Notes, Mail, Messages, and Shortcuts, plus local CLIs such as gh, git, docker, kubectl, vercel, supabase, and stripe using your own logins, any MCP server, and 1,400+ toolkits through Composio with your own free key. Reads run quietly. Anything that sends, deletes, or pays asks first.

For designers

1. Get a critique without leaving the canvas

Open your Figma frame or a live page and ask "what would you change about the hierarchy here?" or "is this contrast readable?". The built-in UI design critique skill gives structured feedback, and the cursor points at the exact element it is talking about, which is faster than reading a paragraph of description.

2. Learn the tool while you use it

"Where do I set up auto layout on this frame?" "How do I make this a variant?" Because HeyMate sees the real screen and asks macOS for the real button position, it points at the control instead of describing where it probably is. The screen walkthrough skill steps through unfamiliar apps one click at a time.

3. Bridge to engineering

When a design needs to exist in code, describe the outcome and let an agent plan it: "build this card component to match the design on screen, using the tokens in this project". Read the plan, approve, and check the result in your browser. Keep a design QA mate pointed at the front-end folder with one instruction in its soul: flag anything that uses a color, size, or font outside the token file.

4. Keep the boring writing off your plate

Microcopy, alt text, release notes for a design system. Dictation puts your spoken words into the field you are typing in, and a writer mate can polish them with your voice guidelines in its memory.

For learning something new

1. Point at what confuses you

Reading a tutorial, a paper, a spreadsheet, or a settings screen you do not understand? Hold the hotkey and ask "explain this like I have never seen it before", then "what should I learn first?". It answers about the page in front of you, not a generic version of the topic.

2. Make a tutor mate

Create a mate whose job is teaching one subject: "ask what I already know, explain with one small example at a time, quiz me, and keep notes". Its memory and folder persist, so next week it remembers what you got wrong. A built-in study tutor skill covers the same pattern if you do not want a dedicated mate.

3. Learn by doing, with a safety net

Want to understand a new framework? Ask an agent to build a tiny example in a sandbox folder, read the plan so you learn what it intends, approve, then open the result and ask about each file. Nothing touches your real projects, and you can undo.

4. Put a review on a schedule

A daily routine like "at 8am, give me three questions on what I studied yesterday" turns one-off reading into something that sticks.

What HeyMate will not do

  • It will not write, send, click, or delete anything without your approval.
  • Screen guidance can capture relevant screen context, including fresh screenshots between walkthrough steps. Some integrations write temporary screenshots; interrupted cleanup can leave files behind. Enabled routines and approved jobs can run in the background. See the privacy details.
  • HeyMate adds no subscription fee and uses your own Claude, Codex, OpenCode, or configured API connection. Provider usage limits and optional API, voice, and connector charges still apply.
  • It is not a sandbox. Coding CLIs run as your macOS user, and plan mode limits writes, not reads. Read the permissions page and the privacy notes.

Common questions about HeyMate on Mac

Is HeyMate free, or do I need an AI subscription?

HeyMate is free and MIT licensed. Connect your existing Claude, ChatGPT (Codex), or OpenCode setup, or configure a supported API. Your AI provider's limits and charges still apply. Optional voice services and connectors may also charge separately.

Does HeyMate work on Intel Macs and Macs without a notch?

HeyMate supports Apple silicon and Intel Macs running macOS 14.2 or later. Macs without a notch use a top-center pill. The optional Apple Intelligence provider has separate hardware requirements and needs macOS 26 or later.

Can HeyMate see my screen and control Mac apps?

Screen guidance needs a vision-capable provider and the relevant macOS permissions. Ask about the current app with Control + Option. Computer control needs to be enabled and approved; click, type, or press Escape to take back control. Read the Mac permissions guide before enabling access.

Does HeyMate work completely offline?

That depends on the selected provider and feature. Cloud AI providers receive the questions and relevant context they process. The optional Apple Intelligence provider supports text-only questions on eligible Macs; it cannot see the screen. Local speech models can process speech on your Mac when available. See what stays local and what leaves your Mac.

Start small

Install it, ask one question about whatever is on your screen right now, and see whether the answer saved you a context switch. Then create one mate for the job you repeat most. That is enough to know if it fits.

Download free

Questions, bugs, or ideas? Open an issue or email umarsiddiqui3037+heymate@gmail.com.

Back to HeyMate