# msh-protocol/msh architecture

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

- Interactive diagram: https://gitdiagram.com/msh-protocol/msh
- Repository: https://github.com/msh-protocol/msh

## Overview

msh is a safety-focused command-execution runtime for AI agents, with CLI, HTTP, MCP, and SDK entry points. The principal workflow accepts a command, executes it through a session-aware runtime, and returns structured, sanitized output; supported capabilities include prompt handling, secret redaction, truncation, file-change tracking, rollback, and run verification. A separate fleet hub registers worker daemons, relays commands and streams, and provides a telemetry dashboard. Some subsystem wiring is based on README capabilities and the file tree because those implementations were not sampled.

Main entry points: [`pkg/execution/executor.go`](https://github.com/msh-protocol/msh/blob/main/pkg/execution/executor.go) (Command executor), [`pkg/fleet/server.go`](https://github.com/msh-protocol/msh/blob/main/pkg/fleet/server.go) (Fleet hub), [`cmd/msh/main.go`](https://github.com/msh-protocol/msh/blob/main/cmd/msh/main.go) (CLI commands), [`pkg/server/server.go`](https://github.com/msh-protocol/msh/blob/main/pkg/server/server.go) (HTTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Agent interfaces"]
  node_cli["CLI commands<br/>[main.go]"]
  node_python["Python client<br/>[client.py]"]
  node_typescript["TypeScript client<br/>[index.ts]"]
  node_mcp["MCP server<br/>[server.go]"]
  node_http["HTTP server<br/>[server.go]"]
end

subgraph group_runtime["Execution runtime"]
  node_sessions["Session manager<br/>[manager.go]"]
  node_executor["Command executor<br/>[executor.go]"]
  node_engines["Execution engines<br/>[engine.go]"]
  node_prompts["Prompt handling"]
  node_sanitize["Output protection<br/>[sanitize.go]"]
  node_errors["Error extraction<br/>[error_extractor.go]"]
  node_fswatch["Change tracking<br/>[watcher.go]"]
  node_hooks["Execution hooks<br/>[hooks.go]"]
end

subgraph group_recovery["Run history and recovery"]
  node_db[("Execution history<br/>[db.go]")]
  node_undo["Undo command<br/>[undo.go]"]
  node_rollback["Diff rollback<br/>[rollback.go]"]
  node_verify["Run verification<br/>[verify.go]"]
end

subgraph group_fleet["Fleet control plane"]
  node_fleetcli["Fleet command<br/>[fleet.go]"]
  node_fleetserver["Fleet hub<br/>[server.go]"]
  node_node["Worker daemon<br/>[node.go]"]
  node_daemon["Background processes<br/>[manager.go]"]
  node_dashboard["Fleet dashboard<br/>[App.tsx]"]
end

node_agent(("Agent or user"))
node_workers(("Worker machines"))
node_workspace["Command workspace"]

node_agent -->|"runs commands"| node_cli
node_agent -->|"calls client"| node_python
node_agent -->|"calls client"| node_typescript
node_agent -->|"invokes tool"| node_mcp
node_python -.->|"runs CLI"| node_cli
node_python -.->|"posts commands"| node_http
node_typescript -.->|"posts commands"| node_http
node_cli -->|"executes"| node_executor
node_mcp -->|"gets session"| node_sessions
node_mcp -->|"executes"| node_executor
node_http -->|"gets session"| node_sessions
node_http -->|"executes"| node_executor
node_sessions -->|"provides session"| node_executor
node_executor -->|"runs command"| node_engines
node_engines -->|"executes in"| node_workspace
node_executor -->|"handles prompts"| node_prompts
node_executor -->|"sanitizes output"| node_sanitize
node_executor -->|"extracts causes"| node_errors
node_executor -->|"tracks changes"| node_fswatch
node_executor -->|"runs hooks"| node_hooks
node_cli -->|"saves execution"| node_db
node_fleetserver -->|"stores history"| node_db
node_undo -->|"reverts changes"| node_rollback
node_verify -->|"reads run record"| node_db
node_fleetcli -->|"starts hub"| node_fleetserver
node_dashboard -->|"calls APIs"| node_fleetserver
node_fleetserver -->|"registers and relays"| node_node
node_node -->|"streams results"| node_fleetserver
node_workers -->|"connects"| node_node
node_fleetserver -->|"manages daemons"| node_daemon

click node_cli "https://github.com/msh-protocol/msh/blob/main/cmd/msh/main.go"
click node_python "https://github.com/msh-protocol/msh/blob/main/packages/python/msh/client.py"
click node_typescript "https://github.com/msh-protocol/msh/blob/main/packages/typescript/src/index.ts"
click node_mcp "https://github.com/msh-protocol/msh/blob/main/pkg/mcp/server.go"
click node_http "https://github.com/msh-protocol/msh/blob/main/pkg/server/server.go"
click node_sessions "https://github.com/msh-protocol/msh/blob/main/pkg/execution/manager.go"
click node_executor "https://github.com/msh-protocol/msh/blob/main/pkg/execution/executor.go"
click node_engines "https://github.com/msh-protocol/msh/blob/main/pkg/execution/engine.go"
click node_prompts "https://github.com/msh-protocol/msh/blob/main/pkg/execution/prompt_responder.go"
click node_sanitize "https://github.com/msh-protocol/msh/blob/main/pkg/sanitize/sanitize.go"
click node_errors "https://github.com/msh-protocol/msh/blob/main/pkg/sanitize/error_extractor.go"
click node_fswatch "https://github.com/msh-protocol/msh/blob/main/pkg/fs/watcher.go"
click node_hooks "https://github.com/msh-protocol/msh/blob/main/pkg/hooks/hooks.go"
click node_db "https://github.com/msh-protocol/msh/blob/main/pkg/db/db.go"
click node_undo "https://github.com/msh-protocol/msh/blob/main/cmd/msh/undo.go"
click node_rollback "https://github.com/msh-protocol/msh/blob/main/pkg/fs/rollback.go"
click node_verify "https://github.com/msh-protocol/msh/blob/main/pkg/execution/verify.go"
click node_fleetcli "https://github.com/msh-protocol/msh/blob/main/cmd/msh/fleet.go"
click node_fleetserver "https://github.com/msh-protocol/msh/blob/main/pkg/fleet/server.go"
click node_node "https://github.com/msh-protocol/msh/blob/main/pkg/fleet/node.go"
click node_daemon "https://github.com/msh-protocol/msh/blob/main/pkg/daemon/manager.go"
click node_dashboard "https://github.com/msh-protocol/msh/blob/main/fleet-ui/src/App.tsx"

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_cli,node_python,node_typescript,node_mcp,node_http,node_agent toneBlue
class node_sessions,node_executor,node_engines,node_prompts,node_sanitize,node_errors,node_fswatch,node_hooks toneAmber
class node_db,node_undo,node_rollback,node_verify toneMint
class node_fleetcli,node_fleetserver,node_node,node_daemon,node_dashboard,node_workers toneRose
class node_workspace toneIndigo
```

## Components

### Agent interfaces

- [CLI commands](https://github.com/msh-protocol/msh/blob/main/cmd/msh/main.go): `cmd/msh/main.go`
- [Python client](https://github.com/msh-protocol/msh/blob/main/packages/python/msh/client.py): `packages/python/msh/client.py`
- [TypeScript client](https://github.com/msh-protocol/msh/blob/main/packages/typescript/src/index.ts): `packages/typescript/src/index.ts`
- [MCP server](https://github.com/msh-protocol/msh/blob/main/pkg/mcp/server.go): `pkg/mcp/server.go`
- [HTTP server](https://github.com/msh-protocol/msh/blob/main/pkg/server/server.go): `pkg/server/server.go`

### Execution runtime

- [Session manager](https://github.com/msh-protocol/msh/blob/main/pkg/execution/manager.go): `pkg/execution/manager.go`
- [Command executor](https://github.com/msh-protocol/msh/blob/main/pkg/execution/executor.go): `pkg/execution/executor.go`
- [Execution engines](https://github.com/msh-protocol/msh/blob/main/pkg/execution/engine.go): `pkg/execution/engine.go`
- [Prompt handling](https://github.com/msh-protocol/msh/blob/main/pkg/execution/prompt_responder.go): `pkg/execution/prompt_responder.go`
- [Output protection](https://github.com/msh-protocol/msh/blob/main/pkg/sanitize/sanitize.go): `pkg/sanitize/sanitize.go`
- [Error extraction](https://github.com/msh-protocol/msh/blob/main/pkg/sanitize/error_extractor.go): `pkg/sanitize/error_extractor.go`
- [Change tracking](https://github.com/msh-protocol/msh/blob/main/pkg/fs/watcher.go): `pkg/fs/watcher.go`
- [Execution hooks](https://github.com/msh-protocol/msh/blob/main/pkg/hooks/hooks.go): `pkg/hooks/hooks.go`

### Run history and recovery

- [Execution history](https://github.com/msh-protocol/msh/blob/main/pkg/db/db.go): `pkg/db/db.go`
- [Undo command](https://github.com/msh-protocol/msh/blob/main/cmd/msh/undo.go): `cmd/msh/undo.go`
- [Diff rollback](https://github.com/msh-protocol/msh/blob/main/pkg/fs/rollback.go): `pkg/fs/rollback.go`
- [Run verification](https://github.com/msh-protocol/msh/blob/main/pkg/execution/verify.go): `pkg/execution/verify.go`

### Fleet control plane

- [Fleet command](https://github.com/msh-protocol/msh/blob/main/cmd/msh/fleet.go): `cmd/msh/fleet.go`
- [Fleet hub](https://github.com/msh-protocol/msh/blob/main/pkg/fleet/server.go): `pkg/fleet/server.go`
- [Worker daemon](https://github.com/msh-protocol/msh/blob/main/pkg/fleet/node.go): `pkg/fleet/node.go`
- [Background processes](https://github.com/msh-protocol/msh/blob/main/pkg/daemon/manager.go): `pkg/daemon/manager.go`
- [Fleet dashboard](https://github.com/msh-protocol/msh/blob/main/fleet-ui/src/App.tsx): `fleet-ui/src/App.tsx`

### Other components

- **Agent or user**
- **Worker machines**
- **Command workspace**

## Connections

- Agent or user → CLI commands: runs commands
- Agent or user → Python client: calls client
- Agent or user → TypeScript client: calls client
- Agent or user → MCP server: invokes tool
- Python client → CLI commands: runs CLI
- Python client → HTTP server: posts commands
- TypeScript client → HTTP server: posts commands
- CLI commands → Command executor: executes
- MCP server → Session manager: gets session
- MCP server → Command executor: executes
- HTTP server → Session manager: gets session
- HTTP server → Command executor: executes
- Session manager → Command executor: provides session
- Command executor → Execution engines: runs command
- Execution engines → Command workspace: executes in
- Command executor → Prompt handling: handles prompts
- Command executor → Output protection: sanitizes output
- Command executor → Error extraction: extracts causes
- Command executor → Change tracking: tracks changes
- Command executor → Execution hooks: runs hooks
- CLI commands → Execution history: saves execution
- Fleet hub → Execution history: stores history
- Undo command → Diff rollback: reverts changes
- Run verification → Execution history: reads run record
- Fleet command → Fleet hub: starts hub
- Fleet dashboard → Fleet hub: calls APIs
- Fleet hub → Worker daemon: registers and relays
- Worker daemon → Fleet hub: streams results
- Worker machines → Worker daemon: connects
- Fleet hub → Background processes: manages daemons