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

> Learn how to contribute to rowboatlabs/rowboat. Fork, install dependencies with pnpm, run dev, and submit PRs using conventional commits to the main branch. Get started today.

- Repository: [RowBoat Labs/rowboat](https://github.com/rowboatlabs/rowboat)
- Tags: how-to-guide
- Published: 2026-02-19

---

**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`](https://github.com/rowboatlabs/rowboat/blob/main/models.ts), IPC patterns in [`ipc.ts`](https://github.com/rowboatlabs/rowboat/blob/main/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:

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

```bash
cd apps/x
pnpm install

```

Build the shared packages that the applications depend on:

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

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

```tsx
// 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`](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/shared/src/mcp.ts) or create new agent behaviors in [`apps/x/packages/core/src/agent.ts`](https://github.com/rowboatlabs/rowboat/blob/main/apps/x/packages/core/src/agent.ts).

Here's how to register a new MCP tool:

```ts
// 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:

```ts
// 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`](https://github.com/rowboatlabs/rowboat/blob/main/apps/python-sdk/src/rowboat/client.py):

```python
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`](https://github.com/rowboatlabs/rowboat/blob/main/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:

```bash
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`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/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.