attn

README

attn

attention hub — because your head shouldn't feel like concrete by 3pm.

I built this after noticing a pattern: I'd start the day sharp, spin up 4-5 AI agents across different repos, and by mid-afternoon my brain was soup. Not from the coding — from the managing. Which terminal has the agent that's stuck? Did that one finish? Wait, who asked me a question 20 minutes ago? Alt-tab, alt-tab, alt-tab, scroll, squint, repeat.

attn fixes the dumbest part of multi-agent workflows: knowing what needs you right now.

It also lets one app manage sessions running somewhere else. Point attn at a remote daemon over SSH — a cloud box, a homelab machine, or even a local VM — and those sessions show up in the same sidebar, terminals, and worktree picker as your local ones.

It's a desktop app that wraps your agent CLIs — Claude Code, Codex, Copilot — and puts them all in one window with color-coded status. Green means working. Yellow means "hey, I need you." Gray means done. No more tab-hunting. No more heavy head.

There is no custom agent UI. attn wraps each CLI directly. You get the real, native experience of every agent — just organized.

What you get

Workspaces in one sidebar — The sidebar groups your work into workspaces, each holding the sessions and terminals for one task. Live state at a glance — the one that needs you glows. Click it. Done.

Panes, splits, and first-class shells — A workspace can hold several sessions side by side. Split a pane, open a plain shell as its own session from the same dialog you use for agents, and move focus between panes with the keyboard. Never leave the window.

Remote daemons over SSH — Keep sessions on a GPU box, Linux host, or local VM and manage them from the same app. Spawn new sessions remotely, browse remote repos, and open remote worktrees without juggling another terminal window.

PR dashboard — Your PRs, your review requests, CI failures, merge conflicts — one place. Works across GitHub.com and GitHub Enterprise. Open a PR directly into a worktree.

Git worktrees & branches — Parallel agents need parallel branches. Create, switch, and manage worktrees from the app. Stop stepping on your own feet.

Quick Find — Cmd+F to yank URLs, paths, and hashes out of terminal output.

Supported agents

Agent	State detection	Resume
Claude Code	Hooks + classifier	Yes
Codex	PTY heuristics + transcript classifier	No
Copilot CLI	PTY heuristics + transcript classifier	No

Install

Homebrew cask (desktop app)

brew tap victorarias/attn https://github.com/victorarias/attn
brew install --cask victorarias/attn/attn

This installs attn.app with its bundled daemon/runtime binary.

Direct DMG

Grab the latest release, open the DMG, drag to Applications.

Updating

brew update && brew upgrade --cask victorarias/attn/attn

The app nudges you when a new release exists. No auto-install — you pick when.

Prerequisites

• macOS (Apple Silicon)
• At least one agent CLI installed
• GitHub CLI (gh) v2.81.0+ for PR features

Quick start

1. Launch attn from Applications.
2. Cmd+T — start a workspace: pick an agent (or a plain shell), pick a directory, go. Cmd+N adds another session to the workspace you're in.
3. Watch the sidebar. Colors tell you who needs you.
4. Press Cmd+/ any time for the full keyboard shortcuts list.
5. Optional: add an SSH endpoint in Settings and run remote or VM sessions from the same picker.

Session states

Color	What it means
🟢 Green	Agent is working — leave it alone
🟡 Yellow	Agent needs attention: asked a question, or finished a long run (5+ min) and is waiting for your review
🟡 Flashing	Agent wants tool approval — go approve
⚫ Gray	Agent is done — move on

Long-run review behavior: if a run takes 5+ minutes, attn keeps it yellow when it finishes, then runs smart done/waiting classification only after you actually view that session (5 seconds stable selection; immediate if you were already focused on it).

Shortcuts

