🌓

Deployment Guide

How to build, deploy, configure, and maintain MultiTerminal on a Windows machine.

Prerequisites

Build Process

Building from Source

MultiTerminal is built using MSBuild (via .NET SDK). The project targets net8.0-windows with self-contained deployment for x64.

# Build in Release mode (self-contained, single output directory)
dotnet publish -c Release -r win-x64 --self-contained true

# Or using MSBuild directly
msbuild MultiTerminal.csproj /p:Configuration=Release /p:RuntimeIdentifier=win-x64

Build Output

The build produces output in:

bin\Release\net8.0-windows\win-x64\publish\

This folder contains the complete self-contained deployment (~385 MB, ~1,262 files). See Distribution for a complete file audit.

Build via MCP Tool

When working inside MultiTerminal, agents can trigger builds using the build_project MCP tool from the windows-build-runner server. This compiles the latest source code without needing to exit the application.

Deploy Workflow

deploy.ps1 Script

The deployment script handles copying build output to the Deploy folder:

1. Close MultiTerminal - Exit the running application completely
2. Run deploy.ps1 - Copies build output from bin\Release\ to Deploy\
3. Relaunch MultiTerminal - Start Deploy\MultiTerminal.exe

# From the source directory:
.\deploy.ps1

# Then relaunch:
H:\DevLaptop\ClarionPowerShell\Deploy\MultiTerminal.exe

Configuration Files

Application Configuration

File	Location	Purpose
MultiTerminal.runtimeconfig.json	Deploy folder	Specifies .NET 8 runtime version, GC settings, and thread pool configuration. Rarely needs modification.
MultiTerminal.deps.json	Deploy folder	Auto-generated dependency manifest. Do not edit manually.
MultiTerminal.dll.config	Deploy folder	Application settings (connection strings, feature flags). Edit to customize behavior.

Claude Code Configuration

File	Location	Purpose
.claude/CLAUDE.md	Project root	Project instructions loaded into every agent's context (~16 KB). Contains architecture reference, patterns, and conventions.
.claude/project.json	Project root	Project identity (unique ID, name, timestamps). Links the project to MultiTerminal's registry.
.claude/settings.json	Project root	Project-level Claude Code settings (experimental features, etc.).
.claude/settings.local.json	Project root	Local permission presets for MCP tools and shell commands. Not committed to git.

Global Claude Configuration

File	Location	Purpose
CLAUDE.md	~/.claude/	User-level instructions applied to all projects (e.g., PowerShell preference, tool priorities).
settings.json	~/.claude/	Global Claude Code settings (experimental features like agent teams).
.mcp.json	%APPDATA%\multiterminal\	MCP server registrations for the two stdio servers (multiterminal, mcp-gateway). Loaded via --mcp-config; generated by the installer.

Database Locations

All databases are SQLite files created automatically on first run. Located in the user's AppData directory:

Database	Path	Contents
multiterminal.db	%APPDATA%\multiterminal\multiterminal.db	Main database (all in one file). Kanban tasks, checklists, plans, helpers, continuation notes, stale tracking. Team profiles, activity feed, inbox notifications, terminal registrations. Projects, agents, MCP config, specialist agents, paths, prompts, skills. Knowledge entries (6 categories), code digests, FTS5 index. Session lineage, session messages, session-agent maps, task reports, and the code graph.
messages.db	%APPDATA%\multiterminal\messages.db	Inter-terminal message delivery queue: pending messages, retry counts, delivery timestamps, expiry.

MCP Server Setup

Two MCP Servers (stdio)

Claude Code connects to exactly two MCP servers, both over stdio. Neither is an HTTP endpoint. See MCP Architecture for the full design.

• multiterminal - a Node.js STDIO server (%APPDATA%\multiterminal\mcp\index.js) that wraps the MultiTerminal REST API. It launches with command: "node" and translates each tool call into an HTTP request against http://localhost:5050/api/* (the REST API hosted by the running app).
• mcp-gateway - a .NET console app (McpGateway.exe) that proxies and aggregates any number of backend MCP servers (sqlite, mssql, everything-search, windows-build-runner, windowssnapit, etc.) behind a single connection.

