# arisros/tmux-agent-deck architecture

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

- Interactive diagram: https://gitdiagram.com/arisros/tmux-agent-deck
- Repository: https://github.com/arisros/tmux-agent-deck

## Overview

tmux-agent-deck is a Claude Code agent-state dashboard implemented as a tmux plugin. Claude hooks send events to `deck`; the hook adapter maps them to state-machine events, the deck persists session state and publishes pane options, and tmux formats and views expose that state. Users reach agents through the popup, sidebar, tabs, and borders. Separate documented capabilities include screen-based reconciliation, usage and plan reporting, sounds, and installation checks. Relationships for unsampled modules are included only where the README or source index supports them.

Main entry points: [`cmd/deck/hookcmd.go`](https://github.com/arisros/tmux-agent-deck/blob/main/cmd/deck/hookcmd.go) (Hook commands), [`cmd/deck/viewcmd.go`](https://github.com/arisros/tmux-agent-deck/blob/main/cmd/deck/viewcmd.go) (View commands), [`cmd/deck/main.go`](https://github.com/arisros/tmux-agent-deck/blob/main/cmd/deck/main.go) (Command dispatch), [`internal/tmux/tmux.go`](https://github.com/arisros/tmux-agent-deck/blob/main/internal/tmux/tmux.go) (tmux operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Commands and setup"]
  node_main["Command dispatch<br/>[main.go]"]
  node_hookcmd["Hook commands<br/>[hookcmd.go]"]
  node_installer["Settings installer<br/>[installcmd.go]"]
  node_installlib["Settings editing<br/>[install.go]"]
  node_tmuxinit["tmux setup<br/>[tmuxinit.go]"]
end

subgraph group_state["Agent state"]
  node_hooks["Hook mapping<br/>[hook.go]"]
  node_machine["State machine<br/>[machine.go]"]
  node_deck["State adapter<br/>[deck.go]"]
  node_store[("Session records<br/>[store.go]")]
  node_record["Event recorder<br/>[record.go]"]
  node_tmuxlib["tmux operations<br/>[tmux.go]"]
end

subgraph group_views["Views and display"]
  node_views["View commands<br/>[viewcmd.go]"]
  node_rows["Agent rows<br/>[rows.go]"]
  node_viewrender["Popup and sidebar<br/>[views.go]"]
end

subgraph group_usage["Usage and diagnostics"]
  node_usage[("Usage tracking<br/>[usage.go]")]
  node_doctor["Installation checks<br/>[doctor.go]"]
end

node_user(("tmux user"))
node_claude(("Claude Code"))
node_tmux["tmux server"]

node_user -->|"invokes commands"| node_main
node_main -->|"dispatches hooks"| node_hookcmd
node_main -->|"dispatches views"| node_views
node_main -->|"dispatches setup"| node_installer
node_main -->|"dispatches setup"| node_tmuxinit
node_claude -->|"sends hook events"| node_hookcmd
node_hookcmd -->|"decodes events"| node_hooks
node_hooks -->|"maps events"| node_machine
node_hookcmd -->|"applies events"| node_deck
node_deck -->|"updates state"| node_machine
node_deck -->|"loads and saves"| node_store
node_deck -->|"publishes options"| node_tmuxlib
node_tmuxlib -->|"runs commands"| node_tmux
node_claude -.->|"optional event trace"| node_record
node_hookcmd -->|"records events"| node_record
node_user -->|"opens popup or sidebar"| node_views
node_views -->|"queries panes"| node_tmuxlib
node_views -->|"builds agent rows"| node_rows
node_views -->|"renders lists"| node_viewrender
node_rows -->|"uses state labels"| node_machine
node_rows -->|"uses pane data"| node_tmuxlib
node_rows -->|"shows usage"| node_usage
node_tmuxinit -->|"sets keys and formats"| node_tmux
node_claude -->|"sends status data"| node_usage
node_hookcmd -->|"records status data"| node_usage
node_usage -->|"supplies plan usage"| node_views
node_user -->|"requests installation"| node_installer
node_installer -->|"edits Claude settings"| node_installlib
node_user -->|"checks installation"| node_doctor
node_doctor -->|"checks configured hooks"| node_installlib
node_doctor -->|"checks tmux setup"| node_tmuxlib
node_doctor -->|"checks state directory"| node_store

click node_main "https://github.com/arisros/tmux-agent-deck/blob/main/cmd/deck/main.go"
click node_hookcmd "https://github.com/arisros/tmux-agent-deck/blob/main/cmd/deck/hookcmd.go"
click node_installer "https://github.com/arisros/tmux-agent-deck/blob/main/cmd/deck/installcmd.go"
click node_installlib "https://github.com/arisros/tmux-agent-deck/blob/main/internal/install/install.go"
click node_tmuxinit "https://github.com/arisros/tmux-agent-deck/blob/main/cmd/deck/tmuxinit.go"
click node_hooks "https://github.com/arisros/tmux-agent-deck/blob/main/internal/hook/hook.go"
click node_machine "https://github.com/arisros/tmux-agent-deck/blob/main/internal/machine/machine.go"
click node_deck "https://github.com/arisros/tmux-agent-deck/blob/main/internal/deck/deck.go"
click node_store "https://github.com/arisros/tmux-agent-deck/blob/main/internal/store/store.go"
click node_record "https://github.com/arisros/tmux-agent-deck/blob/main/internal/record/record.go"
click node_tmuxlib "https://github.com/arisros/tmux-agent-deck/blob/main/internal/tmux/tmux.go"
click node_views "https://github.com/arisros/tmux-agent-deck/blob/main/cmd/deck/viewcmd.go"
click node_rows "https://github.com/arisros/tmux-agent-deck/blob/main/internal/ui/rows.go"
click node_viewrender "https://github.com/arisros/tmux-agent-deck/blob/main/internal/ui/views.go"
click node_usage "https://github.com/arisros/tmux-agent-deck/blob/main/internal/usage/usage.go"
click node_doctor "https://github.com/arisros/tmux-agent-deck/blob/main/cmd/deck/doctor.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_main,node_hookcmd,node_installer,node_installlib,node_tmuxinit,node_user toneBlue
class node_hooks,node_machine,node_deck,node_store,node_record,node_tmuxlib toneAmber
class node_views,node_rows,node_viewrender,node_tmux toneMint
class node_usage,node_doctor toneRose
class node_claude toneIndigo
```

## Components

### Commands and setup

- [Command dispatch](https://github.com/arisros/tmux-agent-deck/blob/main/cmd/deck/main.go): `cmd/deck/main.go`
- [Hook commands](https://github.com/arisros/tmux-agent-deck/blob/main/cmd/deck/hookcmd.go): `cmd/deck/hookcmd.go`
- [Settings installer](https://github.com/arisros/tmux-agent-deck/blob/main/cmd/deck/installcmd.go): `cmd/deck/installcmd.go`
- [Settings editing](https://github.com/arisros/tmux-agent-deck/blob/main/internal/install/install.go): `internal/install/install.go`
- [tmux setup](https://github.com/arisros/tmux-agent-deck/blob/main/cmd/deck/tmuxinit.go): `cmd/deck/tmuxinit.go`

### Agent state

- [Hook mapping](https://github.com/arisros/tmux-agent-deck/blob/main/internal/hook/hook.go): `internal/hook/hook.go`
- [State machine](https://github.com/arisros/tmux-agent-deck/blob/main/internal/machine/machine.go): `internal/machine/machine.go`
- [State adapter](https://github.com/arisros/tmux-agent-deck/blob/main/internal/deck/deck.go): `internal/deck/deck.go`
- [Session records](https://github.com/arisros/tmux-agent-deck/blob/main/internal/store/store.go): `internal/store/store.go`
- [Event recorder](https://github.com/arisros/tmux-agent-deck/blob/main/internal/record/record.go): `internal/record/record.go`
- [tmux operations](https://github.com/arisros/tmux-agent-deck/blob/main/internal/tmux/tmux.go): `internal/tmux/tmux.go`

### Views and display

- [View commands](https://github.com/arisros/tmux-agent-deck/blob/main/cmd/deck/viewcmd.go): `cmd/deck/viewcmd.go`
- [Agent rows](https://github.com/arisros/tmux-agent-deck/blob/main/internal/ui/rows.go): `internal/ui/rows.go`
- [Popup and sidebar](https://github.com/arisros/tmux-agent-deck/blob/main/internal/ui/views.go): `internal/ui/views.go`

### Usage and diagnostics

- [Usage tracking](https://github.com/arisros/tmux-agent-deck/blob/main/internal/usage/usage.go): `internal/usage/usage.go`
- [Installation checks](https://github.com/arisros/tmux-agent-deck/blob/main/cmd/deck/doctor.go): `cmd/deck/doctor.go`

### Other components

- **tmux user**
- **Claude Code**
- **tmux server**

## Connections

- tmux user → Command dispatch: invokes commands (evidence: `cmd/deck/main.go`)
- Command dispatch → Hook commands: dispatches hooks (evidence: `cmd/deck/main.go`)
- Command dispatch → View commands: dispatches views (evidence: `cmd/deck/main.go`)
- Command dispatch → Settings installer: dispatches setup (evidence: `cmd/deck/main.go`)
- Command dispatch → tmux setup: dispatches setup (evidence: `cmd/deck/main.go`)
- Claude Code → Hook commands: sends hook events
- Hook commands → Hook mapping: decodes events (evidence: `cmd/deck/hookcmd.go`)
- Hook mapping → State machine: maps events (evidence: `internal/hook/hook.go`)
- Hook commands → State adapter: applies events (evidence: `cmd/deck/hookcmd.go`)
- State adapter → State machine: updates state (evidence: `internal/deck/deck.go`)
- State adapter → Session records: loads and saves (evidence: `internal/deck/deck.go`)
- State adapter → tmux operations: publishes options (evidence: `internal/deck/deck.go`)
- tmux operations → tmux server: runs commands (evidence: `README.md`)
- Claude Code → Event recorder: optional event trace
- Hook commands → Event recorder: records events (evidence: `cmd/deck/hookcmd.go`)
- tmux user → View commands: opens popup or sidebar (evidence: `README.md`)
- View commands → tmux operations: queries panes (evidence: `cmd/deck/viewcmd.go`)
- View commands → Agent rows: builds agent rows (evidence: `cmd/deck/viewcmd.go`)
- View commands → Popup and sidebar: renders lists (evidence: `cmd/deck/viewcmd.go`)
- Agent rows → State machine: uses state labels (evidence: `internal/ui/rows.go`)
- Agent rows → tmux operations: uses pane data (evidence: `internal/ui/rows.go`)
- Agent rows → Usage tracking: shows usage (evidence: `internal/ui/rows.go`)
- tmux setup → tmux server: sets keys and formats (evidence: `README.md`)
- Claude Code → Usage tracking: sends status data (evidence: `README.md`)
- Hook commands → Usage tracking: records status data (evidence: `cmd/deck/hookcmd.go`)
- Usage tracking → View commands: supplies plan usage (evidence: `README.md`)
- tmux user → Settings installer: requests installation (evidence: `README.md`)
- Settings installer → Settings editing: edits Claude settings (evidence: `cmd/deck/installcmd.go`)
- tmux user → Installation checks: checks installation
- Installation checks → Settings editing: checks configured hooks (evidence: `cmd/deck/doctor.go`)
- Installation checks → tmux operations: checks tmux setup (evidence: `cmd/deck/doctor.go`)
- Installation checks → Session records: checks state directory (evidence: `cmd/deck/doctor.go`)