BUILD.md

Table of Contents Build Dive

• Development Requirements
• Development
  • Clone Repository
  • Update Repository
  • Install dependencies
  • Start development server
  • Development Configuration
• Build for production
  • Cross-platform Build for Windows
• Scripts
• Package Scripts
• MCP Server Setup
  • 1. Add New MCP Server via GUI
  • 2. Edit config.json directly
  • 3. Using Config Editor
  • 4. Custom Scripts
• Project Architecture

Development Requirements

• Node.js LTS+
• uv (for run mcp client)

Development

Clone Repository

git clone --recurse-submodules https://github.com/OpenAgentPlatform/Dive.git
cd Dive

Update Repository

git pull
git submodule update --init --recursive

Install dependencies

npm install

Navigate to mcp-host directory and sync dependencies for mcp host:

cd mcp-host
uv sync

Start development server

npm run dev

Development Configuration

When running Dive in development mode, the configuration file will be automatically generated in the .config directory of your project root. This is different from the production environment where configuration files are stored in the user's home directory.

This allows developers to have separate configurations for development and production environments, making it easier to test different MCP server setups without affecting the production configuration.

To access or modify the development configuration:

/path/to/project/.config/mcp_config.json
/path/to/project/.config/command_alias.json
/path/to/project/.config/model_config.json
/path/to/project/.config/dive_httpd.json
/path/to/project/.config/customrules

Build for production

npm run package

Cross-platform Build for Windows

If you are on macOS or Linux and want to build for Windows:

1. Download Windows binaries

npm run download:windows-bin

2. Build using Docker

./scripts/docker/build-win.sh

Scripts

• dev - Start Electron development server
• build - Build Electron application

Package Scripts

• package - Create application directory
• package:windows - Create Windows distributable package
• package:linux - Create Linux distributable package
• docker:build-win - Build Windows version using Docker

MCP Server Setup

After first launch, you can find the config.json file in these locations:

• macOS: ~/.dive/config
• Windows: %USERPROFILE%\.dive\config
• Linux: ~/.dive/config

There are four ways to configure MCP servers:

1. Add New MCP Server via GUI

1. Click the menu button in the top-left corner to open the sidebar
2. Click "MCP Server Management" at the bottom
3. Click the "Add MCP Server" button
4. Paste your MCP server configuration in JSON format
5. Click "Save" to add the new server

Example configuration:

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

2. Edit config.json directly

You can edit the config.json file directly in the above locations following each MCP server's documentation.

3. Using Config Editor

1. Click the menu button in the top-left corner to open the sidebar
2. Click "MCP Server Management" at the bottom
3. Click the "Edit Config" button on the page

4. Custom Scripts

You can add your own MCP server scripts in the .dive/scripts directory in your home folder, then update the config.json accordingly.

Example:

1. Create a new file echo.js in ~/.dive/scripts
2. Update config.json:

{
  "mcpServers": {
    "echo": {
      "enabled": true,
      "command": "node",
      "args": [
        "echo.js"
      ]
    }
  }
}

Project Architecture

src/
├── atoms/              # Global state management
│   ├── configState.ts    # Model configuration state
│   ├── interfaceState.ts # UI interface state
│   └── historyState.ts   # Chat history state
│
├── components/         # Reusable UI components
│   ├── ModelConfigForm  # Model settings form
│   ├── Toast           # Toast notifications
│   └── Header          # App header
│
├── views/             # Page components
│   ├── Chat/           # Chat interface
│   ├── Setup/          # Initial setup
│   └── Welcome/        # Welcome page
│
├── styles/            # SCSS stylesheets
│   ├── components/     # Component styles
│   └── pages/         # Page-specific styles
│
└── hooks/             # Custom React hooks

electron/
├── main/             # Main process
│   └── index.ts       # Main entry
└── preload/          # Preload scripts
    └── index.ts       # Bridge between main and renderer

mcp-host              # git submodule for [dive-mcp-host](https://github.com/OpenAgentPlatform/dive-mcp-host)