The REST API on port 5050 starts automatically when MultiTerminal launches; the multiterminal MCP server talks to it. There is no http://localhost:5050/mcp endpoint.

Claude Code MCP Registration

Both servers are registered in a single config file at %APPDATA%\multiterminal\.mcp.json, which Claude Code is pointed at via --mcp-config when MultiTerminal launches a terminal. Registration is by command (stdio), not by URL:

# %APPDATA%\multiterminal\.mcp.json
{
  "mcpServers": {
    "mcp-gateway": {
      "type": "stdio",
      "command": "C:\\Program Files\\MultiTerminal\\mcp-gateway\\McpGateway.exe",
      "args": []
    },
    "multiterminal": {
      "type": "stdio",
      "command": "node",
      "args": ["C:\\Users\\<username>\\AppData\\Roaming\\multiterminal\\mcp\\index.js"]
    }
  }
}

This file is regenerated by the app at startup (GatewayIntegrationService) with correct paths for the machine, and MT-spawned terminals load it per-launch via the --mcp-config flag. Registering the same servers globally in ~/.claude.json — so that Claude Code sessions started outside MultiTerminal see them too — is an opt-in installer component ("Register MCP servers globally"), unchecked by default. Do not register an http://localhost:5050/mcp URL — that endpoint does not exist.

Gateway Backend Servers

The mcp-gateway server aggregates backend MCP servers, so Claude Code's connection count stays fixed at two while the backend set can grow. Typical backends:

Backend	Type	Purpose
sqlite	stdio (Node.js)	Direct SQLite database queries
mssql	stdio (Node.js)	SQL Server database access (optional)
everything-search	stdio (Node.js)	Instant file search via voidtools Everything index
windows-build-runner	stdio (Node.js)	Build and compile projects from within agents
windowssnapit	stdio (Node.js)	Screenshot capture and clipboard reading

Backends are stored in the gateway's own SQLite database and grouped into profiles, not in .mcp.json. Manage them at runtime via the gateway's gateway__* tools or per-project from the Project Panel.

Claude Code Integration

.claude/ Folder Structure

.claude/
+-- CLAUDE.md              (project instructions - loaded into agent context)
+-- project.json           (project identity and metadata)
+-- settings.json          (Claude Code settings)
+-- settings.local.json    (local permissions - not in git)
+-- agents/                (specialist agent definitions - 8 files)
|   +-- code-reviewer.md
|   +-- debugger.md
|   +-- devils-advocate.md
|   +-- security-auditor.md
|   +-- session-distiller.md
|   +-- session-summarizer.md
|   +-- test-designer.md
|   +-- verifier.md
+-- hooks/                 (event hooks - 9 files)
|   +-- active-context-hook.js
|   +-- inbox-check-hook.js
|   +-- notification-hook.js
|   +-- pipeline-trigger-hook.js
|   +-- project-context-hook.js
|   +-- safety-hook.js
|   +-- session-status-hook.js
|   +-- subagent-office-hook.js
|   +-- task-to-agent-hook.js
+-- skills/                (custom slash commands)
+-- rules/                 (additional behavioral rules)
+-- messages/              (inter-session message store)
+-- research/              (research artifacts)

Hooks (9 files)

Claude Code hooks integrate terminal activity with MultiTerminal's services:

Hook	Purpose
session-status-hook.js	Injects active context (task, checklist, build status) at session start
active-context-hook.js	Auto-writes ACTIVE-CONTEXT.md after builds, checklist updates, and status changes
project-context-hook.js	Injects project context via MULTITERMINAL_PROJECT_ID at session start
inbox-check-hook.js	Delivers messages (legacy file-inbox path; Channels is the primary path now)
task-to-agent-hook.js	Routes task assignments to the correct agent/team
subagent-office-hook.js	Manages subagent lifecycle and office panel presence
safety-hook.js	Safety guardrails for destructive operations
pipeline-trigger-hook.js	Triggers CI/CD pipeline actions on specific events
notification-hook.js	Sends desktop notifications for important events

Environment Variables

