Agent attention titles

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:

[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:

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

Supported placeholders are:

Use {agent_suffix} when the same format applies to both agent and non-agent windows. It includes its own separator and omits the entire suffix when no harness is active, avoiding dangling punctuation:

format = "{state_symbol}{repository}{agent_suffix}"

repository-style controls the value of {repository}:

[customization.tmux.title]
repository-style = "basename" # aibox
# repository-style = "full"   # projectious-work/aibox

The full form is derived from the configured Git remote path, not from a forge API. It therefore works with HTTPS and SSH remotes on GitHub, GitLab, Gitea, Forgejo, and compatible self-hosted instances. Nested namespaces are preserved (for example, group/platform/repository). If no usable remote is configured, both styles fall back to the repository root directory name.

agent-style controls the value of {agent}:

[customization.tmux.title]
agent-style = "basename" # gpt-5.6-sol
# agent-style = "full"   # gpt-5.6-sol low

The full form appends the active reasoning-effort level when the harness exposes one reliably. Codex resolves both values from current local thread metadata, Claude reads its hook payload and transcript, Gemini reads the documented BeforeModel request, and OpenCode reads model-bearing plugin events. Copilot and Cursor consume model metadata when their hook payload or transcript provides it. Aider, Continue, Hermes, and Tau use their launch-time configuration as a guarded fallback; an explicit runtime signal supersedes it after an in-session model switch.

Every harness can also supply an exact runtime identity with --agent MODEL --effort LEVEL or the AIBOX_AGENT_NAME and AIBOX_AGENT_REASONING_EFFORT environment variables. {harness} remains the CLI harness reporting the lifecycle event. Explicit arguments and environment variables take precedence over automatic detection.

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:

Current generated integrations:

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. Codex permission replies resume the current turn without submitting a new prompt, so aibox also maps Codex pre- and post-tool lifecycle events to working; this clears the question marker when approved work continues.

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

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:

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

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

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.