vibe-async

Vibe Async Patterns

Conventions for async and concurrent code in Vibe. Apply when touching the agent loop, the app server's 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 event loop. The app server serves every session and its RPCs from one event loop, so anything blocking (large JSON/Pydantic serialization, os.fsync, subprocess calls, recursive globs) stalls the clients — 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-client communication

• Route core-to-client communication through vibe.app_server. Server requests such as approvals and user input become canonical Vibe events; neither the clients 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.