Shortcut	What it does
Cmd+T	New workspace (with an initial session)
Cmd+N	New session in current workspace
Cmd+Shift+N	New session, split sideways
Cmd+Option+←↑→↓	Move between panes (cross into the next workspace at an edge)
Cmd+1–9	Jump to a workspace
Cmd+F	Quick Find
Cmd+K	Attention drawer (who needs me?)
Cmd+`	Utility terminal
Cmd+Up / Down	Jump between sessions
Cmd+R	Refresh PRs
Cmd+/	All keyboard shortcuts

Press Cmd+/ in the app for the full, always-current list.

Selecting text in agent terminals

Agents like Claude Code enable terminal mouse tracking, which means a normal click-drag is forwarded to the agent instead of creating a selection. Hold Option while dragging to bypass mouse tracking and make a selection you can copy — this is the same convention iTerm2, Terminal.app, and kitty use.

If the agent explicitly copies text for you (e.g. "copy this to my clipboard"), attn honors the terminal's OSC 52 clipboard sequence and writes to your Mac clipboard directly. No xclip / X server needed on the remote.

How it works

1. The bundled attn runtime wraps your agent CLI and installs hooks (Claude) or reads PTY output (Codex, Copilot) to detect state.
2. A background daemon tracks sessions via unix socket (~/.attn/attn.sock).
3. The desktop app connects over WebSocket for real-time updates.
4. Optional SSH-managed remote daemons connect through the local hub, so local and remote sessions share one session list and one control surface.
5. A lightweight classifier figures out if Claude stopped because it's done or because it's waiting for you.
6. For 5+ minute runs, classification is intentionally deferred until you visualize the session, so "done" runs still surface for manual review first.
7. gh polls PRs across all your authenticated GitHub hosts.

Build from source

Requires Go 1.25+, Rust (stable), Node.js 20+, pnpm, and Tauri prerequisites.

Source builds intentionally disable GitHub release update banners by default.

git clone https://github.com/victorarias/attn.git && cd attn

Command	What it does
make build	Build Go daemon binary
make	Install attn.app and launch it — the one-command prod inner loop
make install	Install the app bundle without launching (scripts / CI)
make install-daemon	Update only the installed app's bundled daemon/runtime for the fast dev loop
make dev	Install and launch attn-dev.app — the isolated dev sibling, for safely iterating on attn without touching your live install
make install-dev	Same as make dev but without launching
make install-daemon-dev	Fast sidecar-only loop for the dev install
make build-app	Build daemon + Tauri app
make dist	Create DMG
make test	Go tests
make test-frontend	Frontend tests (vitest)
make test-harness	Go + frontend + E2E

Iterating on attn itself (attn-on-attn)

If you use attn daily and want to develop attn with attn running, use the dev sibling install instead of reinstalling your live copy. make dev builds and launches ~/Applications/attn-dev.app — separate bundle identifier (com.attn.manager.dev), separate data dir (~/.attn-dev/), separate WebSocket port (29849). Both apps run side-by-side with zero cross-contamination. make install and make install-daemon refuse at parse time if ATTN_PROFILE is set in your shell, so you can't accidentally reinstall the live app while iterating on dev.

The same ATTN_PROFILE=<name> env var scopes CLI commands (eval "$(attn profile-env dev)" to set it shell-wide), and the real-app serial matrix defaults to the dev install so it never takes over your live app.

Docs

Terminal rendering learnings	PTY and harness notes from the current cleanup stream
Release	Maintainer runbook

Status

Alpha — I use it every day. It's rough around the edges, but it works really well and it's genuinely powerful once you get going.

A note about this project

I built attn because I needed it. Managing multiple agents was the bottleneck, not the coding itself.

I work full time, and I have 2 dogs and 4 cats at home. Free time is not abundant. attn is open source, but if you need changes I can't get to — fork it. That's encouraged, not rude.

Issues are welcome, but please be detailed:

• Describe what happened and what you expected.
• Include the tail of ~/.attn/daemon.log from right after you reproduced the issue.
• For visual bugs, attach a screenshot.

Vague "it doesn't work" reports aren't actionable and will sit there forever.

I'm a friendly person and happy to help when I can. But don't be entitled about it — that's the one thing I can't deal with. Entitled behavior gets ignored, and if I'm having a bad day, maybe banned.

Built with

Tauri / React / Go / SQLite

License

GPL-3.0