Architecture

MultiTerminal is a WinForms desktop application (C#/.NET) with an integrated REST API, MCP server, and WebView2-based UI panels. This page describes the system layers, data flow, database schema, and key patterns.

System Overview

The system is organized into five distinct layers, with the MessageBroker serving as the central hub connecting everything together.

Critical Files

These files contain the majority of the system's logic. Read them first when onboarding.

Data Flow

Here is how a typical operation (e.g., creating a task) flows through the system.

Agent Creates a Task

Checklist Item Transition

Host-Controlled Memory Architecture

MultiTerminal inverts the standard Claude Code context model. Instead of agents reading static files (CLAUDE.md, memory.md) and deciding what to remember, the host controls context injection through three mechanisms:

• Session continuity — hooks track session→agent mappings, auto-sync JSONL transcripts, and inject the agent's own last-session recap at startup
• Knowledge injection — hooks query SQLite at session start, rank entries by attention decay, and inject the most relevant knowledge before the agent sees any prompt
• Subprocess isolation — spawned agents receive a per-agent system prompt file and scoped settings, bypassing global CLAUDE.md and user-level hooks entirely

The following sections detail each mechanism.

Session Sync Pipeline (End-to-End)

Every Claude Code session is automatically tracked and imported into the session database, preserving which agent ran it and providing session continuity across restarts.

Phase 1: Session Start (Hook)

Phase 2: Session End (Hook)

Phase 3: Auto-Sync on Startup

Phase 4: Session Recap at Terminal Start

Key Files

Host-Controlled Knowledge Injection

At every session start, the session-status-hook.js injects relevant knowledge entries into the agent's context. The host — not the agent — decides what gets injected and in what order.

Subprocess Isolation

Spawned team agents receive controlled context to prevent global CLAUDE.md leakage and user-level hook interference.

Isolation Key Files

Database Schema

All data is stored under your per-user data folder, %APPDATA%\multiterminal (typically C:\Users\<you>\AppData\Roaming\multiterminal). The primary database is multiterminal.db, which holds most tables.

The %APPDATA%\multiterminal Data Folder

Everything MultiTerminal persists for the current user lives here — the databases, the configuration files, the bundled MCP server, and runtime logs. Nothing is written under the install directory, so the app can run from a read-only location and a single folder holds all your state.

Databases

Configuration & state files

Subfolders

You may also see legacy/backup files here from older versions (e.g. sessions.db.old, tasks.db) — these are no longer used. To back up your data, copy this folder (at minimum multiterminal.db and messages.db) while MultiTerminal is closed; see Troubleshooting.

multiterminal.db - Core Tables

multiterminal.db - Session Lineage Tables

multiterminal.db - Knowledge Tables

multiterminal.db - Project Tables (ProjectDatabase.cs)

MessageBroker Events

The MessageBroker fires C# events that MainForm subscribes to for updating the UI. All events are thread-safe and marshaled to the UI thread.

Key Patterns

Adding a UI Panel

1. Create {Name}Panel/{Name}PanelDocument.cs inheriting DockContent (set DockAreas, HideOnClose=true)
2. Create inner control with WebView2 or custom renderer
3. Add Initialize(MessageBroker broker) and ApplyTheme(bool isDark) methods
4. In MainForm: instantiate, call Initialize(), wire events, add toolbar toggle button
5. Follow existing panels (TasksPanel, ActivityPanel) as templates

Adding a Backend Feature

1. Add model to MCPServer/Models/
2. Add persistence to TaskDatabase.cs (table + CRUD methods + migration)
3. Add routing to MessageBroker.cs (methods + events)
4. Add MCP tool to MCPServer/Tools/ (or index.js) if agents need access
5. Add REST endpoint to API/Controllers/ if HTTP access needed

Adding an MCP Tool

1. Add tool definition to the tools array in %APPDATA%\multiterminal\mcp\index.js
2. Add handler in the CallToolRequestSchema switch block in the same file
3. Tool handler calls the REST API which delegates to MessageBroker which delegates to TaskDatabase
4. Return formatted text result for the agent

Adding a REST Endpoint

1. Add method to the appropriate controller in API/Controllers/
2. Add request model class if needed (same file or separate)
3. Controller calls MessageBroker (for shared logic) or database directly (for reads)
4. Update ToolsController.cs to include the new endpoint in the self-documenting list

Data Storage Patterns

• Checklists: JSON array in checklist_json column: [{"item":"...","status":"pending|coding|testing|done","notes":[{"text":"...","at":"...","by":"..."}],"assignee":"...","cycleCount":0}]
• Plans: Markdown text in plan column
• Continuation notes: Free text in continuation_notes column (session handoff context)
• Skills/interests: JSON arrays in profile columns (skills_json, interests_json)
• Migrations: Manual column-check migrations in database constructors (uses PRAGMA table_info + ALTER TABLE ADD COLUMN)

Checklist State Machine

                    +----------+
                    | pending  |
                    +----+-----+
                         |
                    (start work)
                         |
                    +----v-----+
               +--->|  coding  |<---+
               |    +----+-----+    |
               |         |         |
          (fail/fix)  (submit)  (reject)
               |         |         |
               |    +----v-----+   |
               +----| testing  |---+
                    +----+-----+
                         |
                    (approve)
                         |
                    +----v-----+
                    |   done   |
                    +----------+

  Cycle count increments each coding->testing->coding loop.
  At 3 cycles, escalation inbox notification is sent to PM.

Folder Map

Codebase Statistics

• ~150 C# production files, ~30K+ lines of code
• 1 primary SQLite database (multiterminal.db) with 30+ tables
• 19 data models, ~90 MCP tools, ~25 REST controllers
• 11 UI panels (WebView2-based), 11 dialog windows
• REST API on port 5050, MCP server via Node.js (stdio transport)