One-command boot — npx openvolo starts everything  •  Local-first — SQLite database, data never leaves your machine  •  Multi-platform — X + LinkedIn + Gmail in one CRM  •  AI-powered — Claude AI via Vercel AI SDK

Features

Contact Management

Unified contacts across platforms with automatic cross-platform deduplication. Enrichment scoring (0-100) based on profile completeness and identity count, funnel stage tracking from lead to customer.

X/Twitter Integration

OAuth 2.0 authentication, contact sync from followers/following, tweet and mention import with cursor-based pagination, compose and publish tweets, thread support, and engagement actions (like, retweet, reply).

LinkedIn Integration

OAuth 2.0 with OpenID Connect, profile sync, and CSV import for connections (no LinkedIn partner program required).

Gmail / Google Contacts

Google People API contact sync with 2-tier deduplication (identity match then email match). Email metadata enrichment tracks message frequency (sent/received in last 30 days) per contact — no email content is stored.

Content Library

Import posts and mentions from X, LinkedIn, and Gmail. Filter by platform to focus on a single channel. Multi-platform compose with platform-aware constraints (X: 280 chars + threads, LinkedIn: 3,000 char drafts). Platform-aware engagement display with per-platform action labels. Six content types (post, thread, article, newsletter, DM, reply). AI-powered draft generation via the save-draft agent tool. Engagement metrics tracked over time with both JSON snapshots (fast display) and structured rows (time-series analysis).

Task Management

Create, update, and track tasks with status and priority. Link tasks to contacts for relationship-aware workflows.

Automation Hub

Three-tab Automation page — Agents (gallery + builder), Actions (platform sync operations), Runs (execution history). Six workflow types: sync, enrich, search, prune, sequence, and agent. Agent gallery with 10 seed agents (3 search, 3 enrich, 2 prune, plus user-created), activation dialog for quick setup. User agent builder lets you clone any system agent and customize it. Actions tab consolidates all sync operations (X, LinkedIn, Gmail) with platform connection awareness. Four visualization modes (list, kanban, swimlane, graph) with run/step observability and per-step cost tracking. Cron-based workflow scheduling with presets, custom expressions, and a 60-second background runner.

AI Agent Runner

Eight agent tools — url-fetch (Cheerio), browser-scrape (Playwright), search-web (Serper + Tavily), enrich-contact, update-progress, archive-contact (prune workflows), save-draft (AI content generation), and engage-post (template-driven engagement). Domain-based routing engine (e.g. x.com → browser, wikipedia → fetch) with automatic escalation on failure.

Prune & Archive

Metadata-based contact archiving from prune workflows — contacts are soft-archived (restorable, not deleted). Archive and restore from workflow detail or individual contact pages. "Show Archived" toggle in the contacts list with visual indicators for archived rows.

Workflow Scheduling

Cron-based scheduling with common presets (hourly, daily, weekly) and custom cron expressions. Next-run preview and per-template config overrides. Auto-execution via a 60-second background runner initialized through Next.js instrumentation.

Smart Search

Dual search providers: Serper for broad discovery (Google results), Tavily for deep research. Intelligent routing by workflow type and query patterns with automatic failover. Combined free tiers across both providers.

Analytics Dashboard

Five-tab dashboard — Overview, Agents, Engagement, Content, Sync Health. Six reusable chart components (area, bar, donut, ranked table, stat cards, skeleton). Time range filtering across all tabs.

AI Chat Assistant

Streaming chat panel (Cmd+K) powered by Vercel AI SDK 6. Eight CRM tools for querying contacts, analytics, workflows, and content — plus creating contacts, tasks, and starting agents — all conversationally. Page-aware context injection adapts responses to your current view. Smart prompts suggest relevant queries based on your current page. Save conversations and continue them later from the searchable history panel.

Browser Enrichment

Playwright-based profile scraping with anti-detection measures, LLM-powered field extraction, and session persistence for authenticated scraping.

Privacy & Security

AES-256 encrypted credential storage. All data stored locally in SQLite — no cloud dependency, no data leaves your machine.

Quick Start

npx openvolo

On first run, OpenVolo creates ~/.openvolo/ for your database and config, runs schema migrations, and starts the dashboard at http://localhost:3000.

Environment Variables

Create a .env.local file in your project root:

# Required — for Claude AI features
ANTHROPIC_API_KEY=

# X/Twitter (optional)
X_CLIENT_ID=
X_CLIENT_SECRET=

# LinkedIn (optional)
LINKEDIN_CLIENT_ID=
LINKEDIN_CLIENT_SECRET=

# Gmail / Google Contacts (optional)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

# Web search (optional — for agent workflows)
SERPER_API_KEY=
TAVILY_API_KEY=

Platform Setup

X/Twitter — Create an app at developer.x.com, enable OAuth 2.0 with http://localhost:3000/api/platforms/x/callback as the redirect URI.

