What is the rowboatlabs/rowboat Repository? A Complete Guide to the Local-First AI Coworker

The rowboatlabs/rowboat repository is an open-source, local-first AI coworker monorepo that transforms emails, meeting notes, and work artifacts into a queryable knowledge graph, featuring an Electron desktop app, Next.js web dashboards, CLI tools, and a Python SDK.

The rowboatlabs/rowboat repository provides a comprehensive toolkit for building AI-powered workflows that respect user privacy by keeping data local. It implements a sophisticated architecture where multiple interface layers—desktop, web, and terminal—share a common backend built on TypeScript and Node.js, all orchestrated through a nested PNPM workspace structure.

Core Components of the rowboatlabs/rowboat Repository

Electron Desktop App (RowboatX)

The primary interface is RowboatX, a full-screen Electron application located in apps/x/. Built with React, Vite, and TailwindCSS, this desktop app handles AI chats, background agents, and synchronization with external services like Google Gmail, Calendar, and Fireflies.

The main process entry point at apps/x/apps/main/src/main.ts bootstraps the entire application:

// apps/x/apps/main/src/main.ts
await initConfigs();                 // Load model & UI config
setupIpcHandlers();                  // Wire IPC between main & renderer
startWorkspaceWatcher();             // Watch markdown vault
initGmailSync();                     // Sync Gmail into the graph
initGraphBuilder();                  // Build the knowledge graph from vault
initPreBuiltRunner();                // Start built-in agents
initAgentRunner();                   // Start scheduled agents

Web Dashboards and CLI

Beyond the desktop app, the rowboatlabs/rowboat repository includes multiple web interfaces built with Next.js:

• apps/rowboat/: Web dashboard for managing agents, runs, and settings
• apps/rowboatx/: Alternative web UI mirroring desktop functionality

For terminal users, the CLI tool at apps/cli/src/tui/ui.tsx provides an Ink-based interface that reuses the same RowboatApi class as the Electron UI:

# Launch the interactive terminal UI

node apps/cli/bin/app.js

Python SDK and Documentation

The repository includes a Python SDK (apps/python-sdk/) exposing the same REST API endpoints (/runs, /agents, /models) for programmatic access from Python environments. Documentation is maintained as Markdown source in apps/docs/ and rendered via Next.js.

Architecture and Workspace Structure

Nested PNPM Workspace Layout

The rowboatlabs/rowboat repository follows a sophisticated nested PNPM workspace organization:

rowboat/
├─ apps/
│  ├─ x/                 # Electron app (RowboatX)

│  ├─ rowboat/           # Next.js dashboard

│  ├─ rowboatx/          # Next.js frontend

│  ├─ cli/               # CLI tool

│  ├─ python-sdk/        # Python SDK

│  └─ docs/              # Docs site

├─ packages/
│  ├─ shared/            # Types, utilities, validators (@x/shared)

│  └─ core/              # Business logic, AI, OAuth, MCP (@x/core)

The workspace is defined in apps/x/pnpm-workspace.yaml, which includes the shared packages and Electron applications.

Core Packages: @x/shared and @x/core

Two internal packages form the backbone of the architecture:

@x/shared (packages/shared/): Pure TypeScript utilities including IPC helpers, type definitions, models, and the Model Context Protocol (MCP) implementation at apps/x/packages/shared/src/mcp.ts.

@x/core (packages/core/): Implements the knowledge graph, sync adapters for external services (Gmail, Calendar, Fireflies, Granola), background agents, tool execution, and the AI assistant stack using the Vercel AI SDK.

Key Features and Implementation Details

Local-First Knowledge Graph

At the heart of rowboatlabs/rowboat is a local-first architecture where all data resides in an Obsidian-compatible vault of plain Markdown files (apps/x/packages/core/src/knowledge/). The knowledge graph builder (apps/x/packages/core/src/knowledge/build_graph.ts) scans these files to create queryable relationships between emails, meeting notes, and other work artifacts.

This approach ensures:

• Data sovereignty: Your information never leaves your machine unless explicitly synced
• Version control compatibility: Plain text files work seamlessly with Git
• Backup flexibility: Any file system tool can backup the vault

Model Context Protocol (MCP) Integration

