mirror of
https://github.com/l0ng-ai/tty7.git
synced 2026-11-06 16:15:41 +00:00
Austin SpragginsandClaude Opus 5.5
1b55d3cb00
With several agents running across tabs and windows, finding the one
blocked on a permission prompt meant scanning tab dots or opening the tray
menu. Go to Next Agent Needing Attention (cmd-shift-U, and ctrl-shift-U off
macOS; FocusNextAgentNeedingAttention to rebind, also in Search Everywhere)
reveals it directly: waiting agents first, the longest wait at the head,
then finished turns nobody has read. Pressing again from one of them moves
to the next and wraps; from anywhere else it starts at the head. It searches
the tabs of every open window, the same agents the tray menu lists, and
reveals a pane in another window the way a tray pick does; a workspace no
window is showing is not searched. With nothing to attend to it says so
("No agent in your open windows needs you") instead of doing nothing
silently. The ordering is a pure function over the tray's agent rows, with
tests.
Ordering by age needs to know when a status began, so AgentSessionState
carries since_ms: the daemon stamps it whenever a hook event, an assumed
interrupt or a stale-turn sweep moves the status. Hook events are stamped
one at a time, so a status that leaves and comes back within one batch
(Done, a new prompt, Done again) starts a fresh age. It is wall-clock time,
not an Instant, because it crosses the socket and survives a handoff; ages
across machines therefore follow each machine's clock. An older daemon
simply leaves it out and those rows queue behind stamped ones.
The tray menu now reads "needs input · waiting 3m", the workspace switcher
shows the same age beside the tab (computed the same way, on the same
clock), and `tty7 agents` gains a FOR column. Ages are in whole minutes in
the GUI so the tray snapshot, and with it the menu, changes at most once a
minute.
Claude-Session: https://claude.ai/code/session_017RJFBHCC4dbUua21a2TedQ
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
130 lines
5.5 KiB
Plaintext
130 lines
5.5 KiB
Plaintext
---
|
|
title: "Status and notifications"
|
|
description: "Installing the hooks, reading the dots, and being told when an agent needs you."
|
|
---
|
|
|
|
An agent working for two minutes and an agent that stopped ninety seconds ago
|
|
waiting for permission look identical from outside. tty7 fixes that by letting
|
|
the agent say which one it is.
|
|
|
|
## Installing the hooks
|
|
|
|
**Settings → Integrations** lists every agent that can report status, with an
|
|
**Install** button beside each:
|
|
|
|
| Agent | |
|
|
|---|---|
|
|
| Claude Code · Codex · TraeCode · Copilot CLI · OpenCode · Pi · Grok Build · Oh My Pi · Gemini · Droid · Qwen Code · Goose · Kimi Code · Qoder CLI · Qoder CN CLI · Crush · CodeBuddy · Cursor CLI · Prime Agent · Antigravity · Empryo · Muse Code · jcode | Hooks available |
|
|
| Aider · Amp · Auggie · Hermes · Vibe | Detected and labelled, but no status channel yet |
|
|
|
|
Installing writes into that agent's own configuration directory. Once installed
|
|
the row grows a second **Uninstall** button beside the first, which itself
|
|
becomes **Reinstall** — or **Update**, against an **Outdated** state, when tty7
|
|
ships a newer hook.
|
|
|
|
<Note>
|
|
Crush ships only a `PreToolUse` hook today. It is enough to remember the
|
|
session for resume, but there is no turn boundary behind it, so a Crush pane
|
|
carries no status dot and `tty7 wait` times out rather than returning.
|
|
</Note>
|
|
|
|
<Note>
|
|
Antigravity has no session-start or permission event, so its pane goes
|
|
straight from no dot to working on the first model call, and a pending
|
|
permission prompt shows as working rather than amber. Its hooks live in a
|
|
`tty7` set inside `~/.gemini/config/hooks.json`, beside any sets of your own.
|
|
</Note>
|
|
|
|
<Note>
|
|
`cursor-agent -p` (print mode) sends neither of Cursor's turn hooks, so a
|
|
headless run records its session id — Copy Session ID and resume still
|
|
work — but shows no status dot. The interactive `cursor-agent` shows the
|
|
full working → done cycle.
|
|
</Note>
|
|
|
|
<Note>
|
|
The hooks only do anything inside tty7. Running the same agent in another
|
|
terminal is unaffected.
|
|
</Note>
|
|
|
|
Hooks are installed per machine. Once a second
|
|
[machine](/remote/workspaces) is linked, a row of chips appears above the table
|
|
to pick which one you are looking at, and the table then shows that machine's
|
|
agents — so a dev box gets its hooks installed the same way, from the same
|
|
screen.
|
|
|
|
## The status dot
|
|
|
|
Every tab chip and sidebar row carries a dot:
|
|
|
|
| Dot | Meaning |
|
|
|---|---|
|
|
| 🔵 **Blue** | Working |
|
|
| 🟠 **Amber** | Needs your input — a permission prompt, a question |
|
|
| 🟢 **Green** | Done with this turn |
|
|
|
|
<Frame caption="Working (blue), waiting on you (amber), and done (green), side by side">
|
|
<img src="/images/agent-status.webp" alt="Agent status dots" />
|
|
</Frame>
|
|
|
|
The same three states are what `tty7 agents` reports as `working` / `waiting` /
|
|
`done`, and what [`tty7 wait`](/agents/orchestration) blocks on. A fourth state,
|
|
`idle`, carries no dot — it is an agent that has not started a turn.
|
|
|
|
## Notifications
|
|
|
|
Two, both following your **Settings → General → Notifications** policy:
|
|
|
|
- **"needs your permission…"** the moment an agent blocks on you
|
|
- **"finished after 42s"** at the end of a turn
|
|
|
|
Which means that by default — *When unfocused* — you are told the instant you
|
|
are the bottleneck, and left alone while you are watching.
|
|
|
|
A program can also post its own notification with OSC 9, OSC 777
|
|
(`notify;title;body`) or kitty's OSC 99. tty7 shows it under the same policy,
|
|
held back only while you are looking at that pane, and a click reveals the
|
|
pane. Claude Code writes one when its **Notifications** setting (`/config`) is
|
|
`ghostty`, `kitty` or `iterm2`. Its default, `auto`, sends nothing in tty7. A
|
|
pane whose agent already reports through tty7's hooks skips the copy that would
|
|
repeat the notice above.
|
|
|
|
## The tray icon
|
|
|
|
tty7 keeps a status item in the system tray (menu bar on macOS). It flips to an
|
|
attention state the moment *any* agent anywhere needs input, so you can see it
|
|
without the window in front of you.
|
|
|
|
Its menu lists every agent pane with its brand avatar and status dot — click one
|
|
to reveal it — and also holds the notification policy switch and **Quit and Stop
|
|
Server…**. An agent that needs input says for how long (*needs input · waiting
|
|
3m*), and the workspace switcher shows the same age beside its tab.
|
|
|
|
## Jumping to the agent that needs you
|
|
|
|
**Agent: Go to Next Needing Attention** (<kbd>⌘ ⇧ U</kbd>, <kbd>Ctrl ⇧ U</kbd>
|
|
on Windows and Linux; `FocusNextAgentNeedingAttention` to rebind) reveals the
|
|
agent pane that has been waiting on you longest, switching tab or window to get
|
|
there. It looks at the tabs open in your windows, the same agents the tray menu
|
|
lists; a workspace no window is showing is left out. Press it again for the next
|
|
one: every waiting agent, oldest first, then each finished turn you have not
|
|
looked at yet, and round again. With nothing waiting it says so and stays where
|
|
you are. Each wait is timed by the clock of the machine the agent runs on, so
|
|
agents on machines whose clocks disagree can show ages, and queue, slightly off.
|
|
|
|
Turn it off with **Settings → General → Show tray icon**
|
|
(`show_tray_icon: false`).
|
|
|
|
## Sending an agent some context
|
|
|
|
Two Search Everywhere actions hand what is in front of you to the agent running in
|
|
the pane, as a ready-made prompt:
|
|
|
|
| Command | Sends |
|
|
|---|---|
|
|
| **Agent: Send Selection** | The current terminal selection |
|
|
| **Agent: Send Git Diff for Review** | The repository's `git diff` |
|
|
|
|
If nothing recognisable is running, tty7 says *"No running coding agent found"*
|
|
rather than typing into your shell.
|