Variable	Set By	Purpose
MULTITERMINAL_DOC_ID	Terminal launch	Unique document ID for terminal registration
MULTITERMINAL_NAME	Terminal launch	Display name for the terminal identity (used in messaging and team roster)
MULTITERMINAL_PROJECT_ID	Terminal launch	Project ID for context injection via startup hook
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS	User config	Enable native Claude Code team agent support (set to 1)

Fresh Installation

Option A: Inno Setup Installer (Recommended)

The Inno Setup installer is the recommended installation method. It handles file placement, MCP server registration, and post-install configuration automatically:

1. Run MultiTerminal-Setup.exe
2. Follow the installer prompts to choose an installation directory
3. The post-install script (post-install.js) registers MCP servers and creates configuration files
4. Launch MultiTerminal from the Start Menu or desktop shortcut

See Distribution — Installer for details on the installer scripts.

Option B: Manual (Portable) Installation

Step 1: Deploy Application Files

# Create installation directory
New-Item -ItemType Directory -Path "C:\Applications\MultiTerminal" -Force

# Copy all files from the build output (or existing Deploy folder)
Copy-Item -Path "path\to\publish\*" -Destination "C:\Applications\MultiTerminal\" -Recurse -Force

Step 2: Install MCP Server Dependencies

The MCP server is located at %APPDATA%\multiterminal\mcp\index.js and requires Node.js dependencies:

cd "$env:APPDATA\multiterminal\mcp"
npm install

Step 3: Deploy Claude Code Hooks

Copy the 9 hook files from .claude/hooks/ to your project or global hooks directory:

# Hook files: inbox-check-hook.js, project-context-hook.js, safety-hook.js,
# subagent-office-hook.js, task-to-agent-hook.js, session-status-hook.js,
# pipeline-trigger-hook.js, active-context-hook.js, notification-hook.js

Edit hook files to update hard-coded paths to your installation directory.

Step 4: Configure Claude Code Hooks

Create ~/.claude/hooks.json with the hook event bindings. See Quick Start for the complete hooks.json template.

Step 5: Register MCP Servers

Create %APPDATA%\multiterminal\.mcp.json registering both stdio servers (Claude Code is pointed at it via --mcp-config). Both are launched by command, not by URL:

# %APPDATA%\multiterminal\.mcp.json
{
  "mcpServers": {
    "mcp-gateway": {
      "type": "stdio",
      "command": "path\\to\\McpGateway.exe",
      "args": []
    },
    "multiterminal": {
      "type": "stdio",
      "command": "node",
      "args": ["%APPDATA%\\multiterminal\\mcp\\index.js"]
    }
  }
}

Step 6: Create Data Directory

New-Item -ItemType Directory -Path "$env:APPDATA\multiterminal" -Force

The application will create database files automatically on first run.

Step 7: Launch

C:\Applications\MultiTerminal\MultiTerminal.exe

Verification Checklist

Troubleshooting

Issue	Cause	Solution
Application won't start	Missing runtime files	Verify all files from critical files checklist exist in the Deploy folder
WebView2 panels blank	WebView2 Runtime not installed	Install WebView2 Evergreen Runtime from Microsoft
MCP tools not available in Claude Code	MCP server not registered	Verify %APPDATA%\multiterminal\.mcp.json contains the multiterminal and mcp-gateway stdio entries, and that the app (REST API on 5050) is running
Port 5050 already in use	Another instance running or port conflict	Close other MultiTerminal instances; check with netstat -ano | findstr 5050
Database errors on startup	%APPDATA%\multiterminal folder missing or not writable	Create the folder manually: mkdir %APPDATA%\multiterminal
better-sqlite3 module not found	Node modules not installed for session history	Run npm install in the %APPDATA%\multiterminal\mcp directory
Hooks not executing	hooks.json missing or paths incorrect	Verify ~/.claude/hooks.json exists and all paths point to actual files
Terminal shows blank screen	ConPty initialization failure	Check Debug panel for errors; ensure terminal.html exists in Deploy folder
Messages not delivered	Terminal not registered or webhook failure	Ensure terminals call register_terminal at startup; check Debug panel for delivery errors
Session restore fails	Corrupted layout XML or missing session data	Delete the layout XML file from %APPDATA%\multiterminal\ to reset to defaults