Skip to content
raven.
Sign inDownload
Menu

Docs / Agent awareness

Agent detection and state

raven-term treats every pane as probably-an-agent. It identifies the CLI in the foreground, reads the screen to derive its state, accepts richer metadata from hooks, and resumes agent sessions across restarts.

Detection

Each pane's foreground job is walked and matched against known agent CLIs — including agents launched through wrappers, where the process is node but the argv reveals claude. Detection re-runs on a short TTL off the render path, so it costs nothing per frame. Recognized today:

claudecodexgeminicursorclineopencodegithub-copilotkimikirodroidamppiantigravitygrokhermesqoder

Screen-derived state

Beyond which agent, the daemon derives what it's doingby reading the visible tail of the pane — per-agent heuristics tuned to each CLI's chrome. A Claude Code pane showing a spinner above its prompt box is working; a permission prompt is waiting for you; a bare prompt is idle. The state feeds the sidebar dots, the agents CLI query, and the notch.

  • Idle — no turn or decision is pending.
  • Working— a turn is in flight (spinner chrome, "esc to interrupt").
  • Waiting for you— the agent is asking permission or a question and can't proceed.

A non-agent foreground job (a build, a test run) sets a busy-spinner cue on the pane instead, so long-running plain commands are visible at a glance too.

Hook-reported metadata

Detection covers the common case; hooks can do better. Any process can publish a custom status line, space title, or display name for a pane through raven-term report-agent. Each field is tracked per source, newest report wins, and an optional TTL auto-clears a value — so a Stop hook can publish "waiting on user" and let it expire without a follow-up call.

# from a Claude Code hook
raven-term report-agent --source claude-hook \
  --status "waiting on user" --ttl-ms 30000

# a wrapper CLI renaming its pane
raven-term report-agent --source planner \
  --display-agent "claude (planner)"

Progress and bells

Panes honor OSC 9;4progress reports and terminal bells. Progress percentages and bell events ride the state channel up to the notch, which is how "which agent finished?" gets answered without scanning panes.

Agent resume

With session restore on, a pane that was running Claude Code or Codex comes back as that agent, not as an empty shell: the daemon records which agent each pane ran and relaunches it with claude --resume <id> or codex resume <id> in the original working directory.

Something missing? Help improve these docs