
tomari
Your Claude Code sessions, perched on the edge of your screen.
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up tomari (release-binary project) into my current project. Found on https://claudeers.com/tomari Repo: https://github.com/elrincondeldev/tomari Homepage/docs: https://tomari-zeta.vercel.app Detected install method: release-binary → inspect the README Category: devtools. Platforms: cli, desktop. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: unknown; community-verified: false. Confirm the source before running anything.
Grab the latest release asset from GitHub.
# download a build from https://github.com/elrincondeldev/tomari/releases
git clone https://github.com/elrincondeldev/tomari
// compatibility
| Platforms | cli, desktop |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | MIT |
| Pricing | open-source |
| Language | TypeScript |
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 setup
That'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; - 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, their looks and its pairing token;
- 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 icons
npx tomari setup --pi # also let a claude-panel Raspberry Pi connect over your network
You 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, recent or old, running or stopped; pick one to pin it. 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.
- Hover for the session's name and status, e.g.
Bash: npm testordone · 5m. - Click to open the session in the Claude desktop app, even one the app has stopped. The session in front is ringed in white.
- Right-click (or control-click) to pin or unpin the session and pick its character and 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.
- 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, icons └ claude-panel Pi (with --pi)
tomari(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, unless you set it up with--pi.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. It costs about 0.5 % of one CPU core and 13 MB of memory while it animates.shared/protocol.tsis the contract between them, and the Pi panel speaks it too.
| What the agent reads from Claude | Used for | Documented? |
|---|---|---|
Hooks in ~/.claude/settings.json | Instant state changes | Yes |
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 | Yes |
claude://code/continue?session=local_… | Opening any desktop-app session, running or stopped | 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.
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, . 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 build
The 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/dist
On 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 unless you choose
--pi. No telemetry. - The WebSocket needs the pairing token in
~/Library/Application Support/tomari/config.json, and accepts onlyopen,pin,iconandlibrary, with validated arguments. - Tomari keeps its data in
~/Library/Application Support/tomari/, its logs in~/Library/Logs/tomari/, and the strip's edge in thecom.elrincondeldev.tomaridefaults. - The hover label can show tool details such as a shell command, so anyone who can see your screen can read them.
Roadmap
- Homebrew:
brew install elrincondeldev/tap/tomari, from the same release binaries. - Drag the strip to any edge, global shortcuts to open sessions, and notifications when a session needs you.
License
// faq
What is tomari?
Your Claude Code sessions, perched on the edge of your screen.. It is open-source on GitHub.
Is tomari free to use?
tomari is open-source under the MIT license, so it is free to use.
What category does tomari belong to?
tomari is listed under devtools in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/tomari)
// retro hit counter
[](https://claudeers.com/tomari)
// reviews
// guestbook
// related in Developer Tools
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Curs…
Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote.
AI coding assistant skill (Claude Code, Codex, OpenCode, Cursor, Gemini CLI, and more). Turn any folder of code, SQL schemas, R scripts, shell scripts, docs,…
Use Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA