# syamsuddin/odin architecture

> Architecture diagram of the GitHub repository syamsuddin/odin, 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/syamsuddin/odin
- Repository: https://github.com/syamsuddin/odin

## Overview

ODIN connects Claude Code on a laptop to Linux servers over SSH stdio MCP. The main workflow is natural-language intent → guarded tool call → project-specific server execution → results returned to Claude for analysis and iteration. The CLI separately manages server/project setup and administration. README capabilities are represented as server-agent responsibilities; the sampled excerpts do not expose every tool handler or its internal wiring.

Main entry points: [`server/odin_agent.py`](https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py) (MCP Agent), [`client/odin_guard.py`](https://github.com/syamsuddin/odin/blob/main/client/odin_guard.py) (Risk Guard), [`client/odin_mcp_launch.py`](https://github.com/syamsuddin/odin/blob/main/client/odin_mcp_launch.py) (MCP Launcher), [`server/odin-dispatch.sh`](https://github.com/syamsuddin/odin/blob/main/server/odin-dispatch.sh) (Forced Dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_laptop["Laptop Integration"]
  node_cli["ODIN CLI<br/>[odin_cli.py]"]
  node_guard["Risk Guard<br/>[odin_guard.py]"]
  node_launcher["MCP Launcher<br/>[odin_mcp_launch.py]"]
end

subgraph group_transport["SSH Transport"]
  node_dispatch["Forced Dispatcher<br/>[odin-dispatch.sh]"]
  node_run["Project Launcher<br/>[run.sh]"]
end

subgraph group_agent["Server Agent"]
  node_agentcore["MCP Agent<br/>[odin_agent.py]"]
  node_execution["Linux Commands<br/>[odin_agent.py]"]
  node_intelligence["Output Analysis<br/>[odin_agent.py]"]
  node_inspection["Server Inspection<br/>[odin_agent.py]"]
  node_deploy["Deploy Preflight<br/>[odin_agent.py]"]
  node_runbooks["Runbook Engine<br/>[odin_agent.py]"]
  node_rollback["Rollback Tracking<br/>[odin_agent.py]"]
end

subgraph group_state["Server State"]
  node_memory[("Persistent Memory<br/>[odin_agent.py]")]
  node_events[("Event Journal<br/>[odin_agent.py]")]
  node_audit[("Audit Log<br/>[odin_agent.py]")]
  node_watchdog["Watchdog<br/>[odin_agent.py]"]
end

node_user(("User"))
node_claude(("Claude Code"))
node_ssh["SSH"]
node_github["GitHub Updates"]

node_user -->|"gives intent"| node_claude
node_claude -->|"requests tool"| node_guard
node_guard -->|"allows or asks"| node_claude
node_claude -->|"spawns MCP"| node_launcher
node_launcher -->|"executes SSH"| node_ssh
node_cli -->|"provisions server"| node_ssh
node_ssh -->|"starts forced command"| node_dispatch
node_dispatch -->|"dispatches project"| node_run
node_run -->|"starts MCP agent"| node_agentcore
node_agentcore -->|"runs commands"| node_execution
node_execution -->|"returns output"| node_agentcore
node_agentcore -->|"analyzes results"| node_intelligence
node_agentcore -->|"provides inspection"| node_inspection
node_agentcore -->|"checks prerequisites"| node_deploy
node_agentcore -->|"serves runbooks"| node_runbooks
node_agentcore -->|"tracks state"| node_rollback
node_agentcore -->|"reads and writes"| node_memory
node_agentcore -->|"records events"| node_events
node_agentcore -->|"records activity"| node_audit
node_agentcore -->|"uses watchdog"| node_watchdog
node_agentcore -->|"returns MCP results"| node_claude
node_guard -.->|"checks updates"| node_github

click node_cli "https://github.com/syamsuddin/odin/blob/main/client/odin_cli.py"
click node_guard "https://github.com/syamsuddin/odin/blob/main/client/odin_guard.py"
click node_launcher "https://github.com/syamsuddin/odin/blob/main/client/odin_mcp_launch.py"
click node_dispatch "https://github.com/syamsuddin/odin/blob/main/server/odin-dispatch.sh"
click node_run "https://github.com/syamsuddin/odin/blob/main/server/run.sh"
click node_agentcore "https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py"
click node_execution "https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py"
click node_intelligence "https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py"
click node_inspection "https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py"
click node_deploy "https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py"
click node_runbooks "https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py"
click node_rollback "https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py"
click node_memory "https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py"
click node_events "https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py"
click node_audit "https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py"
click node_watchdog "https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py"

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_guard,node_launcher,node_user toneBlue
class node_dispatch,node_run toneAmber
class node_agentcore,node_execution,node_intelligence,node_inspection,node_deploy,node_runbooks,node_rollback toneMint
class node_memory,node_events,node_audit,node_watchdog toneRose
class node_claude,node_ssh,node_github toneIndigo
```

## Components

### Laptop Integration

- [ODIN CLI](https://github.com/syamsuddin/odin/blob/main/client/odin_cli.py): `client/odin_cli.py`
- [Risk Guard](https://github.com/syamsuddin/odin/blob/main/client/odin_guard.py): `client/odin_guard.py`
- [MCP Launcher](https://github.com/syamsuddin/odin/blob/main/client/odin_mcp_launch.py): `client/odin_mcp_launch.py`

### SSH Transport

- [Forced Dispatcher](https://github.com/syamsuddin/odin/blob/main/server/odin-dispatch.sh): `server/odin-dispatch.sh`
- [Project Launcher](https://github.com/syamsuddin/odin/blob/main/server/run.sh): `server/run.sh`

### Server Agent

- [MCP Agent](https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py): `server/odin_agent.py`
- [Linux Commands](https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py): `server/odin_agent.py`
- [Output Analysis](https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py): `server/odin_agent.py`
- [Server Inspection](https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py): `server/odin_agent.py`
- [Deploy Preflight](https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py): `server/odin_agent.py`
- [Runbook Engine](https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py): `server/odin_agent.py`
- [Rollback Tracking](https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py): `server/odin_agent.py`

### Server State

- [Persistent Memory](https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py): `server/odin_agent.py`
- [Event Journal](https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py): `server/odin_agent.py`
- [Audit Log](https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py): `server/odin_agent.py`
- [Watchdog](https://github.com/syamsuddin/odin/blob/main/server/odin_agent.py): `server/odin_agent.py`

### Other components

- **User**
- **Claude Code**
- **SSH**
- **GitHub Updates**

## Connections

- User → Claude Code: gives intent
- Claude Code → Risk Guard: requests tool
- Risk Guard → Claude Code: allows or asks
- Claude Code → MCP Launcher: spawns MCP
- MCP Launcher → SSH: executes SSH
- ODIN CLI → SSH: provisions server
- SSH → Forced Dispatcher: starts forced command
- Forced Dispatcher → Project Launcher: dispatches project
- Project Launcher → MCP Agent: starts MCP agent
- MCP Agent → Linux Commands: runs commands
- Linux Commands → MCP Agent: returns output
- MCP Agent → Output Analysis: analyzes results
- MCP Agent → Server Inspection: provides inspection
- MCP Agent → Deploy Preflight: checks prerequisites
- MCP Agent → Runbook Engine: serves runbooks
- MCP Agent → Rollback Tracking: tracks state
- MCP Agent → Persistent Memory: reads and writes
- MCP Agent → Event Journal: records events
- MCP Agent → Audit Log: records activity
- MCP Agent → Watchdog: uses watchdog
- MCP Agent → Claude Code: returns MCP results
- Risk Guard → GitHub Updates: checks updates