VibeAround Documentation

The @va/client package provides hand-written TypeScript definitions shared between the VibeAround web dashboard and the Tauri desktop UI. It serves as the TypeScript boundary for communicating with the VibeAround daemon.

Key components include:

• Route Builders: Located in src/routes.ts, these provide VA_PREFIX and base-URL builders that match the daemon's route layout (configured via .nest("/va", ...) in the server).
• Wire Schemas: Located in src/schemas.ts, these contain Zod schemas and inferred types for all HTTP and WebSocket wire shapes, along with constants like AGENT_IDS and PREVIEW_SHARE_TTL_SECS.
• Entry Point: src/index.ts acts as the barrel file for the package.

VibeAround is an all-in-one hub for AI coding agents designed to maintain your development workflow. It allows you to launch various AI agents (like Claude Code, Codex CLI, Gemini CLI, etc.) with specific model profiles and workspaces without manually editing their configuration files.

Key capabilities include:

• Agent Launching: Launch CLI and desktop agents (Claude, Codex) from a single UI with custom API endpoints and sessions.
• API Bridging: Translates between different AI API protocols (OpenAI, Anthropic, Gemini) using a local bridge.
• Session Continuity: Resume sessions across desktop, CLI, messaging apps, and web browsers.
• Host-side Tools: Provides web search capabilities to models that lack native search.
• Agent as API: Exposes local agents as compatible API endpoints for development and testing.

VibeAround is a local daemon system that exposes AI coding agents (like Claude Code or Codex) to multiple interfaces including IM apps (Telegram, Slack, etc.), web browsers, desktop apps, and remote terminals.

Key characteristics:

• Local-first: The daemon, agents, credentials, and code remain on your machine. It is not a cloud service.
• Agent Hosting: It does not replace coding agents; it hosts and routes existing agents (via the Agent Client Protocol) to different surfaces.
• Session Continuity: It tracks agent session IDs rather than chat transcripts, allowing you to move a conversation from a terminal to an IM app seamlessly.
• Unified Model Access: Uses API profiles and a built-in bridge to allow a single model provider account to power multiple different CLIs and OpenAI-compatible clients.

The va-client crate is organized into several modules based on their responsibility:

• Protocol Primitives: auth, endpoint, http, and operation modules contain shared primitives.
• Domain-Specific Builders: Modules like service, settings, runtime, launcher, sessions, profiles, workspaces, and previews provide request builders and wire models for specific domains.
• Operation Catalog: The ops/ module contains a ready-to-send operation catalog, grouped by server domain and re-exported from va_client::ops.
• Events: The events/ module contains WebSocket specs, PTY client frames, and typed event decoders.
• State Management: The state/ module provides display-oriented reducers intended for CLI, TUI, or desktop surfaces.

By default, all VibeAround data resides in ~/.vibearound/. You can override this location using the VIBEAROUND_DATA_DIR environment variable.

Key Directories and Files

• settings.json: Main user-editable configuration.
• agents.json: Cache of resolved agent executables.
• launch/profiles/: Saved launch profile JSON files.
• workspaces/: Default root for created workspaces.
• .cache/: Cache for channel attachments (safe to purge).
• logs/runtime/: Daily rolling log files (safe to purge).
• *.jsonl: Append-only event logs for workspaces, threads, and attachments (do not edit).
• auth.json, local-api-auth.json, local-agent-api-auth.json: Security tokens for the daemon and clients; these are rewritten every time the daemon starts.

The process module implements automated restart logic with the following behaviors:

• Exponential Backoff: Repeated OnCrash failures trigger an exponential backoff, starting from the configured delay and increasing up to a maximum of five minutes.
• Resetting the Budget: A successful heartbeat or a manual start/restart operation resets the failure budget/backoff timer.
• Restart vs. Stop Priority: A Stop operation takes precedence over a Restart. If a cleanup operation is in progress, the system waits to re-acquire the barrier, publishes Stopped, and reaps any replacement processes that may have raced the publication.
• Agent vs. Plugin Policies:
  • Plugins: Subject to heartbeat watchdogs.
  • Agents: Designed to crash loudly. They use a Never restart policy, meaning the owning thread is responsible for deciding how to handle the crash.

Outbound Events

Outputs for web routes are dispatched as JSON ChatEvent objects to every connection registered for that route. Events include message chunks, tool status, permission cards, and TurnStatus. An inactive turn status (TurnStatus { active: false }) serves as the public completion boundary.

Host Residency and Eviction

Web Chat does not have a route-specific process idle deadline. Closing a tab, disconnecting a socket, or an inactive turn does not unload the host or close the thread.

The host follows a warm-thread pool policy: it remains resident unless a new host puts the pool over its soft limit, making this thread a candidate for eviction. If evicted, the ThreadRuntime and session are retained, allowing output replay and resumption upon reopening.

OpenCode Remote Access is designed for several specific developer workflows:

• Multi-Agent Workspaces: Managing a single workspace that includes multiple coding agents (e.g., OpenCode alongside Claude Code, Codex CLI, or Gemini CLI).
• Cross-Device Continuity: Accessing OpenCode sessions from a phone or a browser terminal to continue work while away from a primary workstation.
• Local Resource Access: Workflows that require access to local development servers, local package caches, or resources on a private network.
• Output Previews: Sessions that require viewing generated web, Markdown, or HTML outputs via Live Preview.

VibeAround can provide web search capabilities to models that do not offer them natively. It replaces provider-native web_search with a local search runtime using the va-search-tool project.

Search Sources Supported:

• Exa
• Tavily
• Grok / xAI
• Brave Search

Usage Modes for va-search-tool:

• VibeAround Plugin: Runs as a supervised plugin over stdio.
• CLI: Run standalone for one-off searches using va-search-tool search ....
• HTTP Service: Expose a local /v1/search service for external integrations.

Decide whether to use Launch (native terminal) or Hosted (IM/web chat) based on your workflow requirements:

VibeAround provides two ways to run Claude Code:

1. Native Path: Using Claude Code directly with its native Anthropic login. Use this if your setup is already stable.
2. Profile Path: Using VibeAround provider profiles and API Bridge routes. This allows you to run Claude Code against third-party provider keys, which is useful for repeatable routing, aliases, or bridge translation without requiring a specific coding-plan subscription.

To implement the profile-based routing, refer to the claude-code-switcher.md guide.

If you have tmux installed, the VibeAround dashboard can attach to an existing tmux session instead of spawning a fresh shell. In this configuration, the PTY child process is tmux attach. The behavior of other clients is controlled by the tmux.detach_others setting. The communication protocol (WebSockets and byte piping) remains identical to the standard PTY flow.

# View available tmux sessions via the CLI
va tmux sessions