# seruman/hauntty architecture

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

- Interactive diagram: https://gitdiagram.com/seruman/hauntty
- Repository: https://github.com/seruman/hauntty

## Overview

hauntty is a terminal-session persistence service. The principal workflow is `ht` parsing a command and configuration, connecting over a Unix socket, then asking the daemon to create or reattach to a shell-backed PTY session; PTY output updates terminal state and is streamed to attached clients. The daemon also supports session control, inspection, screen dumps, and persistence/restoration of dead sessions. README capabilities inform the map; where handler source was not sampled, uncertain internal links are omitted.

Main entry points: [`internal/daemon/server.go`](https://github.com/seruman/hauntty/blob/main/internal/daemon/server.go) (Socket server), [`internal/client/client.go`](https://github.com/seruman/hauntty/blob/main/internal/client/client.go) (Client API), [`internal/daemon/session_lifecycle.go`](https://github.com/seruman/hauntty/blob/main/internal/daemon/session_lifecycle.go) (Session lifecycle), [`cmd/ht/main.go`](https://github.com/seruman/hauntty/blob/main/cmd/ht/main.go) (ht commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command line"]
  node_ht["ht commands<br/>[main.go]"]
  node_config["Configuration<br/>[config.go]"]
end

subgraph group_wire["Client transport"]
  node_client["Client API<br/>[client.go]"]
  node_attachclient["Attach client<br/>[attach.go]"]
  node_protocol["Wire messages<br/>[messages.go]"]
end

subgraph group_daemon["Daemon sessions"]
  node_server["Socket server<br/>[server.go]"]
  node_control["Session controls<br/>[server_control.go]"]
  node_inspect["Session inspection<br/>[server_inspect.go]"]
  node_attachserver["Attach handling<br/>[server_attach.go]"]
  node_session["Session lifecycle"]
  node_clients["Attached clients<br/>[session_clients.go]"]
  node_persist[("Saved sessions<br/>[persist.go]")]
  node_socketpath["Socket paths<br/>[paths.go]"]
end

subgraph group_terminal["Terminal state"]
  node_state["Terminal state<br/>[terminal_state.go]"]
  node_ghostty["VT engine<br/>[terminal.go]"]
  node_dump["Screen dumps<br/>[dump.go]"]
end

node_user(("Terminal user"))
node_shell["Shell in PTY"]

node_user -->|"runs commands"| node_ht
node_ht -->|"loads settings"| node_config
node_ht -->|"invokes operations"| node_client
node_client -->|"resolves socket"| node_socketpath
node_client -->|"encodes requests"| node_protocol
node_client -->|"sends over socket"| node_server
node_server -->|"decodes messages"| node_protocol
node_server -->|"dispatches controls"| node_control
node_server -->|"dispatches inspection"| node_inspect
node_server -->|"dispatches attach"| node_attachserver
node_control -->|"controls sessions"| node_session
node_attachserver -->|"attaches to session"| node_session
node_session -->|"starts PTY process"| node_shell
node_shell -->|"writes PTY output"| node_session
node_session -->|"feeds terminal bytes"| node_state
node_state -->|"updates VT state"| node_ghostty
node_attachserver -->|"registers client"| node_clients
node_clients -->|"streams output"| node_protocol
node_inspect -->|"formats screen"| node_dump
node_state -->|"provides screen state"| node_dump
node_server -.->|"persists sessions"| node_persist
node_persist -.->|"restores sessions"| node_server
node_attachclient -->|"uses client API"| node_client
node_client -->|"runs interactive attach"| node_attachclient

click node_ht "https://github.com/seruman/hauntty/blob/main/cmd/ht/main.go"
click node_config "https://github.com/seruman/hauntty/blob/main/internal/config/config.go"
click node_client "https://github.com/seruman/hauntty/blob/main/internal/client/client.go"
click node_attachclient "https://github.com/seruman/hauntty/blob/main/internal/client/attach.go"
click node_protocol "https://github.com/seruman/hauntty/blob/main/internal/protocol/messages.go"
click node_server "https://github.com/seruman/hauntty/blob/main/internal/daemon/server.go"
click node_control "https://github.com/seruman/hauntty/blob/main/internal/daemon/server_control.go"
click node_inspect "https://github.com/seruman/hauntty/blob/main/internal/daemon/server_inspect.go"
click node_attachserver "https://github.com/seruman/hauntty/blob/main/internal/daemon/server_attach.go"
click node_session "https://github.com/seruman/hauntty/blob/main/internal/daemon/session_lifecycle.go"
click node_clients "https://github.com/seruman/hauntty/blob/main/internal/daemon/session_clients.go"
click node_state "https://github.com/seruman/hauntty/blob/main/internal/daemon/terminal_state.go"
click node_ghostty "https://github.com/seruman/hauntty/blob/main/libghostty/terminal.go"
click node_dump "https://github.com/seruman/hauntty/blob/main/internal/protocol/dump.go"
click node_persist "https://github.com/seruman/hauntty/blob/main/internal/daemon/persist.go"
click node_socketpath "https://github.com/seruman/hauntty/blob/main/internal/config/paths.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_ht,node_config,node_user toneBlue
class node_client,node_attachclient,node_protocol toneAmber
class node_server,node_control,node_inspect,node_attachserver,node_session,node_clients,node_persist,node_socketpath toneMint
class node_state,node_ghostty,node_dump toneRose
class node_shell toneIndigo
```

## Components

### Command line

- [ht commands](https://github.com/seruman/hauntty/blob/main/cmd/ht/main.go): `cmd/ht/main.go`
- [Configuration](https://github.com/seruman/hauntty/blob/main/internal/config/config.go): `internal/config/config.go`

### Client transport

- [Client API](https://github.com/seruman/hauntty/blob/main/internal/client/client.go): `internal/client/client.go`
- [Attach client](https://github.com/seruman/hauntty/blob/main/internal/client/attach.go): `internal/client/attach.go`
- [Wire messages](https://github.com/seruman/hauntty/blob/main/internal/protocol/messages.go): `internal/protocol/messages.go`

### Daemon sessions

- [Socket server](https://github.com/seruman/hauntty/blob/main/internal/daemon/server.go): `internal/daemon/server.go`
- [Session controls](https://github.com/seruman/hauntty/blob/main/internal/daemon/server_control.go): `internal/daemon/server_control.go`
- [Session inspection](https://github.com/seruman/hauntty/blob/main/internal/daemon/server_inspect.go): `internal/daemon/server_inspect.go`
- [Attach handling](https://github.com/seruman/hauntty/blob/main/internal/daemon/server_attach.go): `internal/daemon/server_attach.go`
- [Session lifecycle](https://github.com/seruman/hauntty/blob/main/internal/daemon/session_lifecycle.go): `internal/daemon/session_lifecycle.go`
- [Attached clients](https://github.com/seruman/hauntty/blob/main/internal/daemon/session_clients.go): `internal/daemon/session_clients.go`
- [Saved sessions](https://github.com/seruman/hauntty/blob/main/internal/daemon/persist.go): `internal/daemon/persist.go`
- [Socket paths](https://github.com/seruman/hauntty/blob/main/internal/config/paths.go): `internal/config/paths.go`

### Terminal state

- [Terminal state](https://github.com/seruman/hauntty/blob/main/internal/daemon/terminal_state.go): `internal/daemon/terminal_state.go`
- [VT engine](https://github.com/seruman/hauntty/blob/main/libghostty/terminal.go): `libghostty/terminal.go`
- [Screen dumps](https://github.com/seruman/hauntty/blob/main/internal/protocol/dump.go): `internal/protocol/dump.go`

### Other components

- **Terminal user**
- **Shell in PTY**

## Connections

- Terminal user → ht commands: runs commands
- ht commands → Configuration: loads settings
- ht commands → Client API: invokes operations
- Client API → Socket paths: resolves socket
- Client API → Wire messages: encodes requests
- Client API → Socket server: sends over socket
- Socket server → Wire messages: decodes messages
- Socket server → Session controls: dispatches controls
- Socket server → Session inspection: dispatches inspection
- Socket server → Attach handling: dispatches attach
- Session controls → Session lifecycle: controls sessions
- Attach handling → Session lifecycle: attaches to session
- Session lifecycle → Shell in PTY: starts PTY process
- Shell in PTY → Session lifecycle: writes PTY output
- Session lifecycle → Terminal state: feeds terminal bytes
- Terminal state → VT engine: updates VT state
- Attach handling → Attached clients: registers client
- Attached clients → Wire messages: streams output
- Session inspection → Screen dumps: formats screen
- Terminal state → Screen dumps: provides screen state
- Socket server → Saved sessions: persists sessions
- Saved sessions → Socket server: restores sessions
- Attach client → Client API: uses client API
- Client API → Attach client: runs interactive attach