LinkedIn — Create an app at developer.linkedin.com, add the "Sign In with LinkedIn using OpenID Connect" product, set http://localhost:3000/api/platforms/linkedin/callback as the redirect URI.

Gmail / Google — Create a project in Google Cloud Console, enable the People API and Gmail API, configure OAuth consent screen, and add http://localhost:3000/api/platforms/gmail/callback as the redirect URI.

See the in-app Help page (/dashboard/help) for detailed step-by-step setup guides for each platform.

Architecture

Boot flow — npx openvolo runs bin/cli.ts, which ensures ~/.openvolo/ directories exist, pushes the latest schema to SQLite, and spawns Next.js.

Rendering boundary — Server Components read the database directly (better-sqlite3 is synchronous). Client Components call API routes via fetch.

AI — Vercel AI SDK 6 powers both streaming chat in the UI and background agent workflows using Claude models.

Data layer — SQLite database at ~/.openvolo/data.db managed by Drizzle ORM. Credentials are AES-256 encrypted in ~/.openvolo/config.json.

Tech Stack

| Category | Details | |----------|---------| | Framework | Next.js 16.1, React 19, TypeScript 5.8 | | Database | SQLite (better-sqlite3), Drizzle ORM 0.45 | | AI | Vercel AI SDK 6, Anthropic SDK | | UI | Tailwind CSS 4, shadcn/ui (Radix), Lucide Icons | | Charts | Recharts (via shadcn/ui chart component) | | Browser | Playwright (enrichment scraping) | | Parsing | Cheerio (HTML), Tiptap (rich text editor) | | Drag & Drop | @dnd-kit (kanban, swimlane views) | | Testing | Vitest | | Scheduling | cron-parser (cron expression parsing) | | Validation | Zod 3.24 |

Project Structure

bin/cli.ts                            # npx entry point
instrumentation.ts                    # Next.js instrumentation hook (scheduler init)
src/
  app/
    api/                              # API routes
      contacts/                       #   Contact CRUD
      content/                        #   Content CRUD
      platforms/                      #   X, LinkedIn, Gmail auth + sync
      tasks/                          #   Task CRUD
      chat/                           #   AI chat streaming + conversation persistence
      analytics/                      #   Analytics endpoints (5 tabs)
      workflows/                      #   Workflow CRUD + templates + agent runs
    dashboard/                        # UI routes
      contacts/                       #   Contact list + detail
      content/                        #   Content list + detail + compose
      workflows/                      #   Automation hub (agents, actions, runs) + detail
      analytics/                      #   Analytics dashboard (5-tab)
      settings/                       #   Platform connections + API keys (config only)
      help/                           #   Setup guides
  lib/
    db/
      schema.ts                       # All database tables (Drizzle)
      client.ts                       # Database connection
      queries/                        # Query modules (contacts, content, tasks, ...)
    platforms/
      x/                              # X/Twitter client, mappers, adapter
      linkedin/                       # LinkedIn client, mappers, adapter
      gmail/                          # Gmail/Google client, mappers, adapter
    workflows/                        # Workflow types, sync wrapper
    agents/                           # Agent tools, runner, routing engine
    chat/                             # Chat types, system prompt, 8 CRM tools, smart prompts
    browser/                          # Browser enrichment (Playwright, anti-detection)
    analytics/                        # Analytics utilities (time range, formatting)
    scheduler/                        # Background scheduler runner (60s interval)
    auth/                             # AES-256 crypto + API key management
  components/                         # Shared UI components (shadcn/ui based)
    charts/                           #   Reusable chart components (area, bar, donut, ...)
    chat/                             #   Chat panel, message, input, toolbar, history

Development

npm run dev              # Next.js dev server (Turbopack)
npm run build            # Production build
npm run build:cli        # Compile CLI entry point
npm run db:generate      # Generate Drizzle migrations from schema
npm run db:migrate       # Apply pending migrations
npm run db:studio        # Open Drizzle Studio (DB browser)
npm run test             # Run Vitest
npm run lint             # ESLint

Roadmap

• [x] Phase 0 — Project setup, CLI, schema, auth, UI shell
• [x] Phase 1 — Contact CRUD, Task CRUD, Dashboard, Identities, Enrichment, X/Twitter
• [x] Phase 2 — Content Library, LinkedIn + Gmail Integration, Browser Enrichment
• [x] Phase 3 — Unified Workflows, Agent Runner, Smart Search Routing, Prune Execution, Workflow Scheduling
• [x] Phase 4 — Analytics Dashboard (5-tab with charts)
• [x] Phase 5 — AI Chat Assistant (8 CRM tools, streaming, smart prompts, conversation history)
• [x] Phase 5.5 — Multi-Channel Content & Automation (platform-agnostic content, multi-platform compose, Automation hub with Agents/Actions/Runs tabs)
• [ ] Phase 6 — Content & Demand Gen (media system, browser publishing, AI content creation, goals, user templates — 6E complete)

License

Apache License 2.0