Internals
Documentation for debugging VibeAround and changing its code. Two complementary cuts of the same runtime:
Documentation for debugging VibeAround and changing its code. Two complementary cuts of the same runtime:
- Flows follow one request through time — every hop from entry to exit, with code anchors and failure tables. Start here to trace behavior.
- Modules describe one component in space — responsibility, key types, interactions, invariants you must not break, and known debt. Start here to modify code.
They cross-link where a flow passes through a module. The reader-level "why is it designed this way" story lives in architecture/; hard numbers live in timers and limits.
Flows
| Flow | Path it follows |
|---|---|
| IM message | Platform event → plugin → sharded queue → thread → agent → streamed reply. The trunk flow — read it first |
| Web chat | WebSocket event → session intent → the same prompt path |
| Permission | Agent request → oneshot registration → card → tap → agent resumes |
| Bridge request | Client dialect → decode → model mapping → upstream → streamed back |
| Native launch | Profile → launch JSON → va-launch → terminal spawn |
| Handover | Code issued → /pickup → external session bound → route attached |
| Web terminal | Browser xterm ↔ WebSocket ↔ pseudo-tty |
Modules
Fixed structure per page: responsibility · key types · interactions · invariants · known debt.
| Module | One-liner |
|---|---|
| channels | Message transport and routing between surfaces and threads |
| workspace | Conversation state: workspaces, threads, attachments (event-sourced) |
| process | Subprocess supervision: spawn, respawn, watchdog, cleanup |
| agent | One ACP connection to a coding CLI + launch preparation |
| profiles | Provider catalog, profile store, launch rendering |
| pty | Pseudo-terminal sessions behind the web terminal |
| previews | Live preview registry, owner/share URLs |
| tunnels | ngrok / localtunnel / cloudflare publishing |
| auth | Daemon token and pairing codes |
| server | The axum shell: routes, WebSockets, MCP, bridge, boot/shutdown |
Subsystem deep-dives
Cross-cutting subsystems that span several modules get a dedicated page:
| Page | Covers |
|---|---|
| Launch | The four launch paths, env assembly and injection per path, per-OS terminal handling, argument sources, desktop vs CLI producers |
Related material
- Known defects and planned refactors:
reports/architecture-review-remediation-2026-07-04.md(module pages' "known debt" sections link to its items). - Rustdoc module headers in the source are the finest-grained authority; these pages are maps, not replacements.
Troubleshooting and FAQ
Symptoms first, concepts second. When in doubt, start with va doctor — it checks endpoint, auth, and server health in one shot.
Launch subsystem
Everything about starting an agent process, in one place: the four launch paths, how environment variables are assembled and injected on each, per OS terminal handling, argument sources, and where desktop and CLI prod...