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

> Explore the rowboatlabs/rowboat repository, a local-first AI coworker monorepo. Transform documents into a knowledge graph with this open-source solution. Learn more.

- Repository: [RowBoat Labs/rowboat](https://github.com/rowboatlabs/rowboat)
- Tags: getting-started
- Published: 2026-02-16

---

**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`](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/apps/main/src/main.ts) bootstraps the entire application:

```typescript
// 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`](https://github.com/rowboatlabs/rowboat/blob/main/apps/cli/src/tui/ui.tsx) provides an Ink-based interface that reuses the same `RowboatApi` class as the Electron UI:

```bash

# 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`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/shared/src/mcp.ts) and [`apps/x/packages/core/src/mcp/mcp.ts`](https://github.com/rowboatlabs/rowboat/blob/main/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:

```typescript
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:

```bash

# 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:

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

```

To explore the CLI:

```bash
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.