claudeers.
// Developer Tools

tomari

Your Claude Code sessions, perched on the edge of your screen.

// Developer Tools[ cli ][ desktop ][ claude ]#claude#devtools◷ MIT$open-sourceupdated 8 days ago

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.
// or install directly (release-binary)

Grab the latest release asset from GitHub.

# download a build from https://github.com/elrincondeldev/tomari/releases
// or clone
git clone https://github.com/elrincondeldev/tomari

// compatibility

Platformscli, desktop
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageTypeScript

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

Tomari

Eight pixel-art creatures, one per session state: working, needs permission, asking you, compacting, done, asleep, error and closed

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 test or done · 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 and claude 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.ts is the contract between them, and the Pi panel speaks it too.
What the agent reads from ClaudeUsed forDocumented?
Hooks in ~/.claude/settings.jsonInstant state changesYes
claude agents --jsonNames, who is alive, corrections for missed hooksYes
claude --desktop --resume <id>Opening a session the desktop app doesn't knowYes
claude://code/continue?session=local_…Opening any desktop-app session, running or stoppedNo
~/Library/Application Support/Claude/claude-code-sessions/The app's sessions, and their local_… idsNo
setFocusedSession in ~/Library/Logs/Claude/main.logWhich session is in frontNo

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:

FieldMeaning
body16 rows of 16 cells: B body (the session's color), D darker, L lighter, F face plate, P pink, . empty
walkOptional rows that replace the body from row down on alternate frames while the session works
eyesTop-left corners of the two 2×2 eyes, which blink, close and squint on their own
eyeColorOptional #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 only open, pin, icon and library, with validated arguments.
  • Tomari keeps its data in ~/Library/Application Support/tomari/, its logs in ~/Library/Logs/tomari/, and the strip's edge in the com.elrincondeldev.tomari defaults.
  • 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

MIT

// 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.

7 views
★ 18 stars
unclaimed
updated 8 days ago

// embed badge

tomari on Claudeers
[![Claudeers](https://claudeers.com/api/badge/tomari.svg)](https://claudeers.com/tomari)

// retro hit counter

tomari hit counter
[![Hits](https://claudeers.com/api/counter/tomari.svg)](https://claudeers.com/tomari)

// reviews

// guestbook

0/500

// related in Developer Tools

🔓

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Curs…

// devtoolsaffaan-m/⟨JavaScript⟩★ 307,864◷ MIT[ claude ]
🔓

Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote.

// devtoolsDietrichGebert/⟨JavaScript⟩★ 187,728◷ MIT[ claude ]
🔓

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,…

// devtoolssafishamsi/⟨Python⟩★ 147,800◷ MIT[ claude ]
🔓

Use Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA

// devtoolsgarrytan/⟨TypeScript⟩★ 140,465◷ MIT[ claude ]
→ see how tomari connects across the ecosystem