How to Contribute to Rowboatlabs/Rowboat: A Complete Developer's Guide

To contribute to rowboatlabs/rowboat, fork the repository, install dependencies using pnpm in the apps/x workspace, run npm run dev to start the Electron development environment, and submit pull requests with conventional commit messages targeting the main branch.

Rowboat is an open-source AI coworker project that helps users manage emails, calendars, and notes through a local knowledge graph. Contributing to rowboatlabs/rowboat involves working with a TypeScript monorepo containing an Electron desktop application, Next.js web dashboards, a Python SDK, and Model Context Protocol (MCP) integrations.

Understanding the Rowboat Monorepo Architecture

The repository is organized as a monorepo containing multiple applications and shared packages. Understanding this structure is essential before contributing to rowboatlabs/rowboat.

Core Applications and Products

Product	Path	Tech Stack	Purpose
Electron Desktop App	apps/x	Electron 39, React 19, Vite, Tailwind, TypeScript, esbuild	The main AI coworker interface that runs locally, connects to email/calendar, and maintains the knowledge graph
Web Dashboard	apps/rowboat & apps/rowboatx	Next.js 14, React 19, Tailwind, TypeScript	Web interface for exploring and editing the Markdown-based knowledge graph
CLI	apps/cli	Node.js, TypeScript, Ink (TUI)	Command-line interface for automation and debugging
Python SDK	apps/python-sdk	Python 3.12, Pydantic	External scripts integration with Rowboat's local API
Experimental Tools	apps/experimental/*	Varies (Python, Node)	MCP connectors and simulation prototypes

Shared Workspace Packages

All shared logic lives in two workspace packages under apps/x/packages:

• @x/shared (apps/x/packages/shared): Contains utilities, type definitions, and IPC helpers. Defines the data model in models.ts, IPC patterns in ipc.ts, logging, and workspace management.

• @x/core (apps/x/packages/core): Implements business logic including AI agents, scheduling, LLM step events, and the Model Context Protocol bridge.

Both packages must be compiled before running the Electron app using npm run deps in the workspace root.

Setting Up Your Development Environment

Follow these steps to configure your local environment for contributing to rowboatlabs/rowboat.

Fork and Clone the Repository

Start by forking the repository on GitHub, then clone your fork locally:

git clone https://github.com/your-username/rowboat.git
cd rowboat

Install Dependencies and Build Shared Packages

The project uses pnpm for package management. Navigate to the Electron workspace and install dependencies:

cd apps/x
pnpm install

Build the shared packages that the applications depend on:

npm run deps

This compiles @x/shared and @x/core so they can be imported by the main process, preload, and renderer.

Launch the Development Server

Start the full development environment with hot-reloading:

npm run dev

This command runs npm run deps and starts the Electron application concurrently. The renderer process is served at http://localhost:5173, and the main process waits for it before launching the window.

Key Contribution Areas

When contributing to rowboatlabs/rowboat, you can focus on several distinct domains based on your expertise.

UI Components and Electron Renderer

The React-based UI lives in apps/x/apps/renderer/src. This is where you can:

• Fix UI bugs in components
• Implement new dashboard views
• Improve the knowledge graph visualization

The renderer communicates with the main process through the preload bridge exposed at window.rowboat. For example, fetching data from the main process:

// apps/x/apps/renderer/src/App.tsx
import { useEffect, useState } from 'react';

const App = () => {
  const [graph, setGraph] = useState<string>('');
  useEffect(() => {
    // window.rowboat is exposed by the preload script
    window.rowboat?.invoke('getGraph').then(setGraph);
  }, []);
  return <pre>{graph}</pre>;
};
export default App;

AI Agents and MCP Tools

To extend Rowboat's capabilities, you can add new Model Context Protocol tools in apps/x/packages/shared/src/mcp.ts or create new agent behaviors in apps/x/packages/core/src/agent.ts.

Here's how to register a new MCP tool:

// apps/x/packages/shared/src/mcp.ts
export interface Tool {
  name: string;
  description: string;
  execute: (input: any) => Promise<any>;
}

export const registerTool = (tool: Tool) => {
  // Store tool in a global registry used by agents
  toolRegistry[tool.name] = tool;
};

Example implementation of a Slack integration tool:

// apps/x/packages/shared/src/tools/slack.ts
import { registerTool } from '../mcp';
import fetch from 'node-fetch';

registerTool({
  name: 'slack.postMessage',
  description: 'Post a message to a Slack channel',
  async execute({ channel, text }) {
    const res = await fetch(`https://slack.com/api/chat.postMessage`, {
      method: 'POST',
      headers: { Authorization: `Bearer ${process.env.SLACK_TOKEN}` },
      body: JSON.stringify({ channel, text })
    });
    return res.json();
  }
});

Python SDK Enhancements

The Python SDK in apps/python-sdk allows external scripts to interact with Rowboat's local API. You can extend the client functionality in apps/python-sdk/src/rowboat/client.py:

from rowboat import RowboatClient

client = RowboatClient(vault_path="~/.rowboat/vault")
note = client.get_note("meeting-2024-02-19.md")
print(note.content)

Documentation Improvements

Documentation is located in apps/docs (MDX files) and the top-level README.md. Clear documentation is crucial for helping others contribute to rowboatlabs/rowboat.

Code Standards and Testing

Maintaining code quality is essential when contributing to rowboatlabs/rowboat.

Linting and Type Checking

Before submitting changes, run the linting and type-checking commands:

npm run lint                # ESLint across the workspace

pnpm -r run build           # TypeScript compile for all packages

These commands ensure that your changes meet the project's coding standards and compile without errors.

Conventional Commits and Pull Request Process

Follow these guidelines when submitting your contribution:

1. Use conventional commit messages (e.g., feat: add Slack MCP connector, fix: resolve memory leak in agent scheduler, docs: update API reference)
2. Target the main branch with your pull request
3. Include a concise description explaining what changed and why
4. Link related issues using GitHub's closing keywords (e.g., "Closes #123")
5. Ensure CI passes – the repository uses GitHub Actions (.github/workflows/*) to verify builds, linting, and tests

Summary

• Rowboat is a monorepo containing an Electron desktop app, Next.js web dashboards, a Python SDK, and MCP integrations located in apps/x, apps/rowboat, and apps/python-sdk
• Shared packages @x/shared and @x/core in apps/x/packages contain the data models, IPC helpers, and AI agent logic that power the application
• Development setup requires pnpm install in apps/x, running npm run deps to build shared packages, and npm run dev to start the Electron app with hot-reloading
• Contribution areas include React UI components in apps/x/apps/renderer, MCP tools in apps/x/packages/shared/src/mcp.ts, Python SDK extensions in apps/python-sdk, and documentation in apps/docs
• Quality standards require running npm run lint and pnpm -r run build before submitting PRs with conventional commit messages targeting the main branch

Frequently Asked Questions

What is the fastest way to start contributing to rowboatlabs/rowboat?

The fastest path is to fork the repository, clone it locally, navigate to apps/x, run pnpm install followed by npm run deps to compile the shared packages, then execute npm run dev to launch the Electron development environment. Once running, you can modify React components in apps/x/apps/renderer/src or add MCP tools in apps/x/packages/shared/src and see changes immediately via hot-reloading.

How do I add a new integration tool to Rowboat?

To add a new Model Context Protocol (MCP) tool, create a new TypeScript file in apps/x/packages/shared/src/tools/ (following the pattern in mcp.ts), implement the Tool interface with name, description, and execute properties, then register it using the registerTool function. The tool becomes available to agents defined in apps/x/packages/core/src/agent.ts and can invoke external APIs or local resources as needed.

What testing and linting steps are required before submitting a pull request?

Before submitting a PR, you must run npm run lint to execute ESLint across the workspace and pnpm -r run build to ensure all TypeScript packages compile without errors. These commands verify that your changes meet the project's code quality standards. Additionally, ensure your commit messages follow the conventional commits format (e.g., feat:, fix:, docs:) and that your PR targets the main branch with a clear description linking any related issues.

Can I contribute to Rowboat using Python instead of TypeScript?

Yes, you can contribute Python code through the apps/python-sdk directory, which provides a Python interface to Rowboat's local API. You can extend the RowboatClient class in apps/python-sdk/src/rowboat/client.py to add new methods for interacting with the knowledge graph vault or local services. Additionally, experimental tools in apps/experimental/* often use Python for MCP connectors and simulation runners, providing another avenue for Python contributions.

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