When you let Claude control your desktop, the first thing that goes wrong is the UI freezing the instant the model starts spitting out tokens. A naïve client.messages.create() call blocks the event loop, so the text field stops repainting, the cancel button never fires, and users think the app has crashed. The fix is to treat the LLM as a streaming data source and push each fragment onto the UI from a dedicated, asyncio‑aware worker.

The real pain shows up a few turns later: a tool call fails, the agent’s internal “thoughts” diverge from what the user sees, and you’re left with a mismatched conversation history that can’t be recovered without a full restart. The pattern that keeps the conversation loop sane, respects Anthropic’s rate limits, and still feels instant to the human a user is a deliberately architected state machine backed by an async‑first GUI layer.

—

⚡ TL;DR — Key takeaways
  • Use an asyncio worker thread (or QThread) to stream Claude responses into a QTextEdit without blocking.
  • Keep a single source of truth for conversation state; UI components subscribe via Qt signals.
  • Wrap every tool call in an idempotent, user‑confirmed wrapper that can roll back on failure.
  • Implement exponential backoff + token bucket to stay inside RPM/TPM limits.
  • Profile token‑stream rendering and use httpx.AsyncClient with keep‑alive connections for low latency.

—

Before you start: Python ≥ 3.12, Anthropic SDK v0.30+, PyQt6 v6.7, httpx v0.27 (async), a Claude 3.5 Sonnet API key, and basic familiarity with asyncio and Qt signal/slot mechanics.

How to stream Claude’s API response in real-time to a PyQt6 QTextEdit without blocking the UI?

A 2026 Claude Agent UI requires a non‑blocking architecture using asyncio with PyQt6/Tkinter. Implement a dedicated worker thread for streaming API responses to avoid UI freeze. Core patterns include a managed conversation loop, state synchronization, and graceful timeout recovery for robust human‑agent collaboration beyond simple chat.

System architecture & workflow

The diagram below shows the high‑level data flow. The Agent Core lives inside an asyncio task that talks to Claude, the State Store holds the canonical conversation, Qt UI subscribes to state changes via signals, and a Rate‑Limiter sits between the UI and the SDK.

flowchart LR
    UI[Qt UI] -->|user input| Queue[Async Request Queue]
    Queue -->|pop| Agent[Agent Core (asyncio)]
    Agent -->|stream chunk| Streamer[Async Stream Worker]
    Streamer -->|emit| UI
    Agent -->|tool call| ToolMux[Tool‑Use State Machine]
    ToolMux -->|result| Agent
    Agent -->|update| Store[State Store (single source of truth)]
    Store -->|notify| UI
    UI -->|rate‑limit check| Limiter[Token Bucket / Leaky Bucket]
    Limiter -->|allow| Agent
  • UI → Queue: Every user message is placed on an asyncio.Queue.
  • Agent Core: Pulls from the queue, sends a messages.stream request, and forwards each MessageDelta to the Streamer.
  • Streamer: Runs in a QThread, converts async chunks into Qt signals, and updates the QTextEdit.
  • Tool‑Use State Machine: Detects tool_calls in the response, validates them, and optionally asks the user for confirmation before dispatching to the Computer Use API.
  • State Store: A tiny Pydantic model that holds the full message list; any mutation triggers a stateChanged Qt signal.
  • Rate Limiter: Guarantees we never exceed Anthropic’s RPM/TPM quotas; it throttles the queue rather than the UI.

Core technical stack for 2026 Claude UI agents

Anthropic Python SDK (≥ v0.30)

The SDK now ships a native async client that yields MessageDelta objects, each carrying either content or tool_calls. Use the stream=True flag to get an async generator:

# anthropic_sdk_v0.30_client.py
from anthropic import Anthropic
from anthropic.types import MessageDelta

client = Anthropic(api_key="YOUR_ANTHROPIC_KEY")

async def stream_message(messages: list[dict]) -> AsyncGenerator[MessageDelta, None]:
    async for delta in client.messages.stream(
        model="claude-3-5-sonnet-202410",
        max_tokens=1024,
        messages=messages,
        temperature=0.2,
        stream=True,
    ):
        yield delta

