# t8y2/motty architecture

> Architecture diagram of the GitHub repository t8y2/motty, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/t8y2/motty
- Repository: https://github.com/t8y2/motty

## Overview

Motty is a native desktop SSH workspace. The main workflow is to organize or import a host, connect and verify its host key, then work in a shared session across a terminal, file transfer, tunnels, remote screens, monitoring, and an AI assistant. State and session history support that work; AI tools can also be exposed to external agents. The README documents the product branches, while the excerpts show app startup and MCP’s gate boundary; links for other unsampled subsystem implementations are therefore limited to documented behavior.

Main entry points: [`internal/sshconn/conn.go`](https://github.com/t8y2/motty/blob/main/internal/sshconn/conn.go) (SSH sessions), [`cmd/motty/main.go`](https://github.com/t8y2/motty/blob/main/cmd/motty/main.go) (Application startup), [`internal/workbench/host_catalog.go`](https://github.com/t8y2/motty/blob/main/internal/workbench/host_catalog.go) (Host catalog), [`internal/workbench/ai_panel.go`](https://github.com/t8y2/motty/blob/main/internal/workbench/ai_panel.go) (Assistant UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop workspace"]
  node_app["Application startup<br/>[main.go]"]
  node_workspace["Tabbed workspace<br/>[deck.go]"]
end

subgraph group_connect["Hosts and connections"]
  node_host_catalog["Host catalog<br/>[host_catalog.go]"]
  node_host_import["Host import<br/>[sessionimport.go]"]
  node_ssh["SSH sessions<br/>[conn.go]"]
  node_host_keys["Host key trust<br/>[knownhosts.go]"]
end

subgraph group_sessions["Session tools"]
  node_terminal["Terminal<br/>[parser.go]"]
  node_sftp["SFTP transfer<br/>[worker.go]"]
  node_forwarding["Port forwarding<br/>[forward.go]"]
  node_desktop["Remote desktops<br/>[session.go]"]
  node_vnc["VNC sessions<br/>[session.go]"]
  node_monitor["Remote monitoring<br/>[worker.go]"]
end

subgraph group_assistant["AI assistant"]
  node_ai_ui["Assistant UI<br/>[ai_panel.go]"]
  node_ai_agent["Agent sessions<br/>[session.go]"]
  node_ai_llm["LLM providers<br/>[llm.go]"]
  node_ai_mcp["MCP server<br/>[server.go]"]
  node_ai_gate["Tool approval gate<br/>[gate.go]"]
end

subgraph group_state["Persistence and sync"]
  node_config[("Configuration store<br/>[store.go]")]
  node_vault[("Credential vault<br/>[vault.go]")]
  node_session_logs[("Session logs<br/>[store.go]")]
  node_sync["Cloud sync<br/>[sync_engine.go]"]
end

node_user(("Desktop user"))
node_sync_service["Remote sync service"]
node_external_agent(("External AI client"))

node_user -->|"launches"| node_app
node_app -->|"opens workspace"| node_workspace
node_user -->|"organizes hosts"| node_host_catalog
node_user -->|"imports sessions"| node_host_import
node_host_catalog -->|"connects host"| node_ssh
node_ssh -->|"verifies fingerprint"| node_host_keys
node_ssh -->|"opens login shell"| node_terminal
node_ssh -->|"transfers files"| node_sftp
node_ssh -->|"owns tunnels"| node_forwarding
node_ssh -->|"tunnels RDP"| node_desktop
node_ssh -->|"tunnels VNC"| node_vnc
node_user -->|"views resources"| node_monitor
node_user -->|"asks assistant"| node_ai_ui
node_ai_ui -.->|"starts agent session"| node_ai_agent
node_ai_agent -.->|"requests completions"| node_ai_llm
node_external_agent -->|"sends MCP requests"| node_ai_mcp
node_ai_mcp -->|"routes tool calls"| node_ai_gate
node_user -->|"saves preferences"| node_config
node_user -->|"stores passwords"| node_vault
node_user -.->|"reviews sessions"| node_session_logs
node_user -.->|"runs sync"| node_sync
node_sync -->|"reads and writes backup"| node_sync_service

click node_app "https://github.com/t8y2/motty/blob/main/cmd/motty/main.go"
click node_workspace "https://github.com/t8y2/motty/blob/main/internal/workspace/deck.go"
click node_host_catalog "https://github.com/t8y2/motty/blob/main/internal/workbench/host_catalog.go"
click node_host_import "https://github.com/t8y2/motty/blob/main/internal/sessionimport/sessionimport.go"
click node_ssh "https://github.com/t8y2/motty/blob/main/internal/sshconn/conn.go"
click node_host_keys "https://github.com/t8y2/motty/blob/main/internal/knownhosts/knownhosts.go"
click node_terminal "https://github.com/t8y2/motty/blob/main/internal/term/parser.go"
click node_sftp "https://github.com/t8y2/motty/blob/main/internal/sftpclient/worker.go"
click node_forwarding "https://github.com/t8y2/motty/blob/main/internal/portforward/forward.go"
click node_desktop "https://github.com/t8y2/motty/blob/main/internal/desktop/rdp/session.go"
click node_vnc "https://github.com/t8y2/motty/blob/main/internal/desktop/vnc/session.go"
click node_monitor "https://github.com/t8y2/motty/blob/main/internal/remotestats/worker.go"
click node_ai_ui "https://github.com/t8y2/motty/blob/main/internal/workbench/ai_panel.go"
click node_ai_agent "https://github.com/t8y2/motty/blob/main/internal/ai/agent/session.go"
click node_ai_llm "https://github.com/t8y2/motty/blob/main/internal/ai/llm/llm.go"
click node_ai_mcp "https://github.com/t8y2/motty/blob/main/internal/ai/mcp/server.go"
click node_ai_gate "https://github.com/t8y2/motty/blob/main/internal/ai/gate/gate.go"
click node_config "https://github.com/t8y2/motty/blob/main/internal/configstore/store.go"
click node_vault "https://github.com/t8y2/motty/blob/main/internal/vault/vault.go"
click node_session_logs "https://github.com/t8y2/motty/blob/main/internal/sessionlog/store.go"
click node_sync "https://github.com/t8y2/motty/blob/main/internal/workbench/sync_engine.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_workspace,node_user,node_external_agent toneBlue
class node_host_catalog,node_host_import,node_ssh,node_host_keys toneAmber
class node_terminal,node_sftp,node_forwarding,node_desktop,node_vnc,node_monitor toneMint
class node_ai_ui,node_ai_agent,node_ai_llm,node_ai_mcp,node_ai_gate toneRose
class node_config,node_vault,node_session_logs,node_sync,node_sync_service toneIndigo
```

## Components

### Desktop workspace

- [Application startup](https://github.com/t8y2/motty/blob/main/cmd/motty/main.go): `cmd/motty/main.go`
- [Tabbed workspace](https://github.com/t8y2/motty/blob/main/internal/workspace/deck.go): `internal/workspace/deck.go`

### Hosts and connections

- [Host catalog](https://github.com/t8y2/motty/blob/main/internal/workbench/host_catalog.go): `internal/workbench/host_catalog.go`
- [Host import](https://github.com/t8y2/motty/blob/main/internal/sessionimport/sessionimport.go): `internal/sessionimport/sessionimport.go`
- [SSH sessions](https://github.com/t8y2/motty/blob/main/internal/sshconn/conn.go): `internal/sshconn/conn.go`
- [Host key trust](https://github.com/t8y2/motty/blob/main/internal/knownhosts/knownhosts.go): `internal/knownhosts/knownhosts.go`

### Session tools

- [Terminal](https://github.com/t8y2/motty/blob/main/internal/term/parser.go): `internal/term/parser.go`
- [SFTP transfer](https://github.com/t8y2/motty/blob/main/internal/sftpclient/worker.go): `internal/sftpclient/worker.go`
- [Port forwarding](https://github.com/t8y2/motty/blob/main/internal/portforward/forward.go): `internal/portforward/forward.go`
- [Remote desktops](https://github.com/t8y2/motty/blob/main/internal/desktop/rdp/session.go): `internal/desktop/rdp/session.go`
- [VNC sessions](https://github.com/t8y2/motty/blob/main/internal/desktop/vnc/session.go): `internal/desktop/vnc/session.go`
- [Remote monitoring](https://github.com/t8y2/motty/blob/main/internal/remotestats/worker.go): `internal/remotestats/worker.go`

### AI assistant

- [Assistant UI](https://github.com/t8y2/motty/blob/main/internal/workbench/ai_panel.go): `internal/workbench/ai_panel.go`
- [Agent sessions](https://github.com/t8y2/motty/blob/main/internal/ai/agent/session.go): `internal/ai/agent/session.go`
- [LLM providers](https://github.com/t8y2/motty/blob/main/internal/ai/llm/llm.go): `internal/ai/llm/llm.go`
- [MCP server](https://github.com/t8y2/motty/blob/main/internal/ai/mcp/server.go): `internal/ai/mcp/server.go`
- [Tool approval gate](https://github.com/t8y2/motty/blob/main/internal/ai/gate/gate.go): `internal/ai/gate/gate.go`

### Persistence and sync

- [Configuration store](https://github.com/t8y2/motty/blob/main/internal/configstore/store.go): `internal/configstore/store.go`
- [Credential vault](https://github.com/t8y2/motty/blob/main/internal/vault/vault.go): `internal/vault/vault.go`
- [Session logs](https://github.com/t8y2/motty/blob/main/internal/sessionlog/store.go): `internal/sessionlog/store.go`
- [Cloud sync](https://github.com/t8y2/motty/blob/main/internal/workbench/sync_engine.go): `internal/workbench/sync_engine.go`

### Other components

- **Desktop user**
- **Remote sync service**
- **External AI client**

## Connections

- Desktop user → Application startup: launches
- Application startup → Tabbed workspace: opens workspace (evidence: `cmd/motty/main.go`)
- Desktop user → Host catalog: organizes hosts
- Desktop user → Host import: imports sessions
- Host catalog → SSH sessions: connects host
- SSH sessions → Host key trust: verifies fingerprint
- SSH sessions → Terminal: opens login shell
- SSH sessions → SFTP transfer: transfers files
- SSH sessions → Port forwarding: owns tunnels
- SSH sessions → Remote desktops: tunnels RDP
- SSH sessions → VNC sessions: tunnels VNC
- Desktop user → Remote monitoring: views resources
- Desktop user → Assistant UI: asks assistant
- Assistant UI → Agent sessions: starts agent session
- Agent sessions → LLM providers: requests completions
- External AI client → MCP server: sends MCP requests (evidence: `internal/ai/mcp/server.go`)
- MCP server → Tool approval gate: routes tool calls (evidence: `internal/ai/mcp/server.go`)
- Desktop user → Configuration store: saves preferences
- Desktop user → Credential vault: stores passwords
- Desktop user → Session logs: reviews sessions
- Desktop user → Cloud sync: runs sync
- Cloud sync → Remote sync service: reads and writes backup (evidence: `internal/workbench/sync_engine.go`)