mirror of
https://github.com/l0ng-ai/tty7.git
synced 2026-11-06 08:15:35 +00:00
384a329df7
* feat(terminal): program notifications follow the policy; read kitty OSC 99
OSC 9/777 notifications used to post from the reader thread regardless of
focus or the Never setting, and clicking one revealed nothing. They now queue
for the view, which applies notify_on_command_finish (Unfocused holds one back
only while its pane is focused in the key window), posts it clickable for the
pane, and titles it with the agent's name when it brings none. A pane whose
agent reports through tty7's hooks skips the copies the hooks already cover.
Kitty's OSC 99 is read too, chunked by i= with d=/p=/e=, in the client and in
the daemon sniffer, so a hookless agent's kitty notification marks it Waiting.
Claude Code's ghostty, kitty and iterm2 Notifications channels all land here;
its default, auto, sends nothing under TERM_PROGRAM=tty7.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* feat(terminal): agent hook notices follow the per-pane rule
An agent's Waiting and Done notices from tty7's hooks were only posted while
the window was in the background, so an agent in another tab of the front
window never reached you. They now share shows_notification with program
notifications: Never posts nothing, When unfocused holds a notice back only
while its pane is focused in the key window, Always always posts. A hooked
pane still skips its program's own copies, so nothing doubles.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* Revert "feat(terminal): agent hook notices follow the per-pane rule"
This reverts commit 7df400043c. The hook
notice change is a behaviour change of its own and moves to the stacked
branch upstream/hook-notices-per-pane.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* refactor(terminal): NotifyMode::allows, a Note type, and a cap on queued notes
One rule for every notification path: a mode allows a notice unless it is
Unfocused and the reader is watching. Kitty's pending chunks and a
finished note get names instead of tuples, and a pane whose view is not
polling keeps only its newest eight notes.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(changelog): drop the Unreleased entry; the release notes carry it
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(terminal): a burst of program notes shows its newest three, and an exiting shell's are shown
`take_osc_notes` hands over the newest three queued notes and drops the
rest, so a program that writes a burst doesn't spray the desktop. The view
shows them ahead of `poll_foreground`'s exit check, so what a program said
just before its shell exited still gets through.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* refactor(terminal): one cap on queued program notes, three
The queue kept 8 and `take_osc_notes` then handed over the newest 3: two
caps for one rule. The queue now keeps 3 and `take_osc_notes` drains it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* feat(terminal): at most five program notes per pane every ten seconds
The queue cap applies between polls, so a pane that keeps writing
notifications still posted a few every 300ms. Each pane now has a
NoteBudget: at most five notes per ten seconds reach the desktop, and the
rest are dropped and said once, as "More notifications from this pane
weren't shown", when the window turns over. The budget is asked on every
poll, held-back ones included, so that note comes even after the flood
stops and never for a count gone stale.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(terminal): kitty control payloads and id-less chunks don't build a note; OSC 9;10-12 aren't notes
A p=close, p=alive or p=? with the id of an unfinished OSC 99 note
finished and posted it. They are commands about notifications, so they
now leave pending notes alone. Chunks without an i= are each their own
notification per the spec, and no longer join an earlier id-less d=0
chunk. ConEmu's OSC 9;10, 9;11 and 9;12 (a prompt mark some shells emit
every prompt) were posted as notifications; they are subcommands like
9;1-9;9.
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: l0ng-ai <24760907+l0ng-ai@users.noreply.github.com>
117 lines
4.6 KiB
Plaintext
117 lines
4.6 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 | Hooks available |
|
|
| Aider · Amp · Auggie · Hermes · Vibe · Empryo | 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…**.
|
|
|
|
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.
|