Amaru docs

Amaru is a native macOS app with three surfaces on the edges of your screen: the notch at the top, a side rail for AI usage, and a dock at the bottom. This page covers version 0.2.4.

Install

Amaru is shared as a ready-built app, not as source code. Download it, unzip it and drag it into Applications.

Download for macOS Version 0.2.4 · Apple silicon · 7.5 MB · macOS 14.6 or later

1. Open the zip in Downloads; Amaru appears next to it.
2. Drag Amaru into Applications.
3. Open it. This build is not notarized yet, so macOS may block it the first time. If it does, open System Settings › Privacy & Security, scroll to the message about Amaru, choose Open Anyway and then Open. You only do this once. On macOS 14 you can instead right-click Amaru and choose Open.
4. Amaru lives in the menu bar and the notch. It greets you, then the welcome guide lets you pick features.

macOS 14.6 or later on Apple silicon. The Liquid Glass look needs macOS 26; older systems get a solid fallback. To check the download, compare its SHA-256 with the one below:

shasum -a 256 ~/Downloads/Amaru-0.2.4-arm64.zip
3a115029e22e3ed7baf267505a3c1ed523a35c38541b20d0f515b4ed8615146f

Updating. Quit Amaru, then drop the new version into Applications and replace the old one. Your settings stay. Uninstalling. Quit Amaru and move it to the Trash; its settings are in your user folder under ~/Library if you want them gone too.

The bundle identifier is still local.gustra.Dock while the rename settles, so permissions you already granted carry over.

First run

The welcome guide opens on first launch: it asks what to call you, lets you pick features and walks through the setup of each. Amaru lives in the menu bar (the Peek icon): from there you can show the dock, open the notch, switch profiles, open Settings or quit. Nothing needs a permission to start; each feature asks when you turn it on.

Settings is a sidebar of groups you can fold: General, Appearance and Profiles; the Notch pages, Pets, Notifications, Widgets and shelf, Music and calendar, Pomodoro and Devices; and Add-ons such as Token usage and Lyrics.

Keyboard

These shortcuts work while Amaru is the active app. They are not global hotkeys.

Notch

