🌓

Troubleshooting / FAQ

Concrete fixes for the issues you are most likely to hit: port conflicts on 5050, MCP tools not connecting, database location and backup, resetting the docking layout, frozen terminals, the WebView2 runtime, and where the logs live.

Key paths & ports at a glance

What	Where
REST API	http://localhost:5050 (loopback only)
MCP server (Node.js)	%APPDATA%\multiterminal\mcp\ (entry point index.js)
Main database	%APPDATA%\multiterminal\multiterminal.db
Message queue database	%APPDATA%\multiterminal\messages.db
Startup error log	%APPDATA%\multiterminal\startup-error.log
Worktrees (when enabled)	<project>\.claude\worktrees\

On Windows, paste %APPDATA%\multiterminal straight into the File Explorer address bar to open that folder.

REST API / port 5050 conflicts

MultiTerminal hosts its REST API on localhost:5050. Every MCP tool and panel talks to that port, so a conflict breaks task, chat, and code-graph operations across the app.

Symptoms: the app launches but tasks/chat never load; MCP tools time out or return connection errors.

Check what owns the port (PowerShell):

Get-NetTCPConnection -LocalPort 5050 -State Listen |
  Select-Object LocalAddress, OwningProcess
Get-Process -Id (Get-NetTCPConnection -LocalPort 5050 -State Listen).OwningProcess

Fixes:

• A stale MultiTerminal process is the usual culprit — fully exit any prior instance (check the system tray and Task Manager) before relaunching.
• If a genuinely unrelated process owns 5050, stop it, then relaunch MultiTerminal.
• Confirm the API is healthy once the app is up: curl http://localhost:5050/health should return {"status":"healthy","port":5050}.

MCP tools not connecting

The MCP server is a Node.js process under %APPDATA%\multiterminal\mcp\. Its tools are thin wrappers that call the REST API on localhost:5050, so MCP problems are usually really API-or-path problems.

Work through these in order:

• Is the app running? The MCP tools need MultiTerminal open so the API on 5050 is listening. Start the app first.
• Is the API up? curl http://localhost:5050/health. If that fails, fix the port first — the MCP layer can't work without it.
• Does the MCP folder exist? Confirm %APPDATA%\multiterminal\mcp\index.js is present. MultiTerminal provisions this on startup; if it's missing, restart the app to let it re-provision.
• Is Node.js available? The MCP server runs under Node; node --version should succeed on your PATH.
• Restart the client. After fixing the above, restart your Claude Code session so it re-handshakes with the MCP server.

Running from source: is the plugin required?

If you build MultiTerminal from source (no installer), the app runs fine on its own — but the multiterminal-marketplace Claude Code plugin is what wires terminals into the coordination features. A common question is how load-bearing it actually is, and whether installing it pollutes your other Claude Code sessions. Short answers: very, and no.

The plugin does not leak into non-MultiTerminal sessions. MT launches every hosted terminal with an explicit --plugin-dir flag pointing into the marketplace folder, so the plugin's hooks, skills, agents, and CLAUDE.md load only in MT-spawned terminals. The directory under ~/.claude/plugins/marketplaces/ is just the file source that flag points at — its presence alone does not activate the plugin anywhere else (that would require enabledPlugins or --plugin-dir, neither of which MT sets globally). Registering the MCP servers globally in ~/.claude.json is a separate, opt-in installer component that defaults to off.

To install the plugin from source (no installer needed):

git clone https://github.com/ClarionLive/multiterminal-marketplace ^
  "%USERPROFILE%\.claude\plugins\marketplaces\multiterminal-marketplace"

MultiTerminal resolves that exact path at launch and passes it to each terminal via --plugin-dir.

What works without the plugin:

• The REST API on 5050, the task board and all UI panels, the project registry, and the code graph
• All multiterminal MCP tools (task CRUD, list_projects, code search, …) once the MCP server is wired up

What stays dark without the plugin:

• Terminal identity — the SessionStart hook registers each session as a named agent; without it list_terminals stays empty and agents can't claim tasks or message as themselves
• Session continuity — session-to-DB sync feeds get_latest_session, session memory search, and cross-session handoff notes
• The workflow layer — the kanban lifecycle skills, reviewer/verifier agents, and agent behavioral rules (CLAUDE.md)
• Activity feed and inter-agent messaging notifications (the channel MCP server ships inside the plugin)

Verdict: if you only want a dashboard plus an MCP toolset for a single terminal, you can skip the plugin and add it later in minutes. If you want the actual multi-terminal coordination — named agents, task handoffs, session memory — the plugin is the nervous system, and it costs nothing in your non-MT sessions.

Database location & backup

MultiTerminal stores its data in SQLite under %APPDATA%\multiterminal\:

• multiterminal.db — tasks, checklists, sessions, knowledge, profiles, projects, and the code graph (all in one file).
• messages.db — the inter-terminal message queue.

