Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cline.bot/llms.txt

Use this file to discover all available pages before exploring further.

The SDK exposes two related event surfaces:
  • AgentRuntimeEvent from @cline/agents, delivered through agent.subscribe(listener).
  • AgentEvent / CoreSessionEvent from @cline/core, delivered through core session adapters and cline.subscribe(listener).
Use this page for event handling patterns. For event shapes, see Events reference.

​
AgentRuntime Events

const unsubscribe = agent.subscribe((event) => {
  if (event.type === "assistant-text-delta") {
    process.stdout.write(event.text ?? "")
  }
})

await agent.run("Explain this codebase")
unsubscribe()
AgentRuntimeEvent is the low-level event stream from the browser-compatible runtime.

​
Core / Host-Facing Agent Events

AgentEvent is the host-facing event shape used by @cline/core session orchestration. For direct Agent usage, prefer agent.subscribe(...) and AgentRuntimeEvent. Common host-facing event categories:
CategoryEventsUse for
Contentcontent_start, content_update, content_endText/reasoning/tool UI
Iterationsiteration_start, iteration_endProgress tracking
UsageusageToken/cost tracking
NoticesnoticeRecovery and status updates
Completiondone, errorFinal state and failure handling

​
ClineCore Session Events

Use cline.subscribe() for session-level events: 
const unsubscribe = cline.subscribe((event) => {
  console.log(event.type, event.sessionId)
})

await cline.start({ /* ... */ })
unsubscribe()
Pass a sessionId filter when you only want one session: 
const unsubscribe = cline.subscribe(listener, { sessionId })

​
Streaming UI Pattern

Subscribe to events to build real-time UIs: 
agent.subscribe((event) => {
  switch (event.type) {
    case "assistant-text-delta":
      onUpdate({ type: "text", content: event.text ?? "" })
      break
    case "tool-started":
      onUpdate({ type: "tool_start", content: event.toolCall.toolName })
      break
    case "tool-finished":
      onUpdate({ type: "tool_end", content: event.toolCall.toolName })
      break
    case "run-finished":
      onUpdate({ type: "done", content: event.result.status })
      break
  }
})
For a complete working example of streaming agent events to a browser via SSE, see the multi-agent example. It spawns multiple agents in parallel and streams each agent’s events to separate UI cards.

​
Usage Tracking Pattern

let totalTokens = 0

agent.subscribe((event) => {
  if (event.type === "usage-updated") {
    totalTokens = event.usage.inputTokens + event.usage.outputTokens
  }
})

​
Runtime State Snapshots

Call snapshot() when you need the current state: 
const snapshot = agent.snapshot()
console.log(snapshot.status, snapshot.iteration, snapshot.usage)