A sunlit, empty lecture hall with a blackboard

hoff-harness

Name: hoff-harness
Author: rorosaga

A second cursor for your coding agent. It glides to things on your Mac, explains
them in a speech bubble, walks you through tasks step by step, or does them while
you watch. And you can point back: hold ⌃⌥, circle something, and ask
"what is this?". Your agent gets exactly what you marked.

hoff.rorosaga.com: see it in action.

macOS only. Works with Claude Code, Cursor, the Claude desktop app (MCP), Codex,
Antigravity, OpenCode, Pi, Hermes and other agents that can run shell commands.

Install

Paste this into Claude Code, Cursor, Codex or any agent that runs commands:

Install hoff-harness (https://github.com/rorosaga/hoff-harness), a second cursor for coding agents on macOS. If you are Claude Code: run `claude plugin marketplace add rorosaga/hoff-harness` and `claude plugin install hoff-harness@hoff-harness`; the script is then `~/.claude/plugins/cache/hoff-harness/hoff-harness/*/skills/hoff-harness/scripts/hoff-harness`. If you are another agent (Cursor, Codex, Antigravity...): run `git clone https://github.com/rorosaga/hoff-harness ~/code/hoff-harness`, `mkdir -p ~/.agents/skills` and `ln -sfn ~/code/hoff-harness/skills/hoff-harness ~/.agents/skills/hoff-harness` (if you load skills from another folder, link it there too), then read its SKILL.md; the script is `~/code/hoff-harness/skills/hoff-harness/scripts/hoff-harness`. Make sure `uv` is installed. Run the script with `doctor`, explain any missing macOS permission and ask before requesting it. In Claude Code, offer the clip counter for my status line with `statusline install`. If browser-harness is installed, run it with `browser` to connect Chrome. Finally point at something in Finder: run it with `point --app Finder --find "Go" --role MenuBarItem --activate --say "Hi, I'm your guide cursor."`. If you can't run commands (the Claude app's chat, for example), tell me to paste this into Claude Code or the Claude app's Code tab instead.

Other agents and manual setup: install.md.

What it can do

	You say	What happens
Show me	"Where's the export button in Figma?"	The cursor glides to it, rings it, and a bubble explains it.
Walk me through	"Walk me through adding a GitHub Action."	One step at a time; each step waits for your click on the right thing.
Do it for me	"Turn on dark mode, and show me as you go."	The bubble says what it's about to do, the cursor points, then it clicks or types while you watch.
Explain my screen	"What are all these Xcode panels?"	A short cursor tour of the parts, with the full answer in chat.
Point back	Hold ⌃⌥, circle an error: "why is this failing?"	Your agent gets the app, the window, the text and elements under your mark, and a crop.
Many clips	Mark three things: "compare these."	Each mark is numbered; Claude Code's status line shows `📎 3 screen clips ready`.
Web pages	Circle part of a page: "summarize this", "fill this in for me"	In Chrome it works with the page itself: exact elements, links, text. It clicks and types through Chrome without taking your mouse.

Keys

Keys	What they do
hold ⌃⌥ and click	Point at something. A pulse shows where.
hold ⌃⌥ and drag	Circle, underline or arrow something.
⌃⌥ esc	Clear your marks and put the cursor away. During "do it for me", it also tells the agent to stop.

Send your message and the marks go with it. Marks fade from the screen after a
few seconds, but stay attached for 15 minutes. To change the keys, ask your
agent ("use cmd+shift for marking"); they live in
~/.config/hoff-harness/config.json.

Works with

Agent	Point, guide, do	Marks attach to your message	Tested
Claude Code (terminal, IDEs)	✓	✓ automatically (plugin hooks)	✓
Codex	✓ finds the skill in `~/.agents/skills`	the agent runs `hoff-harness context`	✓ installed itself from the prompt above
Cursor	✓ finds the skill in `~/.agents/skills` or `~/.claude/skills`	the agent runs `hoff-harness context`	✓ (allow it to run outside its sandbox)
Claude desktop app, Code tab	✓ it is Claude Code	✓	finds and runs the skill; needs Accessibility and Screen Recording for Claude
Claude desktop app, chat	✓ through `hoff-harness mcp` (install.md)	the `marks` tool	connects; needs Accessibility and Screen Recording for uv
Antigravity, OpenCode, Pi, Hermes	✓ through SKILL.md	the agent runs `hoff-harness context`	not yet
ChatGPT	only remote MCP servers		not possible yet

Requirements

macOS 14 or later. It uses the macOS accessibility API and AppKit
windows, so it doesn't run on Linux or Windows.
uv. The first run installs PyObjC into uv's
cache, which takes a few seconds.
Accessibility and Screen Recording permission for the app your agent
runs in: your terminal, Cursor, or the Claude app for its Code tab (System
Settings > Privacy & Security). hoff-harness doctor checks both,
hoff-harness permissions opens the right pages, and Claude Code tells you
at the start of a session when one is missing. Restart the app after.
Optional: browser-harness
for web pages in Chrome and other Chromium browsers.

How it works

  agent's shell                          overlay (starts with your agent session)
       │                                          │
  hoff-harness point ...  ── local socket ──▶  glass cursor, bubble, rings, your marks
       │                                          │  click-through windows above everything
  macOS accessibility tree, screenshots           │
  browser-harness for Chrome pages         hold ⌃⌥: it takes the mouse and saves
                                           each mark with what is under it
  Claude Code hooks: start the overlay with a session, attach marks to your next message

It never takes focus. Clicks pass through it, except while you hold ⌃⌥.
Your real pointer moves only for a click on something that has no
accessibility action, and it goes straight back.
Everything stays on your Mac. Marks and screenshots live in
~/Library/Caches/hoff-harness, are only sent to your agent with your message,
and are deleted after a day.

Why "hoff"

hoff is short for hands-off. The idea mainly came from Hoff, a hackathon
project Ricky and I
built together and demoed at YC at the Browser Use hackathon.

Credits

The pointer's shape and spring motion are from
macos-harness (MIT).
Web pages go through
browser-harness (MIT).
Inspired by Clicky and HeyClicky.

Details and licences: THIRD_PARTY.md. Contributing:
CONTRIBUTING.md.

MIT