To back up: close MultiTerminal completely, then copy the .db files somewhere safe. Closing first matters — SQLite uses write-ahead logging (WAL), so copying while the app is running can capture a half-written state.

# PowerShell — back up both databases with the app closed
$src = "$env:APPDATA\multiterminal"
$dst = "$env:USERPROFILE\Desktop\mt-backup"
New-Item -ItemType Directory -Force $dst | Out-Null
Copy-Item "$src\multiterminal.db" $dst
Copy-Item "$src\messages.db" $dst

To restore: close the app and copy the saved .db files back over the ones in %APPDATA%\multiterminal\.

Resetting the docking layout

MultiTerminal's panels are arranged with a docking layout manager, and the layout is persisted between runs. If panels end up off-screen, collapsed to zero size, or otherwise wedged:

• Use the toolbar toggle buttons to hide and re-show the affected panel — panels are hidden on close (not destroyed), so toggling re-docks them.
• If the whole layout is corrupt, exit the app and remove the persisted layout file in %APPDATA%\multiterminal\ (the docking-layout file), then relaunch to rebuild the default arrangement. Your tasks and chat history live in the databases, so they are unaffected.

Frozen terminal / respawn

Each terminal hosts a real shell process (ConPTY). If one stops responding — no echo, no output, a hung command:

• Click into the terminal and press Ctrl+C to interrupt a stuck foreground command.
• If it's truly frozen, close that terminal tab and open a new one — this respawns a fresh shell process. Other terminals and panels are unaffected.
• A frozen agent terminal (a spawned teammate) can likewise be closed and re-spawned; its task state persists in the database, so a new session can pick the task back up from its continuation notes.

WebView2 runtime

Most of MultiTerminal's panels (Tasks, Chat, Activity, Office, and others) render in embedded WebView2 controls, which require the Microsoft Edge WebView2 Runtime.

Symptoms of a missing/broken runtime: panels are blank or white, or the app errors on startup referencing WebView2.

Fix: install the Evergreen WebView2 Runtime from Microsoft (it ships with current Windows 11 but can be absent or outdated on older images), then relaunch. WebView2's own user-data cache lives under your local app data; a corrupt cache is rare but clears by reinstalling the runtime.

Phone / Multi-Connect won't connect

Multi-Connect publishes MultiTerminal to your phone over your private Tailscale network (see Multi-Connect). Most connection failures fall into one of three buckets:

• Phone can't reach https://<host>.ts.net at all. Confirm both the PC and the phone are signed in to the same tailnet and that Tailscale is up on each. Then confirm MagicDNS is enabled (Tailscale admin console → DNS) — without it there is no .ts.net hostname for the phone to open. Verify tailscale serve is running on the PC and the hostname matches what the settings tab's Detect button reports.
• Login returns 503. The phone gateway fails closed: login is disabled until both the phone username and password are changed away from their default changeme placeholders. Set them in the Multi-Connect settings tab, then retry. This is deliberate — it stops the app from ever sitting open on your tailnet with default credentials.
• Connected, but push notifications don't arrive. Web Push needs a VAPID keypair configured (the settings tab / setup skill manage the keys; you normally only set the VAPID subject).

Code-graph search returns 503 "CodeGraph not available"

The code-graph endpoints (/api/code-graph/search, /callers, /callees, /impact, /inheritance) and the matching MCP tools return 503 {"error":"CodeGraph not available"} when the project hasn't been indexed yet. The CodeGraphWatcher background service normally indexes every registered C# project automatically — it sweeps and refreshes stale graphs shortly after app startup, and re-indexes on edit — so a 503 usually means one of:

• The startup sweep hasn't finished. Right after launch there's a brief window before the watcher's first index completes. Wait a few seconds and retry; GET /api/code-graph/stats shows the last-indexed time.
• The directory isn't a watched project. The watcher only indexes registered projects that have a top-level .csproj. A loose directory (or a src/-style layout with no root .csproj) is never auto-indexed.
• Auto-indexing is disabled. MULTITERMINAL_CODEGRAPH_WATCH is set to 0/false/off.

Fix: for a registered project, just wait for the startup sweep (or check it's eligible / not disabled). To index any directory immediately — including one that isn't a registered project — run the index_code_graph MCP tool or POST /api/code-graph/index with the project directory. You generally don't need to re-index after edits anymore; the watcher handles that.

Where to see logs

• Debug panel. The in-app Debug panel is the first place to look — it streams live diagnostic output (including remote-mode changes, worktree strands, and service warnings). Toggle it from the toolbar.
• Startup errors. If the app fails early (before panels load), check %APPDATA%\multiterminal\startup-error.log.
• API health. curl http://localhost:5050/health and curl http://localhost:5050/api/tools confirm the API is up and list every available endpoint.