Asyncio + Qt event loop

Qt’s own event loop is not asyncio‑aware, but we can bridge them with a QThread that runs an asyncio.run loop. The thread pushes data to the main thread through pyqtSignal.

# worker_thread.py
from PyQt6.QtCore import QObject, pyqtSignal, QThread
import asyncio
import logging

class StreamWorker(QObject):
    chunk_received = pyqtSignal(str)          # UI slot updates QTextEdit
    finished = pyqtSignal()
    error = pyqtSignal(str)

    def __init__(self, messages):
        super().__init__()
        self._messages = messages
        self._cancel_requested = asyncio.Event()

    async def _run(self):
        try:
            async for delta in stream_message(self._messages):
                if delta.type == "content_block_delta":
                    self.chunk_received.emit(delta.delta.text)
                elif delta.type == "tool_use":
                    # forward tool payload to the UI for confirmation
                    self.chunk_received.emit(f"\n[Tool call: {delta.id}]")
                if self._cancel_requested.is_set():
                    break
            self.finished.emit()
        except Exception as exc:
            logging.exception("Streaming error")
            self.error.emit(str(exc))

    def start(self):
        asyncio.run(self._run())

    def cancel(self):
        self._cancel_requested.set()

In the main window we spin up a QThread, move the StreamWorker there, and connect the signals:

# main_window.py
from PyQt6.QtWidgets import QApplication, QWidget, QVBoxLayout, QTextEdit, QPushButton
from PyQt6.QtCore import QThread
import sys

