From c65000ae7fa22ae4507bcbf1f96621d8dd82991a Mon Sep 17 00:00:00 2001 From: Ashlee Radka Date: Wed, 18 Feb 2026 08:30:05 -0500 Subject: [PATCH] docs: audit and fix READMEs across the repo - Root README: add iOS to architecture description, update repo structure tree (add benchmarking/, .claude/, fix clients/ description), remove dead assistant/README.md link - clients/README.md: remove stale PR number references and outdated "Migration from Single-Platform" section - clients/ios/README.md: standardize daemon startup to canonical CLI entry point (src/index.ts daemon start) - clients/macos/README.md: clarify iOS build options (Xcode recommended), standardize daemon startup command, remove inaccurate bun run dev claim Co-Authored-By: Claude Opus 4.6 --- README.md | 15 +++++++++------ clients/README.md | 15 ++------------- clients/ios/README.md | 4 ++-- clients/macos/README.md | 7 ++----- 4 files changed, 15 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 1938b7ed448..0cb08b6ee81 100644 --- a/README.md +++ b/README.md @@ -4,19 +4,22 @@ AI-powered assistant platform by Vellum. ## Architecture -The platform has two main components: +The platform has three main components: -- **Assistant runtime** (`assistant/`): Bun + TypeScript daemon that owns conversation history, attachment storage, and channel delivery state in a local SQLite database. Exposes an HTTP API consumed by the gateway. +- **Assistant runtime** (`assistant/`): Bun + TypeScript daemon that owns conversation history, attachment storage, and channel delivery state in a local SQLite database. Exposes a Unix domain socket (macOS) and optional TCP listener (iOS) for native clients, plus an HTTP API consumed by the gateway. +- **Native clients** (`clients/`): Swift Package with macOS and iOS apps sharing ~45-50% of code via `VellumAssistantShared`. The macOS app is a menu bar assistant with computer-use (accessibility + CGEvent). The iOS app is a chat client supporting standalone mode (direct Anthropic API) and connected-to-Mac mode (TCP proxy through the daemon). - **Gateway** (`gateway/`): Standalone Bun + TypeScript service that owns Telegram integration end-to-end. Receives Telegram webhooks, routes to the correct assistant via static settings, forwards to the assistant runtime, and sends replies back to Telegram. Optionally acts as an authenticated reverse proxy for the assistant runtime API (client → gateway → runtime). ## Repository Structure ``` / -├── assistant/ # Bun-based assistant runtime -├── clients/ # Desktop clients +├── assistant/ # Bun-based assistant runtime (daemon, CLI, HTTP API) +├── clients/ # Native clients (macOS menu bar app + iOS chat app) ├── gateway/ # Telegram gateway service -├── scripts/ # Utility scripts +├── benchmarking/ # Load testing scripts (gateway webhook/proxy benchmarks) +├── scripts/ # Utility scripts (publishing, tunneling) +├── .claude/ # Claude Code slash commands and workflow tools └── .github/ # GitHub Actions workflows ``` @@ -44,7 +47,7 @@ See [.githooks/README.md](./.githooks/README.md) for more details about availabl ## Assistant Runtime -The assistant runtime lives in `/assistant`. See [assistant/README.md](./assistant/README.md) for details. +The assistant runtime lives in `/assistant`. ```bash cd assistant diff --git a/clients/README.md b/clients/README.md index 1a9c9936f28..a3c0d30e369 100644 --- a/clients/README.md +++ b/clients/README.md @@ -124,8 +124,8 @@ Depends only on `VellumAssistantShared` (no macOS frameworks). **~45-50% code reuse** between macOS and iOS achieved through: 1. **Shared IPC layer** - Both platforms communicate with daemon (different transport) -2. **Shared design system** (PR 2) - Tokens and components with conditional compilation -3. **Shared ViewModels** (PR 3) - ChatViewModel, message models work on both platforms +2. **Shared design system** - Tokens and components with conditional compilation +3. **Shared ViewModels** - ChatViewModel, message models work on both platforms **Platform-specific**: - **UI frameworks**: AppKit (macOS) vs UIKit (iOS) @@ -133,17 +133,6 @@ Depends only on `VellumAssistantShared` (no macOS frameworks). - **Screen recording**: ScreenCaptureKit (macOS) vs ReplayKit (iOS) - **App lifecycle**: NSStatusItem (macOS) vs UIScene (iOS) -## Migration from Single-Platform - -This structure was introduced in PR #1821 (iOS shared library foundation). Before this: -- `clients/macos/Package.swift` - Single-platform package -- `clients/macos/vellum-assistant/IPC/` - macOS-only IPC code - -After migration: -- `clients/Package.swift` - Multi-platform package -- `clients/shared/IPC/` - Cross-platform IPC code -- All 25+ IPC message types have `public` access and explicit `public init()` - ## Development ### Adding Shared Code diff --git a/clients/ios/README.md b/clients/ios/README.md index d49fde1ae3d..e65ab40c16c 100644 --- a/clients/ios/README.md +++ b/clients/ios/README.md @@ -103,10 +103,10 @@ Requires the Vellum daemon running on your Mac (either as the macOS desktop app ```bash cd assistant # For simulator (localhost only): -VELLUM_DAEMON_TCP_ENABLED=1 bun run src/daemon/main.ts +VELLUM_DAEMON_TCP_ENABLED=1 bun run src/index.ts daemon start # For real device (all network interfaces): -VELLUM_DAEMON_TCP_ENABLED=1 VELLUM_DAEMON_TCP_HOST=0.0.0.0 bun run src/daemon/main.ts +VELLUM_DAEMON_TCP_ENABLED=1 VELLUM_DAEMON_TCP_HOST=0.0.0.0 bun run src/index.ts daemon start ``` TCP is opt-in (`VELLUM_DAEMON_TCP_ENABLED=1`) for security — the Unix socket default binds only to the local filesystem. By default the TCP listener binds to `127.0.0.1` (simulator use). Set `VELLUM_DAEMON_TCP_HOST=0.0.0.0` to accept LAN connections from a real device. diff --git a/clients/macos/README.md b/clients/macos/README.md index 22dae014236..cfb3b6d4daf 100644 --- a/clients/macos/README.md +++ b/clients/macos/README.md @@ -6,7 +6,7 @@ A native macOS menu bar app that controls your Mac via accessibility APIs and CG This repository also includes an iOS app target (`vellum-assistant-ios`) that shares ~45-50% of code with the macOS app through the `VellumAssistantShared` library. The iOS app is a chat-focused client that connects to a network-accessible daemon via TCP. -**Status:** Fully functional. The iOS target requires xcodebuild with iOS SDK to build — it cannot be built with `swift build` on macOS due to UIKit dependencies. See [clients/ios/README.md](../ios/README.md) for build instructions. +**Status:** Fully functional. Build via Xcode (recommended) or `xcodebuild` from the command line — `swift build` on macOS cannot compile the iOS target due to UIKit dependencies. See [clients/ios/README.md](../ios/README.md) for build instructions. **Code organization:** - `clients/shared/` — Shared library (IPC layer, chat models/ViewModels, design system) @@ -179,13 +179,10 @@ The macOS app is a frontend — all inference (chat, computer-use sessions, ambi ```bash # Start the daemon (from the repo root) -cd assistant && bun run dev - -# Or use the CLI cd assistant && bun run src/index.ts daemon start ``` -The app will auto-reconnect if the daemon restarts. For development, `bun run dev` runs in the foreground with auto-restart on file changes. +The app will auto-reconnect if the daemon restarts. ## Permissions