vibeshell AGENTS.md

VibeShell — Agent Guide

Overview

VibeShell is a modern SSH/SFTP desktop terminal built with Tauri 2 (Rust backend) and React 18 (TypeScript frontend). It supports multi-session SSH, SFTP file management, SSH tunneling, local shell, session recording, jump hosts, and AI tool integration.

Architecture

┌─────────────────────────────────────────────────────────┐
│  Frontend (React 18 + Vite 6 + TypeScript)              │
│  ├── Zustand stores (10 stores)                         │
│  ├── xterm.js terminal emulator                         │
│  └── Tailwind CSS (Tokyo Night theme)                   │
├─────────────────────────────────────────────────────────┤
│  IPC: Tauri invoke (frontend↔backend)                   │
│  IPC: Named pipe / Unix socket (CLI↔backend)            │
├─────────────────────────────────────────────────────────┤
│  Backend (Rust / Tauri 2)                               │
│  ├── SSH: russh 0.44 (async, non-Clone Handle/Channel)  │
│  ├── SFTP: russh-sftp                                   │
│  ├── DB: rusqlite (SQLite, bundled)                     │
│  ├── Async: tokio runtime                               │
│  └── Local Shell: portable-pty                          │
└─────────────────────────────────────────────────────────┘

Critical Knowledge

russh 0.44 Constraints

• client::Handle<H> and Channel<S> are NOT Clone
• Handle sharing: wrap in Arc<tokio::sync::Mutex<Option<Handle>>>
• Channel I/O: use channel.into_stream() → tokio::io::split() for bidirectional data

Frontend → Backend Communication

• All Tauri calls go through src/lib/tauri.ts → safeInvoke<T>(command, args)
• Returns InvokeResult<T> = { success: true; data: T } | { success: false; error: TauriError }
• For latency-sensitive input: use sendInputBatched() with RAF batching
• For fire-and-forget: use fireAndForgetInvoke()

Session Lifecycle

SessionManager.create_with_credentials()
  → SshClient.connect_password/connect_key()
  → SshClient.open_shell()
  → Session { input: mpsc::Sender, output: broadcast::Sender }
  → Frontend attaches via Tauri event listener