class ClaudeGui(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Claude Desktop Agent")
        self.layout = QVBoxLayout(self)

        self.display = QTextEdit(self)
        self.display.setReadOnly(True)
        self.layout.addWidget(self.display)

        self.input_box = QTextEdit(self)
        self.layout.addWidget(self.input_box)

        self.send_btn = QPushButton("Send", self)
        self.send_btn.clicked.connect(self.start_conversation)
        self.layout.addWidget(self.send_btn)

        self.thread = None
        self.worker = None

    def start_conversation(self):
        user_msg = self.input_box.toPlainText().strip()
        if not user_msg:
            return
        self.display.append(f"<b>You:</b> {user_msg}")
        self.input_box.clear()
        # push to async queue (handled elsewhere)
        ConversationManager.enqueue(user_msg)
        self._launch_worker()

    def _launch_worker(self):
        if self.thread and self.thread.isRunning():
            return  # avoid duplicate workers

        self.thread = QThread()
        self.worker = StreamWorker(ConversationManager.current_state())
        self.worker.moveToThread(self.thread)

        self.worker.chunk_received.connect(self.display.insertPlainText)
        self.worker.finished.connect(self.thread.quit)
        self.worker.error.connect(self._show_error)

        self.thread.started.connect(self.worker.start)
        self.thread.start()

    def _show_error(self, msg: str):
        self.display.append(f"<span style='color:red'>Error: {msg}</span>")

The state synchronization problem & solutions

Every time a tool call finishes, we must rewind the conversation state to the point before the call, then re‑inject the resolved result. A clean way is to keep the entire message list in a Pydantic model (ConversationState) and expose a clone_and_append method that returns a fresh copy for the next API round.

# conversation_state.py
from pydantic import BaseModel, Field
from typing import List, Dict

class ConversationState(BaseModel):
    messages: List[Dict] = Field(default_factory=list)

    def add_user(self, content: str):
        self.messages.append({"role": "user", "content": content})
        return self.clone()

    def add_assistant(self, content: str):
        self.messages.append({"role": "assistant", "content": content})
        return self.clone()

    def add_tool_result(self, tool_id: str, result: str):
        self.messages.append({
            "role": "assistant",
            "tool_result": {
                "tool_call_id": tool_id,
                "content": result
            }
        })
        return self.clone()

    def clone(self):
        return ConversationState(messages=self.messages.copy())

The UI never mutates ConversationState directly; it only *observes* stateChanged signals. This eliminates race conditions where two concurrent user inputs would append to the same list.

Rate‑limit handling

Anthropic’s limits are expressed as RPM (requests per minute) and TPM (tokens per minute). The following decorator implements an exponential back‑off plus a token bucket:

# ratelimit.py
import asyncio
import time
from functools import wraps

MAX_RPM = 30
MAX_TPM = 120_000
TOKEN_REFILL_RATE = MAX_TPM / 60  # tokens per second

class TokenBucket:
    def __init__(self, capacity, refill_rate):
        self.capacity = capacity
        self.tokens = capacity
        self.refill_rate = refill_rate
        self.last = time.monotonic()
        self.lock = asyncio.Lock()

    async def consume(self, amount):
        async with self.lock:
            now = time.monotonic()
            elapsed = now - self.last
            self.tokens = min(self.capacity, self.tokens + elapsed * self.refill_rate)
            self.last = now
            if self.tokens >= amount:
                self.tokens -= amount
                return True
            return False

bucket = TokenBucket(capacity=MAX_TPM, refill_rate=TOKEN_REFILL_RATE)

def rate_limited(coro):
    @wraps(coro)
    async def wrapper(*args, **kwargs):
        attempt = 0
        while True:
            if await bucket.consume(kwargs.get("max_tokens", 256)):
                try:
                    return await coro(*args, **kwargs)
                except Exception as e:
                    if "429" in str(e) and attempt < 5:
                        backoff = 2 ** attempt
                        await asyncio.sleep(backoff)
                        attempt += 1
                        continue
                    raise
            else:
                await asyncio.sleep(0.1)
    return wrapper

Wrap the SDK call:

@rate_limited
async def safe_stream(messages):
    return await client.messages.stream(
        model="claude-3-5-sonnet-202410",
        max_tokens=1024,
        messages=messages,
        temperature=0.0,
        stream=True,
    )

GUI Toolkit showdown & Python implementation

FeaturePyQt6TkinterTauri (Rust+WASM)
Native async support✅ via QThread + asyncio❌ requires loop.create_task hack✅ via web workers, but adds Rust build complexity
Rich widgets (tree, progress bar)✅Limited✅ (via web components)
Desktop‑level OS access (file dialogs, clipboard)✅✅✅ (via Rust bridge)
Learning curveModerateLowHigh (Rust + JS)
Production track record (2026)Strong (used in 300+ AI agents)NicheGrowing fast in “cross‑platform AI desktop” space

For the purpose of this tutorial we stick with PyQt6 because it gives us:

  • built‑in signal/slot threading model,
  • a mature QTest‑based automation layer for the Computer Use API,
  • and native system dialogs that the agent can safely invoke.

Step 1: Scaffolding an asyncio‑aware main window

The skeleton below puts the ConversationManager (a thin async façade) behind a Qt‑friendly façade.

# conversation_manager.py
import asyncio
from collections import deque
from conversation_state import ConversationState

class ConversationManager:
    _queue: asyncio.Queue = asyncio.Queue()
    _state = ConversationState()

    @classmethod
    def enqueue(cls, user_msg: str):
        cls._state = cls._state.add_user(user_msg)
        cls._queue.put_nowait(cls._state.clone())

    @classmethod
    async def next_state(cls) -> ConversationState:
        return await cls._queue.get()

    @classmethod
    def current_state(cls) -> ConversationState:
        return cls._state.clone()

Now wire it to the UI (lightly edited from the earlier snippet). The crucial part is that start_conversation

Written by

’m Nilesh, a Software Development Engineer with 2+ years of experience, specializing in Go, JavaScript, Python, Docker, Kubernetes, Git, Jenkins, microservices, and system design (LLD/HLD), backed by a strong foundation in data structures and algorithms. Alongside my engineering journey, I bring 4+ years of hands-on experience in SEO, where I’ve worked extensively on content strategy, keyword research, technical SEO, and organic growth, helping products and businesses scale efficiently by aligning solid technology with search-driven performance.