Component Overview
This diagram shows how hooks, the daemon, the relay, mech-storage, and remote approvers fit together.
flowchart LR
subgraph DevMachine[Developer Machine]
IDE["Claude Code + Editor"]
Hooks["Hooks\n(session_start.mjs, pre_tool_use.mjs)"]
Daemon["Teleportation Daemon\n(teleportation-daemon.js)"]
end
subgraph RelayCloud[Relay + Storage]
Relay["Teleportation Relay API\n(relay/server.js)"]
Storage[("mech-storage\nsessions / approvals / messages / results")]
end
RemoteUser["Remote Approver\n(Mobile/Web UI)"]
IDE -->|"1. User runs 'claude'\nstarts session"| Hooks
Hooks -->|"2. Register session"| Daemon
Hooks -->|"3. Register session"| Relay
IDE -->|"4. User runs a tool\n(command request)"| Hooks
Hooks -->|"5. Create approval\n+ optional daemon handoff"| Relay
Daemon -->|"6. Poll approvals /\nsubmit results"| Relay
Relay -->|"7. Persist state"| Storage
RemoteUser -->|"8. Review & approve\n(or deny) commands"| Relay
Relay -->|"9. Status, results"| IDE
End-to-End Command Flow
This sequence shows the lifecycle of a single approved command from Claude through the daemon and relay, and back.
sequenceDiagram
participant User as Dev User
participant IDE as Claude Code
participant HookStart as session_start.mjs
participant HookTool as pre_tool_use.mjs
participant Daemon as Teleportation Daemon
participant Relay as Relay API
participant Storage as mech-storage
participant Remote as Remote Approver
User->>IDE: Run `claude`
IDE->>HookStart: Invoke session_start hook
HookStart->>Relay: POST /api/sessions/register
Relay->>Storage: Create/Update session doc
HookStart->>Daemon: POST /sessions/register
User->>IDE: Use tool (e.g. Bash `touch ...`)
IDE->>HookTool: Invoke pre_tool_use hook
HookTool->>Relay: POST /api/approvals (status=pending)
HookTool->>Daemon: Optional handoff / bookkeeping
Relay->>Storage: Store approval
loop every 5s
Daemon->>Relay: GET /api/approvals?status=allowed&session_id=...
Relay-->>Daemon: Pending/allowed approvals
end
Remote->>Relay: POST /api/approvals/:id/decision (allowed/denied)
Relay->>Storage: Update approval status
Daemon->>Relay: GET /api/approvals?status=allowed
Relay-->>Daemon: Approved approval
Daemon->>Relay: GET /api/sessions/:id/daemon-state (validate session)
Relay-->>Daemon: 200 OK (valid session)
Note over Daemon: Execute command (currently via shell\n in testing; designed to be via Claude CLI in production)
Daemon->>Relay: POST /api/sessions/:id/results (store result)
Relay->>Storage: Persist result
IDE->>HookTool: Next tool use
HookTool->>Relay: GET /api/sessions/:id/results/pending
Relay-->>HookTool: Pending result(s)
HookTool-->>IDE: Deny tool + show results to user