# AI Agents

Nana recognizes AI coding agents running in its terminals and shows whether
each one is working, waiting for you, or done. It needs no setup, hooks, or
plugins, and works while no app is open.

## Supported agents

Antigravity, Claude Code, Codex, Copilot, Cursor, Droid, Grok, Kiro, Oh My Pi,
OpenCode, Pi, and Xal.

The server spots them from the running program and what's on screen.
Recognition is best effort.

Oh My Pi detection reads its OSC terminal-title run state: a spinner while
working, `!` when waiting, and `>` when idle. It also recognizes optional OSC
progress reports, `⎋` working messages, and the older `Working… [esc]` spinner.
In `omp --print` sessions, a final non-empty
`Working...` line signals work; once output follows it, that progress line
no longer keeps the session busy. Detection uses terminal escape sequences
and screen text, so disabling or customizing these signals can affect recognition.

For foreground `omp` and `oh-my-pi` processes, automatic terminal titles omit
the leading `π ` prefix. The provider icon remains visible, and custom tab
titles are unchanged.

## States

| State | Meaning |
| --- | --- |
| Working | The agent is busy. |
| Waiting | The agent needs your input. |
| Idle | The agent is done or not doing anything. |

Tabs, worktrees, and projects show the agent's icon and state. When several
agents run, "waiting" wins.

## Notifications

The desktop app sends a system notification when an agent needs your attention
or finishes working, as a Windows toast.

- No notification is shown for the pane you are looking at, or for detached
  terminals.
- Looking at the terminal clears the alert in every app.
- Clicking a notification jumps to its pane.
- Only one app notifies, so alerts are never doubled.
- Turn notifications off in **Settings → System → Notifications → Nana**.
- A toast belongs to the installed app, which the installer registers
  under Nana's own identity; clicking one starts Nana if it is not running.
  First use initializes Windows' notification entry silently; it does not turn
  notifications back on if you have disabled them.

Alerts live in memory on the server, at most one per terminal. Restarting the
server clears them.

## Agents Focused sidebar

Choose **Agents Focused** from the sidebar layout menu to list only the tabs
that run an agent.

## From a shell and kibbles

- `nana activity list --json` prints agent status and unread alerts as JSON.
  `nana activity ack <event-id>` clears alerts.
- Kibbles get the `agent.status` event and `nana.agents.list()`. See
  [Events](https://nana.areshk.dev/docs/extensions/events.md).