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.
—
- 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.AsyncClientwith 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.streamrequest, and forwards eachMessageDeltato the Streamer. - Streamer: Runs in a
QThread, converts async chunks into Qt signals, and updates theQTextEdit. - Tool‑Use State Machine: Detects
tool_callsin 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
stateChangedQt 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
| Feature | PyQt6 | Tkinter | Tauri (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 curve | Moderate | Low | High (Rust + JS) |
| Production track record (2026) | Strong (used in 300+ AI agents) | Niche | Growing 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