Aki

Show your AI agent exactly what to fix.

Point at anything on your Mac — a button, a line in the terminal, a whole area — say what should change,
and Claude Code, Codex or your agent of choice gets it in the right session. No pasting screenshots, no ⌘Tab, no "not that one".

Website · Download · How it works · Shortcuts · X

---

Why

Telling an agent what to change is the slow part: take a screenshot, paste it, describe where to look, switch to the right terminal, hope it finds the element. Aki turns that into point, say it, send. The agent receives the exact element (selector, text, HTML, even the React source file), your note, and a crop only when a picture actually helps — so it spends tokens on the fix, not on guessing.

The other question while several agents run is how am I doing this week? The same sidebar answers it: how much of Claude's and Codex's weekly limit is gone, today's tokens and what they'd cost, and whether you're ahead of the pace — without another app.

How it works

1 · Point	2 · Say it	3 · Send
⇧⌘A, then click an element, drag an area or hold ⌥ for lines of text.	Write what should change. Queue as many marks as you like; edit or drop any of them.	⌘⏎. Aki types the request into that session's terminal; the agent reads it over MCP and marks each one done.

Mark an area. Drag over anything — a chart, a broken layout, a whole panel.	Any app. Finder, Figma, Xcode, a terminal error. If it's on screen, it can be marked.
Queue & send. Marks wait in a queue; one send hands them all to the right session.	What your agent reads. The page, the element, your note and a crop. It fixes each one and resolves it.

Want to try it without installing? The website lets you mark the page itself.

Features

🎯 Exact elements in Chrome, no extension	Aki asks the page what's under the pointer: the element, a unique CSS selector, its text and HTML, the React component's source in dev builds. Works in Chrome, Brave, Edge, Arc and Vivaldi.
⌨️ Walk the screen with the keyboard	↑ ↓ ← → move to the next thing above, below or beside, about the same size; ⇧ with the arrows adds the next one (the opposite arrow takes it back out); ⌘↑ takes what holds it, ⌘↓ goes back inside — even a CSS ::after arrow; ⏎ marks it.
🖥️ Any app	Elsewhere it uses macOS Accessibility: buttons, rows, tabs, the browser's own bar, floating panels. Areas and points work everywhere.
📝 Text first, pictures when they help	Each mark carries the text it covers; a small crop goes along only when what you marked is visual. You can switch either on or off.
🧭 The right terminal, by itself	A page on localhost:3000 belongs to a worktree; Aki finds the session running it. Otherwise it goes to the session you picked.
⏱️ Your agent wakes up	Seconds after you stop, Aki types the request into the session's tab — and never glues it to something you were typing there.
🟠 One ring per session	A sidebar on the screen edge shows every Claude Code / Codex session, grouped by project, with its state, context used, your 5-hour and weekly limits, and what's waiting.
📊 Your week at a glance	A ring each for Claude and Codex with the share of the weekly limit used and today's tokens and cost at API prices. Hover for the 5-hour window, when each renews, the pace, today's share of the week, the last 7 days and the projects that used most. Want only that? Settings → Show in the sidebar → Only limits. aki usage prints it in the terminal.
📬 Sent, then done	A countdown on the session's ring until the request goes in; a ✓ when the agent has resolved every mark.
🕘 History	⇧⌘H lists every mark with its size; move marks between sessions; done marks clean themselves up.
⚙️ Yours to set	Light or dark, Aki's red or your Mac's accent, four sizes, shortcuts you choose, nine languages (English, Português, Español, Français, Deutsch, 日本語, 中文, 한국어, Italiano).
🔄 Updates by itself	Signed updates with an optional beta channel.

Works with

