# Agent attention titles

LLMS index: [llms.txt](/aibox/v0.x/v0.33.2/llms.txt)

---

When an AI harness needs a human response, aibox can mark the tmux window in
the terminal tab title. This is useful when the agent is running in a
background pane or another tmux window: the title remains visible even when
that pane is not selected.

## Configuration

Titles are configured in `aibox.toml`:

```toml
[customization.tmux.title]
enabled = true
format = "{state_symbol}{project}:{window} — {directory}"
max-length = 60
directory-style = "basename"
done-ttl-seconds = 10
message-max-length = 32

[customization.tmux.title.states]
working = "● "
question = "❓ "
done = "✓ "
error = "! "
idle = ""

[customization.tmux.notifications]
enabled = false
protocol = "osc-9" # or "bell"
states = ["question", "error"]
include-message = true
```

`enabled = false` disables generated title settings. The default title is
short and project-oriented; use a custom `format` when session or harness
identity is more useful than the directory:

```toml
format = "{state_symbol}{harness} — {project}:{window}"
```

Supported placeholders are:

| Placeholder | Meaning |
|---|---|
| `{state_symbol}` | Configured symbol for the aggregate window state |
| `{state}` | State name: `idle`, `working`, `question`, `done`, or `error` |
| `{project}` | aibox project name |
| `{session}` | tmux session name |
| `{window}` / `{window_index}` | tmux window name or index |
| `{pane}` | active pane index |
| `{directory}` | Current directory in the selected directory style |
| `{directory_path}` | Full current-directory path |
| `{repository}` / `{branch}` | Git repository and branch, when available |
| `{harness}` / `{agent}` | Harness and agent identity, when supplied |
| `{task}` / `{message}` | Short task or question/error text, sanitized and bounded |
| `{elapsed}` | Elapsed time captured at the most recent state aggregation |

State is aggregated across all panes in the window. The precedence is
`error > question > working > done > idle`, so a question in a background
pane cannot be hidden by an idle active pane. Completion markers are temporary
and use `done-ttl-seconds`.

## Harness support and fallback

Harness integration is capability-based:

| Tier | Behavior |
|---|---|
| Native | Lifecycle hooks report working, question, completion, and error states. |
| Partial | Reliable lifecycle hooks report only the states the harness exposes. |
| Wrapper | aibox reports process start/exit; question detection is unavailable. |
| Manual | Use the explicit `aibox-agent-signal` helper from a key binding or wrapper. |

Current generated integrations:

| Harness | Tier | Native signals |
|---|---|---|
| Claude Code | Native | prompt, permission/elicitation, stop, failure |
| Codex CLI | Native | prompt, permission, stop, session end |
| OpenCode | Native | session status, permission, explicit question, error, idle |
| Gemini CLI | Native | before/after agent, tool permission, session end |
| GitHub Copilot CLI | Native | prompt, permission/elicitation, stop, error, session end |
| Cursor | Partial | prompt and stop |

Gemini and Codex classify an after-turn response ending in a question mark as
`question`. OpenCode uses its explicit `question.asked`, `question.replied`,
and `question.rejected` events. Copilot reports permission and elicitation
dialogs as questions; its stop payload does not expose final response text.

aibox does not infer a question from process idleness. For a harness without a
question hook, signal it explicitly, for example:

```sh
aibox-agent-signal question --harness my-harness --message 'Choose an option'
aibox-agent-signal working --harness my-harness
aibox-agent-signal done --harness my-harness
```

Signals are scoped to the current tmux pane and are safe to repeat. Outside
tmux they are a no-op, so the same wrapper can be used in and out of aibox
workspaces without affecting the terminal.

## Terminal and shell title ownership

Terminal emulators normally display the title emitted by tmux through the
standard title control sequence. Do not configure a competing fixed tab title
for an aibox tab. Inside tmux, tmux should be the sole title writer; otherwise
a shell `precmd` hook can overwrite the attention marker. This title path does
not depend on Ghostty or any other specific terminal emulator.

If you currently set the title from zsh, keep that behavior outside tmux only:

```zsh
if [[ -z "$TMUX" ]]; then
  precmd() {
    print -Pn '\e]2;%~\a'
  }
fi
```

Terminal notifications are optional and transition-based. Configure them with
`[customization.tmux.notifications]`:

| Field | Meaning |
|---|---|
| `enabled` | Enable terminal attention notifications (default `false`) |
| `protocol` | `osc-9` for a message-bearing desktop notification on supporting terminals, or `bell` for the portable terminal attention signal |
| `states` | State transitions that trigger a notification; supported values are `working`, `question`, `done`, `error`, and `idle` |
| `include-message` | Include the sanitized question/error text when available (default `true`) |

Notifications are emitted only from inside tmux and only on aggregate state
transitions. OSC 9 is supported by terminals including Ghostty and iTerm2 but
is not universal; choose `bell` when portability matters and configure the
terminal's bell attention behavior as desired. Title rendering remains
independent and non-fatal if notifications are unavailable.

## Security and limits

Agent-provided messages are stripped of terminal control characters and
truncated to `message-max-length`, then the complete title is bounded by
`max-length`. This prevents task text or a question from injecting terminal
escape sequences.