Agents

When you run AI coding agents inside taiku terminals, the session automatically detects them. This is not a passive label. taiku watches terminal output in real time, identifies which agent is running, tracks its status transitions, and surfaces that information across the entire session UI. Every collaborator sees which terminals are autonomous, which are waiting for input, and which have finished their work.

Why agent detection matters

Consider a common scenario: you have three Claude Code instances running in separate terminals. One is refactoring a database migration, another is writing tests, and a third is debugging a CI failure. Without agent tracking, you would need to manually scan each terminal's output to figure out what is happening. Worse, if one agent hits a permission prompt and stops, you might not notice for minutes.

taiku solves this by treating agent activity as a first-class concept. Each agent-running terminal gets a status badge visible in the tile titlebar. When an agent transitions from "running" to "waiting" (because it needs approval or hit a confirmation prompt), taiku can play an audio ping, flash the terminal tile, or send a native OS notification. You never lose track of what your agents are doing.

Supported agents

taiku currently recognizes these AI coding agents:

• Claude
• Codex
• OpenCode

Detection happens continuously as terminal output arrives. If you start an agent after a session is already running, taiku picks it up as soon as it prints a recognized pattern. If the agent exits and you start a different one in the same terminal, the detection updates accordingly.

Agent status lifecycle

Once detected, each agent is tracked through a series of status states:

Running: The agent is actively producing output. This is the default state when an agent is first detected and terminal data is flowing.

Thinking: The agent is processing but has not yet produced output. This typically maps to model inference time when the terminal is quiet but the agent process is still active.

Tool use: The agent is executing a tool call (reading files, running commands, making edits). taiku infers this from output patterns characteristic of tool execution.

Waiting: The agent has stopped and is asking for user input. This is the most important status transition because it means human attention is required.

Completed: The agent has indicated it finished its task, via patterns like Task completed, All done, or Session ended.

Idle: The agent was detected previously but has not produced output recently.

These status transitions drive the notification system. You can configure notifications in Settings to use sound, visual flash, or both when an agent enters the "waiting" state.

What gets surfaced in the UI

Agent detection manifests in several places across the session:

Tile titlebars show a colored status dot next to the shell name. A green dot means the agent is actively running, yellow means it is waiting for input, blue means it is thinking, orange means tool use, and gray means idle or completed. Collaborators can see at a glance which terminals have active agents.

Notifications fire when an agent needs attention. taiku supports three notification modes (configurable in Settings): an audio ping (an 880Hz-to-660Hz sine sweep), a visual flash on the terminal tile, or both. Native OS notifications are also sent, which works in both the browser (via the Notification API) and the desktop app (via Tauri's native notification plugin).

The Agent Monitor plugin provides a dedicated sidebar panel that aggregates all agent activity into a single view. More on this below.

The Agent Monitor plugin

The built-in Agent Monitor plugin (taiku.agent-monitor) is the primary interface for understanding agent activity across a session. It opens as a sidebar panel and shows:

• A summary bar at the top with counts of active and total agents, plus cumulative session cost and all-time cost tracking.
• A list of every detected agent, sorted by most recently active. Each row shows the agent type (Claude, Codex, etc.), its current status, elapsed time since last activity, and running cost if token usage data is available.
• Hovering over an agent row reveals a tooltip with detailed metadata: shell ID, session ID, model name, event count, and a full token usage breakdown (input, output, cached tokens, and cost).
• Clicking an agent row opens the agent session overlay, which provides a deeper view of that agent's activity history.

Open the Agent Monitor with Cmd+Shift+A (or Ctrl+Shift+A on Linux/Windows), or click its toolbar icon.

The plugin tracks cumulative cost across sessions using per-user persistent storage. Even after a session ends, your all-time cost counter carries over to the next one.

How agent events flow through the system

Under the hood, agent detection works through a layered event pipeline:

1. Terminal output scanning: As each chunk of terminal data arrives, the processTerminalOutput function in agents.ts runs it against the detection patterns. If an agent is identified or a status change is detected, the agent store is updated.

2. OSC escape sequences: For richer integration, agents can emit Operating System Command (OSC) escape sequences that taiku intercepts. These carry structured data like session IDs and instance identifiers, enabling precise tracking even when multiple agent instances run in the same tmux session.

3. Session mapping: When an agent is detected, taiku maintains a mapping from agent session IDs to shell IDs. This uses a FIFO queue system: when a shell emits an agent-start signal, the shell is enqueued, and when a tracker session event arrives, the oldest matching shell is popped and bound to that session. A 5-second drift tolerance ensures the mapping stays accurate even under timing variations.

4. Plugin event broadcasting: Agent status changes are broadcast as agent_status events through the plugin event system. Any plugin with the agent.events permission can subscribe to these events and build custom visualizations or automations on top of them.

A plugin consuming agent events receives payloads like this:

{
  "type": "agent_status",
  "data": {
    "shellId": 3,
    "agentType": "claude",
    "status": "waiting",
    "instanceId": "abc123",
    "sessionId": "uuid-here",
    "model": "claude-opus-4-6",
    "tokenUsage": {
      "input": 125000,
      "output": 8400,
      "cached": 98000,
      "cost": 1.23
    },
    "eventCount": 47
  },
  "timestamp": 1711234567890
}

Multi-agent and subagent tracking

taiku handles scenarios where multiple agents run in the same terminal, which is common with tmux-based workflows. Each agent instance gets a unique instance ID (derived from the tracked process identity), so taiku can distinguish between three Claude instances in three tmux panes within a single terminal tile.

Parent session IDs enable subagent tracking. When an agent spawns a child agent (for example, Claude Code launching a subagent for a parallel task), the parent session ID links the two, allowing the Agent Monitor to show the relationship between them.

The resolveSessionPanelAgent function uses a priority order when multiple agents exist on one shell: exact instance match first, then matching agent type, then the first agent in the list. This ensures the UI always shows the most relevant agent for a given context.

Notification configuration

Agent notifications are controlled through Settings. The options are:

• Mode: "sound" plays the audio ping, "flash" pulses the terminal tile border, "both" does both. You can also disable notifications entirely.
• Volume: A slider from 0 to 100 controls the audio ping volume. The ping uses the Web Audio API to synthesize a short two-tone (A5 to E5) descending sweep.
• Terminal highlighting: When enabled, agent-running terminals get a subtle visual highlight in the workspace, making them easy to spot even without the Agent Monitor panel open.

Notifications are deduplicated per shell with a 10-second cooldown, so a chatty agent that repeatedly prints prompt-like output won't flood you with pings.

See Built-in Plugins for the full list of monitoring plugins that pair well with agent-heavy sessions.