The repository implements the Model Context Protocol at apps/x/packages/shared/src/mcp.ts and apps/x/packages/core/src/mcp/mcp.ts. This protocol allows the AI assistant to request external tools (search engines, databases, Slack, etc.) and receive structured responses.

The MCP defines JSON schemas for tool calls and responses, enabling extensible tool use without hardcoding specific integrations into the core assistant logic.

Background Agents and Scheduling

Rowboat supports autonomous background agents that operate on schedules or triggers. The agent scheduling system (apps/x/packages/core/src/agent-schedule/) allows defining agents that run at specific times:

import { AgentScheduleRepo } from "@x/core/dist/agent-schedule/repo.js";

await AgentScheduleRepo.save({
  agentId: "rowboatx",
  trigger: { cron: "0 9 * * MON-FRI" }, // every weekday at 9 AM
  description: "Morning brief generator",
});

The scheduler initializes automatically via initAgentRunner() in the main process, ensuring scheduled agents start when the application boots.

Getting Started with rowboatlabs/rowboat

To run the rowboatlabs/rowboat repository locally:

# Clone the repository

git clone https://github.com/rowboatlabs/rowboat.git
cd rowboat

# Install pnpm and dependencies

npm i -g pnpm
pnpm install

# Build workspace dependencies

npm run deps   # builds shared, core, and preload packages

# Start the Electron desktop app

npm run dev    # starts renderer (Vite) and main process

The Electron app will open at http://localhost:5173 in development mode (or app://-/index.html in production) and connect to the local backend at http://127.0.0.1:3000.

To run the web dashboard:

cd apps/rowboat
npm install
npm run dev   # http://localhost:3000

To explore the CLI:

node apps/cli/bin/app.js   # Interactive Ink-based TUI

Configure external integrations by adding API keys under ~/.rowboat/config/ for services like Deepgram, Brave Search, Exa, and Google OAuth as described in the repository README.

Summary

• The rowboatlabs/rowboat repository is a comprehensive monorepo delivering a local-first AI coworker that transforms work artifacts into a queryable knowledge graph.
• It features multiple interface layers including an Electron desktop app (apps/x/), Next.js web dashboards (apps/rowboat/, apps/rowboatx/), a CLI tool (apps/cli/), and a Python SDK (apps/python-sdk/).
• The architecture relies on a nested PNPM workspace with core packages @x/shared (utilities, IPC, MCP) and @x/core (knowledge graph, AI assistant, sync adapters).
• All data resides in an Obsidian-compatible Markdown vault (apps/x/packages/core/src/knowledge/), ensuring complete data sovereignty and version control compatibility.
• The system supports background agents with cron scheduling, Model Context Protocol (MCP) for external tool integration, and sync adapters for Gmail, Calendar, and meeting notes.

Frequently Asked Questions

What is the primary purpose of the rowboatlabs/rowboat repository?

The rowboatlabs/rowboat repository provides an open-source, local-first AI coworker designed to ingest emails, meeting notes, and other work artifacts, convert them into a structured knowledge graph, and enable AI agents to act on that context while keeping all data stored locally in Markdown files.

How does the rowboatlabs/rowboat repository handle data privacy?

The repository implements a strict local-first architecture where all user data resides in an Obsidian-compatible vault of plain Markdown files located at apps/x/packages/core/src/knowledge/. This ensures data never leaves the local machine unless explicitly synced by the user, providing complete data sovereignty and compatibility with standard version control and backup tools.

What interfaces are available for interacting with the rowboatlabs/rowboat system?

The repository provides multiple interface layers: the RowboatX Electron desktop app (apps/x/) for full-featured desktop use; Next.js web dashboards (apps/rowboat/ and apps/rowboatx/) for browser-based management; a CLI tool (apps/cli/) with an Ink-based terminal UI; and a Python SDK (apps/python-sdk/) for programmatic access.

How are background agents and automation implemented in rowboatlabs/rowboat?

Background agents operate through the agent-schedule system defined in apps/x/packages/core/src/agent-schedule/. Users can define scheduled agents using cron expressions via AgentScheduleRepo.save(), and these agents initialize automatically when the main process starts via initAgentRunner(). This enables automated workflows like daily morning briefs generated from the knowledge graph without manual intervention.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}