Agents: Claude Code · Codex · Gemini CLI · Grok CLI · opencode · Cursor Agent — anything that can run a command or speak MCP.
Terminals: Orca (Aki types straight into the session's tab), plus any terminal for reading marks.
Launchers: Raycast, Alfred, Shortcuts and Spotlight through aki:// links.

Install

One line (about a minute — downloads the latest version, puts it in Applications and opens it):

curl -fsSL https://aki-updates.vercel.app/aki-install.sh | sh

Or by hand:

1. Download the latest Aki-x.y.z.dmg from Releases (or the website) and drag Aki to Applications.
2. First launch only: macOS asks to confirm an app from the internet — System Settings → Privacy & Security → Open Anyway. (The one-line install skips this.) Updates install without asking again.
3. Aki opens Get started: each permission below, why it's needed, and a button that takes you straight there. Each turns green when it's given.

Apple Silicon, macOS 14 or later.

Permissions, and why

To…	Aki needs	Why
See what you mark (crop it, read its text)	Screen Recording	macOS asks this of any app that looks at the screen. Nothing is recorded; marks stay on your Mac until you send them to your agent.
Point at buttons, rows and tabs in any app	Accessibility	It's how Mac apps describe their buttons and lists to other apps.
Hand your marks to Claude Code or Codex	Aki's MCP server in the agent (Settings → Agents → Connect)	It's how agents get new tools. Sessions already open see it after a restart.
Pick the exact element on a web page	In the browser: View → Developer → Allow JavaScript from Apple Events, then allow Aki to control it	Aki asks the page itself which element is under the pointer — no extension.

Anonymous notices (telemetry)

Aki sends no usage data and no crash reports. The one exception is two small, anonymous notices, so the maker knows how many people use Aki and on which version (what to fix first, when an old version can be retired):

When	What is sent
Aki is installed (about two minutes after the first launch)	Aki's version, macOS version, chip, preferred language
Aki updates to a new version	the same, plus the version it updated from

The download host (aki-updates.vercel.app, on Vercel) adds the approximate state or region and country (never the city). No account, no identifier, no IP address kept, nothing you mark or type. They're on by default and explained in Get started; turn them off there or in Settings → General → Privacy — when off, nothing is sent. The code is short and readable: Sources/Aki/App/InstallPing.swift. Details in the privacy notice.

Where Aki lives

Aki is always on: the bar at the edge of your screen and the pin in the menu bar (mark, history, sidebar, settings). It stays out of the Dock and ⌘Tab, and shows there while Settings or History is open. Search "Aki" in Spotlight to open Settings; want it in the Dock? Settings → General → App icon.

Shortcuts

Keys
⇧⌘A	Mark the screen
⇧⌘H	History
⏎	Add the mark to the queue
⌘⏎	Send (with a queue: the whole queue — the card also offers Only this one)
⇥	Next session
↑ ↓ ← →	Move to the next thing on screen (above, below, beside)
⇧ + arrows	Add the next one to what's outlined (the opposite arrow takes it back out)
⌘↑ ⌘↓	Bigger (what holds it) · smaller (back inside)
⇧ held	Use the page below as is (click, hover, menus); let go to mark again
⌘Z	Undo the last mark
Space while dragging	Move the whole area
⏎	Mark what's outlined
⌥	Lines of text instead of elements
esc	Leave (the queue is kept)

Both global shortcuts can be changed in Settings → Shortcuts.

Raycast, Alfred, Spotlight

Aki answers four links: aki://mark, aki://history, aki://settings, aki://sidebar.

• Raycast: Settings → Shortcuts → Add to Raycast writes four script commands to ~/.aki/raycast; add that folder once in Raycast (Extensions → + → Add Script Directory). Each command can get its own hotkey. The same scripts live in integrations/raycast.
• Alfred or any launcher: open the link.
• Spotlight: make a Shortcut that opens aki://mark; it shows up in Spotlight by its name.

How Aki finds the right session

flowchart LR
    A["You mark something<br/>(⇧⌘A)"] --> B{"A page on<br/>localhost?"}
    B -- yes --> C["Port → process (lsof)<br/>→ its folder → worktree"]
    B -- no --> D["The session you picked<br/>in the sidebar"]
    C --> E["Open sessions<br/>~/.claude/sessions · running codex"]
    D --> E
    E --> F["Mark saved in ~/.aki<br/>for that session"]
    F --> G["Aki types the request<br/>into its Orca tab"]
    G --> H["Agent reads it<br/>MCP read_annotations · aki list"]
    H --> I["Fixes it, marks it done<br/>aki done &lt;id&gt;"]

Sessions come from Claude Code's own registry (~/.claude/sessions) and from the agent processes running on your Mac, matched to a worktree by their folder. Each ring in the sidebar is one of them.

What your agent reads

Through the MCP tools (read_annotations, wait_for_annotations, get_annotation_image, resolve_annotation) or the aki command:

aki list        # marks for this folder / session
aki wait        # wait until new marks arrive
aki done <id>   # mark one as done
aki terminals   # agent sessions Aki sees

## aki_1791130541219_0a9c912d  (2026-10-04 16:15)
page:     http://localhost:3000/
app:      Google Chrome — Halo Pro
comment:  Center it and make it huge
kind:     element
element:  <h1> section.hero > h1.hero-title
text:     Halo Pro
file:     src/components/Hero.tsx:42

Privacy

Everything you mark stays on your Mac, in ~/.aki. Aki's local server listens on 127.0.0.1 only and checks every request's origin. The usage rings read only the token counts in Claude Code's and Codex's own logs on your Mac, never the conversations. Nothing is sent anywhere except the update check and the optional, anonymous notices described in Anonymous notices.

Build from source

Needs the Xcode Command Line Tools (Swift 6) — no Xcode project.

scripts/dev-cert.sh   # once: a local signing identity, so macOS keeps permissions across builds
scripts/install.sh    # build, sign, put in /Applications and open
swift run AkiChecks   # checks
python3 scripts/check-translations.py   # every language complete, no repeated text

How it's built: docs/ARCHITECTURE.md · how to help: CONTRIBUTING.md · what changed: CHANGELOG.md · security reports: SECURITY.md.

FAQ

Does it need a browser extension? No. Chrome-based browsers answer through Apple Events (turn on View → Developer → Allow JavaScript from Apple Events once).

Does it send screenshots to my agent? Only when you mark something visual, and you can switch it off per mark. Text is the default: cheaper and more precise.

Which terminal do I need? Any, to read marks. Aki types the request into the session by itself in Orca; elsewhere the agent picks marks up with aki wait or when you ask.

Intel Macs? Not yet.

Credits

Aki builds on ideas and code from Codenotch, Vibe Annotations (MIT version), Annotate, react-grab and @medv/finder, and updates with Sparkle. Their notices are in THIRD_PARTY_NOTICES.

License

Functional Source License 1.1 (FSL-1.1-ALv2) © 2026 Murilo Prataviera. Use it, read it, change it and send improvements — anything except building a product that competes with Aki. Each version becomes Apache-2.0 two years after its release. Made by Murilo Prataviera · X · Instagram.