tomari
v0.6.0
Published
Your Claude Code sessions as animated pixel-art creatures on the edge of your Mac's screen
Readme
Tomari
A floating strip on the edge of your Mac's screen with one animated pixel-art creature per Claude Code session. Each creature shows what its session is doing, and the ones waiting for you are hard to miss. Click a creature and its session opens in the Claude desktop app.
Not an official Anthropic project. It is not affiliated with or endorsed by Anthropic. "Claude" is a trademark of Anthropic, PBC.
Early development. Expect rough edges. macOS 14 or newer only.
Install
npx tomari setupThat's all: the strip appears on the right edge with a + to pin your sessions, and it comes back at every login. Setup:
- copies Tomari's binaries into
~/Library/Application Support/tomari/bin; - adds hooks to
~/.claude/settings.json, after backing it up, so Claude Code reports each event to Tomari's agent; - if you use Codex, adds the same hooks to
~/.codex/hooks.json, also after a backup; - starts the agent and the strip now and at every login, as LaunchAgents;
- replaces claude-panel's agent if you have it, keeping its pinned sessions and their looks;
- moves an install from when Tomari was called Perch (
@elrincondeldev/perch) into Tomari's places, keeping its pins, icons and token.
npx tomari status # what's installed and running
npx tomari uninstall # remove everything; asks before deleting pins and iconsYou need the Claude desktop app (sessions in its Code tab), the Claude Code CLI 2.1.285 or newer, and Node.js 18 or newer for npx.
Features
- The sessions you choose: the + at the end of the strip lists every session in the Claude desktop app and every Codex thread, recent or old, running or stopped, plus the running sessions Tomari sees in your terminals, in a panel with a Claude and a Codex tab; pick one to pin it, or unpin it. Type to filter by name or folder (accents and case don't matter; each tab's count shows its matches), ↑↓ to move, Tab to switch tabs, Return to pin and Esc to close. The panel takes the keyboard without bringing Tomari to the front, and closes when you click elsewhere. Its last item, New Terminal tab, opens a plain shell in Terminal.app, without Claude: a tab of the front window when macOS is set to prefer tabs, a new window otherwise. Sessions you haven't pinned show up only while they work or wait for you, and for five minutes after they finish, so a fresh install starts with just the +.
- One creature per session, animated by its state: working, needs permission, asking you, compacting, done, error or closed. Finished sessions fall asleep after five minutes.
- Hard to miss when it needs you: a permission request blinks the creature's tile in orange; a question rings it in orange. A working creature hops with typing dots over its head, and one that finished its turn holds up a green check, ringed in green, until you reply or it falls asleep.
- Answer permissions and questions from the strip: click a Claude Code session waiting for permission to see what it asks, in full (the command, file, URL or input), and Allow (Return) or Deny it without leaving the app you are in; Open takes you to the session instead, and Esc closes the card without answering. When Claude suggests a rule to stop asking, such as
Bash(npm test:*)in this project or access to a folder for this session, the card spells it out and Always allows with it, the same as Claude's own "Yes, and don't ask again". A question (AskUserQuestion) shows each question with its options: pick them and Answer, or press an option's number when there is a single question. Claude keeps its own dialog up meanwhile, in the terminal or the desktop app, and whichever you answer first wins. Plans to review still open the session, since approving one also picks the mode Claude goes on in, and so does typing your own answer to a question. On by default; turn it off from the menu bar icon to make that click open the session as before. Not for Codex, which asks its hooks before it shows its own approval, so waiting there would hide it. - Hover for the session's name, agent and status, e.g.
Bash: npm test · 4mordone · 5m; while a session works or waits, the time is how long it has been in that state (waiting for you · 2m,working · 1h 5m). - Click to open the session in the Claude desktop app, even one the app has stopped. A session running in Terminal.app brings its tab to the front instead. Without the desktop app, a closed session resumes with
claude --resumein a new Terminal tab, in the folder where it ran. The session in front is ringed in white. - Which session is in front: while Terminal is in front, the selected Terminal tab decides; while the Claude desktop app is in front, the session it shows does; with any other app in front the ring stays where it was. The first time Terminal is in front, macOS asks to let Tomari control Terminal, which it uses to read which tab is selected; Tomari doesn't ask Terminal anything while another app is in front.
- Background sessions (
claude --bg) run in a terminal the Claude daemon owns, so clicking one attaches it withclaude attachin a new Terminal tab. Right-click one and choose Stop session to runclaude stop(it asks first if the session is busy); the conversation is kept. - Right-click (or control-click) to pin or unpin the session, open its folder in Finder (shown only while the folder exists) and pick its character and color.
- Launcher: press ⌥Space anywhere to open the + panel in the middle of the screen, with a first On strip tab that lists the strip's sessions, those waiting for you on top, longest wait first, each with what it is doing. Type to filter, Return opens the session where it lives (its Terminal tab, the Claude desktop app or Codex), ⌘Return pins or unpins it, and the Claude and Codex tabs open any session of the library the same way. The last tab, New, lists the folders your sessions ran in, the most recent first: Return starts a new Claude Code session there (in the desktop app when you have it, else in a new Terminal tab), and ⌥Return a Codex one in Terminal. Press the shortcut again or Esc to close. Pick your own under Launcher Shortcut → Record Shortcut… in the menu bar item: press any key with ⌘, ⌃ or ⌥, or an F-key alone, and it is saved at once, unless another app already uses it. ⌥ alone only goes with keys that type nothing (Space, arrows, Return…), since ⌥ with a letter or number types a character, such as @ on a Spanish keyboard. The same submenu goes back to ⌥Space or turns the shortcut off. It is a Carbon hot key, so it needs no Accessibility permission.
- Notifications: when a session starts waiting on you, macOS shows a notification (Tomari asks for permission the first time). A permission prompt comes with Allow, Always Allow (when Claude suggests a rule) and Deny, and a single question with up to four options with one button per option, so you can answer from the banner, even with the strip hidden; clicking the notification itself shows the card beside the creature, or opens the session. A new prompt replaces the session's notification, and it goes away once the session moves on, however you answered. None for the session you are looking at in Terminal or the Claude desktop app, nor for sessions already waiting when Tomari starts. On by default; turn it off from the menu bar icon, or for Tomari in System Settings → Notifications.
- Sound when done: off by default; turn it on from the menu bar icon to hear a short chime when a session finishes working. It stays quiet for the session you are looking at in Terminal or the Claude desktop app.
- Sound when waiting for you: off by default; turn it on from the menu bar icon to hear a different chime (Ping) when a session starts needing your permission or input. Same rules as the done chime: quiet for the session you are looking at.
- Color by project: off by default; turn it on from the menu bar icon to give each project its own color, so sessions in the same folder (or the same repo, for Claude worktrees under
.claude/worktrees) look alike. It only applies to creatures still in the default color; one you colored yourself keeps its color. - Stays out of the way: the strip floats over every Space and full-screen app and never takes focus from the app you're using. The arrow tab beside it slides the strip off the edge, leaving just the tab, which blinks orange when a session needs you; click it again to bring the strip back.
- Codex too: sessions of OpenAI's Codex CLI and Codex app show up next to Claude Code's, as a robot. See Codex.
- Which agent, at a glance: every creature carries its agent's badge in its top-left corner: a small clay spark for Claude Code, a small
>_for Codex. The hover label ends with the agent, e.g.api · Claudeorapi · Codex. - Menu bar item to show or hide the strip, move it to the left or right edge, and see how many sessions are waiting for you. Quit Tomari there; it starts again at your next login.
How it works
Claude Code ─ hooks ─▶ tomari agent ◀─ WebSocket (127.0.0.1:7778, token) ─ tomari-overlay ─ menu bar
claude agents ─ poll ─▶ └ SQLite: pins, iconstomari(agent/, Bun and TypeScript compiled into one binary) holds the CLI and the agent. The agent tracks every session's state from Claude Code hooks andclaude agents --json, keeps pins and icons in SQLite, and opens sessions in the desktop app. It listens on 127.0.0.1 only.tomari-overlay(Sources/, Swift) is a native AppKit and Core Animation app that runs as an accessory: no Dock icon, just the strip and a menu bar item. Releases wrap it inTomari.app(an agent app,LSUIElement), since macOS only lets app bundles post notifications; built withswift buildit runs bare, without them. It costs about 0.5 % of one CPU core and 13 MB of memory while it animates.shared/protocol.tsis the contract between them.
| What the agent reads from Claude | Used for | Documented? |
|---|---|---|
| Hooks in ~/.claude/settings.json | Instant state changes | Yes |
| The PermissionRequest hook's decision | Allowing, allowing always (echoing a rule from permission_suggestions as updatedPermissions), denying and answering questions (updatedInput with answers) from the strip; Claude runs the hook alongside its own dialog and takes the first answer | Yes, but running alongside the terminal's dialog isn't |
| claude agents --json | Names, who is alive, corrections for missed hooks | Yes |
| claude --desktop --resume <id> | Opening a session the desktop app doesn't know; without the app, claude --resume <id> in a new Terminal tab | Yes |
| claude://code/continue?session=local_… | Opening any desktop-app session, running or stopped | No |
| claude://code/needs-input | Making the app let go of the session it counts as focused, which it won't open again by link, before opening that one with the app in front | No |
| ~/Library/Application Support/Claude/claude-code-sessions/ | The app's sessions, and their local_… ids | No |
| setFocusedSession in ~/Library/Logs/Claude/main.log | Which session is in front | No |
If a Claude update breaks an undocumented source, only the feature it feeds stops working.
Codex
Tomari follows Codex sessions, in its CLI and in its desktop app, through Codex's own hooks, which report the same events as Claude Code's. It needs Codex 0.146 or newer.
npx tomari setupadds Tomari's hooks to~/.codex/hooks.json(or$CODEX_HOME/hooks.json) when Codex is installed, anduninstallremoves them; your own hooks there stay. If yourconfig.tomldeclares hooks itself, setup leaves Codex alone, since Codex warns when one place declares hooks in both files: copy thehooksblock of ahooks.jsonthat setup wrote elsewhere into it as TOML.- Trust them once: Codex runs a new hook only after you review it. Open Codex, type
/hooksand trust Tomari's. Until then its sessions don't show up. Tomari never marks them trusted for you. - The Codex app also runs hooks for sessions you never see: the empty thread it opens ahead of "New thread", and a short one that writes each thread's title. Tomari tracks a Codex session only once it does something besides starting or ending and has a rollout in
~/.codex/sessions, so those never reach the strip. - A Codex session waits for you on a permission request (
PermissionRequest) and finishes its turn onStop. Its name is the thread's title from~/.codex/session_index.jsonl, or its folder. - Like a Claude Code session in a terminal, a Codex session you haven't pinned leaves the strip when it ends, e.g. when you quit Codex. Pin it from the + to keep it: a pinned closed thread stays, grayed, and a click reopens it.
- Click: a thread the Codex app started opens there (
codex://threads/<id>); a running CLI session brings its Terminal tab to the front; a closed one resumes withcodex resume <id>in a new Terminal tab, in its folder. - Codex has no
claude agents: the hook reports the pid of the shell's parent, the agent walks up to thecodexprocess, and the session ends when that process does, or onSessionEnd.
| What the agent reads from Codex | Used for | Documented? |
|---|---|---|
| Hooks in ~/.codex/hooks.json | State changes, and the pid of the Codex process | Yes |
| ~/.codex/session_index.jsonl | Thread titles | No |
| The first line of a thread's rollout in ~/.codex/sessions/ | Whether the Codex app started it | No |
| ~/.codex/state_<n>.sqlite, read only | The Codex threads the + lists, running or not | No |
| ~/.codex/external_agent_session_imports.json | Which Codex threads are Claude Code sessions Codex imported, left out of the Codex list | No |
| codex://threads/<id> | Opening a thread in the Codex app | No |
| codex resume <id> | Reopening a closed CLI session | Yes |
Customizing the creatures
The characters are 16×16 text templates in Sources/TomariCore/Resources/characters.json:
| Field | Meaning |
|---|---|
| body | 16 rows of 16 cells: B body (the session's color), D darker, L lighter, F face plate, P pink, W white, . empty |
| walk | Optional rows that replace the body from row down on alternate frames while the session works |
| eyes | Top-left corners of the two 2×2 eyes, which blink, close and squint on their own |
| eyeColor | Optional #rrggbb |
After editing, check the templates with swift run TomariCoreTests and rebuild.
Development
You need the Command Line Tools for Xcode (xcode-select --install) and Bun 1.3 or newer.
(cd agent && bun install)
bun test agent npm # agent, CLI and npm launcher
swift run TomariCoreTests # protocol, session list, status rules, sprites and layout
swift build # debug overlay: .build/debug/tomari-overlay
bun scripts/release.ts --arch arm64 # npm packages in dist/npm
dist/npm/tomari-darwin-arm64/bin/tomari setup # install that buildThe Command Line Tools for Xcode 15 ship without XCTest, so the Swift tests are a plain executable that exits non-zero when a check fails.
Pushing a v* tag runs .github/workflows/release.yml: it tests, builds for Apple Silicon and Intel, publishes the three npm packages through npm's Trusted Publishing, with no token, and attaches the binaries to a GitHub release. Pull requests that touch what ships run the same build without publishing.
The landing page is an Astro site in site/. It draws the creatures from the same characters.json, through a TypeScript port of the overlay's sprite renderer in site/src/domain.
cd site && bun install
bun run dev # http://localhost:4321
bun test # the sprite port and the page's other pure logic
bun run build # type-checks, then builds into site/distOn Vercel, import the repository and set its Root Directory to site; Vercel detects Astro and builds it with Bun.
Privacy
- Everything stays on your Mac: the overlay only talks to the agent on 127.0.0.1, and the agent only listens there. No telemetry.
- The WebSocket needs the pairing token in
~/Library/Application Support/tomari/config.json, and accepts onlyopen,pin,icon,stop,library,terminal,new(start Claude Code or Codex in a folder a session already ran in, and only there),frontApp(which of Terminal, the Claude desktop app or another app is in front, nothing more) andpermission(allow, always allow with the rule Claude suggested, or deny one held request, by its id, or pick its questions' options by index), with validated arguments. A permission request is held only while the overlay is connected, and gets no decision from Tomari when it disconnects, the session moves on, or after ten minutes. - Tomari keeps its data in
~/Library/Application Support/tomari/, its logs in~/Library/Logs/tomari/, and the strip's edge in thecom.elrincondeldev.tomaridefaults. - When several untitled sessions share a folder name, the strip tells them apart with the first 24 characters of each one's first prompt. It is kept in memory only, never written to disk, but it is visible on screen like the hover label below.
- The hover label can show tool details such as a shell command, so anyone who can see your screen can read them.
- Notifications show the command or question a session waits on, and macOS keeps them in Notification Center and may show them on the lock screen; choose how they show for Tomari in System Settings → Notifications. Nothing leaves your Mac.
- The permission card shows the full command or input a session asks to run, or its questions, kept in memory only, like the hover label. Always allow only ever adds the rule Claude itself suggested for that request, never a mode change.
Roadmap
- Homebrew:
brew install elrincondeldev/tap/tomari, from the same release binaries. - Drag the strip to any edge.