Closed, the notch shows one live thing beside the camera: the song and its lyric line, an agent at work, the Pomodoro countdown, a volume change, or the idle slots you picked (clock, battery, today's tokens, plan left or a pet). Hover or click to open it.

Open, it has pages you switch between at the top:

• Home: what's playing with controls, a Pomodoro timer, your next calendar events and a to-do list.
• Coding: local dev servers with port, project and uptime, plus build, Docker and Git activity. Open, copy the address or stop a server.
• Usage: AI tokens and cost (see AI usage).
• Shelf: files you dropped, kept as references (up to 100). Removing one never deletes the file. AirDrop target included.
• System: CPU, GPU, memory, disks, network, battery and the busiest processes.

Three looks: Classic (black, like the hardware notch), Glass, and Pill, a floating capsule under the camera that also works on screens without a notch.

Music and lyrics

Amaru shows what any app is playing through the system's Now Playing information: Music, Spotify, video players and browsers. Controls and artwork for Music and Spotify use the Automation permission. Titles from browsers are tidied, so "ARTIST - SONG - Official Video" reads as the song by the artist.

Synced lyrics are an add-on, off by default. When on, Amaru asks LRCLIB once per song with the title, artist, album and length, and keeps the answer on your Mac (90 days, or one day for "not found"). If a song's lyrics run early or late, nudge them by up to five seconds; the offset is remembered for that song.

AI usage

Token usage is an add-on. When you turn it on, Amaru reads the files these tools already write in your home folder, read-only:

Each tool's card in Settings → Token usage says whether its files were found and what to change in the tool when a count is missing. Totals are shown for today, this month and all time, by model and by project. Cost is an estimate from public model prices; a model without a known price shows tokens only.

Plan limits

For Claude Code, Codex, OpenCode Go, Cursor, GitHub Copilot, Kiro and Antigravity, Amaru can show how much of your plans is left and when they reset, one card per account with its email partly hidden (h•••@gmail.com). This is a separate switch from token usage, because it uses the network: Amaru reads the sign-in the tool stored on your Mac and asks the tool's own service over HTTPS. Antigravity and Kiro are asked on your Mac through their own local server or command. Amaru never refreshes or changes a sign-in, follows no redirects, and backs off when a provider asks it to.

The Services panel in the AI usage tab lists each tool with what Amaru reads from it and where that goes. Sign in runs the tool's own login command in Terminal; Amaru does not type into Terminal or see what you enter. Cursor is read from the sign-in Cursor's own app keeps; no browser is ever read. A second Claude login, such as a Team seat you only use in the browser, can be added by hand with its claude.ai session key (the dashed "Add another Claude account" card on the Limits page, Services, or Settings › AI usage); Amaru keeps it in its own Keychain item and you can remove it at any time. For OpenCode Go you can add an API key the same way. Costs are estimates at public API rates, shown in USD or IDR.

From the recent pace Amaru forecasts when a limit will run out and shows a banner two hours before. Plan resets also appear in the notch calendar; nothing is written to your own calendars.

Side rail

A thin rail on the screen edge with today's tokens, a ring per plan limit and the number of running sessions. Hover to open a card per tool with limits, reset times, running sessions and their models. It can sit on the left or the right, or tuck away.

Dock and window previews

The dock shows pinned and running apps, the time, battery, a timer and the shelf. Right-click an icon to pin, reorder or see its windows. Collapse it to a floating pill whenever you like.

Turn on Show app windows on hover to see thumbnails of each app's windows. Thumbnails need Screen Recording; focusing or closing a specific window needs Accessibility. Everything else works without them.

Optionally, Amaru can hide the macOS Dock while it runs. Your Dock settings come back when you turn the option off or quit Amaru.

Send and receive files

The Send tile on the shelf is one door for sending. Drop files on it, or click it to send the whole shelf: AirDrop opens, and if Quick Share is on and an Android phone is nearby, the phone appears beside AirDrop to pick. Quick Share is off until you turn it on in Settings.

To receive from any phone, iPhone or Android, with no app on it, tap the QR icon on the tile. Amaru shows a QR code for a link on your Wi-Fi; the phone scans it, opens a page, picks files, and they land in Downloads and on your shelf. The link holds a random secret, works for ten minutes or until you press Stop, accepts only devices on your local network, and limits files to 2 GB each. It is plain HTTP on your network and nothing goes through the internet. Anyone on your Wi-Fi who has the link can send files while it is open, so close it when you are done.

Pets

Pip and seven other pets (cat, dog, rabbit, fox, panda, penguin, capybara) sit beside the camera, in native, pixel or illustrated style, with coats, accessories and your own name for them. They react to what happens: headphones when music plays, watching during a film, focus with your timer, worried when the battery is low, asleep when you step away. You can import your own PNG or an animated pack.

Notifications

The notch can show short banners for the charger, low battery, network changes, Bluetooth devices, finished downloads, calendar reminders, an agent waiting for you, and a plan limit about to run out. Each category can be turned off; Quiet mode hides them all.

Opt-in integrations report finished tasks from VS Code and finished commands from zsh (including Warp), using the exit code. You install them yourself with the guide in the repository; Amaru never edits your shell or editor configuration on its own.

Claude Code permissions

Optional and off by default. When it is on, Claude Code's permission prompts appear in the notch with Deny, Always and Allow, so you can answer without switching to the terminal.

1. In Settings → Pop-ups, turn on Answer Claude Code permission requests.
2. Choose Copy hook setup and paste the hooks block into ~/.claude/settings.json yourself. Amaru never edits that file. If you move the app, copy the setup again, because the path changes.

Amaru shows the tool name and a short summary of the command, file or address, plus the name of the working folder. If Amaru is not running, or you do not answer within about 30 seconds, the hook gives no decision and Claude Code asks the usual way. Claude Code's own deny rules still apply even when you allow.

Browser bridge

An optional extension for Chromium browsers such as Chrome and Arc reports the media playing in tabs and can enforce your focus list during a Pomodoro. Turn it on in Settings, open the extension folder, load it in your browser and paste the pairing key. It only talks to Amaru on 127.0.0.1, and requests without the key are rejected. Safari is not supported.

Permissions

macOS asks for each permission the first time a feature needs it. You can say no and keep using the rest of Amaru.

Privacy and network

Amaru needs no account and has no analytics. Settings, profiles, notes, to-dos, pets and the shelf are stored in your user folder. It connects to the network only for these, and only after you switch them on or press the button for them:

Token counts are computed from local files and stay on your Mac. Prompts and conversation text are not sent anywhere.

FAQ

Credits

Amaru adapts parts of renotch (by yosaiy) and token-monitor (by Javis), both under the MIT License; their licenses ship inside the app. Lyrics come from LRCLIB. Brand typefaces: Bricolage Grotesque and Schibsted Grotesk, under the SIL Open Font License.