Vibe Async Patterns

Conventions for async and concurrent code in Vibe. Apply when touching the agent loop, Textual event loop, HTTP clients, streaming, or any async code.

Runtime

• asyncio is the orchestration runtime in the agent loop and tool execution. Use asyncio.create_task + queues for concurrent work, not blanket gather.

Blocking work

• Never run CPU-heavy or I/O-bound code on the UI thread. The Textual TUI and the agent loop share one event loop, so anything blocking (large JSON/Pydantic serialization, os.fsync, subprocess calls, recursive globs) freezes the UI — offload it with asyncio.to_thread.
• Async file wrappers don't make blocking syscalls non-blocking.
• Use anyio.Path for file I/O on async paths.

Streaming

• Streaming surfaces return AsyncGenerator[Event, None], not coroutines.

Core-to-TUI communication

• Route core-to-TUI communication through vibe.app_server. Server requests such as approvals and user input become canonical Vibe events; neither the TUI nor app server may register callbacks, listeners, or message observers directly on the agent loop.

HTTP clients

• When Vibe owns an HTTP client, use VibeAsyncHTTPClient from vibe.utils.http instead of httpx.AsyncClient so proxy env vars are handled consistently.
• Its CIDR NO_PROXY matching applies only to IP-literal request hosts; do not resolve DNS before proxy selection.
• Mock outbound HTTP with respx in tests.