# charmbracelet/vhs architecture

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

- Interactive diagram: https://gitdiagram.com/charmbracelet/vhs
- Repository: https://github.com/charmbracelet/vhs

## Overview

VHS is a Go tool for scripting terminal sessions into GIFs and other video outputs, with additional recording, publishing, and SSH-server workflows. The main workflow accepts a tape from a user or stdin, lexes and parses its commands, evaluates them against a terminal/browser session, captures frames, and renders output. The graph also includes documented CLI capabilities whose implementation details were not fully sampled; those links are marked accordingly. Evidence is limited to the provided excerpts, source index, and README.

Main entry points: [`evaluator.go`](https://github.com/charmbracelet/vhs/blob/main/evaluator.go) (Command evaluator), [`vhs.go`](https://github.com/charmbracelet/vhs/blob/main/vhs.go) (Terminal session), [`main.go`](https://github.com/charmbracelet/vhs/blob/main/main.go) (VHS CLI), [`command.go`](https://github.com/charmbracelet/vhs/blob/main/command.go) (Command handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and authoring"]
  node_cli["VHS CLI<br/>[main.go]"]
  node_recorder["Action recorder<br/>[record.go]"]
  node_syntax["Command formatting<br/>[syntax.go]"]
end

subgraph group_language["Tape language"]
  node_tape["Tape lexer<br/>[lexer.go]"]
  node_tokens["Token definitions<br/>[token.go]"]
  node_parser["Tape parser<br/>[parser.go]"]
end

subgraph group_runtime["Terminal runtime"]
  node_evaluator["Command evaluator<br/>[evaluator.go]"]
  node_dispatch["Command handlers<br/>[command.go]"]
  node_session["Terminal session<br/>[vhs.go]"]
  node_shell["PTY shell<br/>[shell.go]"]
  node_terminal["Virtual terminal"]
  node_themes["Theme catalog<br/>[themes.go]"]
end

subgraph group_media["Capture and output"]
  node_framecapture["Frame capture<br/>[vhs.go]"]
  node_decoration["Frame decoration<br/>[draw.go]"]
  node_renderer["Video renderer<br/>[ffmpeg.go]"]
  node_video["Rendered video"]
end

subgraph group_services["Sharing and access"]
  node_publisher["Tape publisher<br/>[publish.go]"]
  node_sshserver["SSH server<br/>[serve.go]"]
end

node_author(("Tape author"))
node_sshuser(("SSH user"))

node_author -->|"runs tape"| node_cli
node_cli -->|"evaluates tape"| node_evaluator
node_evaluator -->|"lexes input"| node_tape
node_evaluator -->|"parses tokens"| node_parser
node_tape -->|"emits tokens"| node_tokens
node_parser -->|"uses token types"| node_tokens
node_parser -->|"reads tokens"| node_tape
node_evaluator -->|"executes commands"| node_dispatch
node_evaluator -->|"starts and configures"| node_session
node_dispatch -->|"updates session"| node_session
node_session -->|"starts shell"| node_shell
node_session -->|"connects browser terminal"| node_terminal
node_dispatch -->|"sends key input"| node_terminal
node_session -->|"records frames"| node_framecapture
node_framecapture -.->|"adds window styling"| node_decoration
node_session -->|"renders recording"| node_renderer
node_renderer -.->|"writes video output"| node_video
node_cli -->|"starts recording"| node_recorder
node_recorder -->|"writes tape text"| node_author
node_cli -->|"publishes output"| node_publisher
node_cli -->|"starts server"| node_sshserver
node_sshuser -->|"submits tape"| node_sshserver
node_sshserver -.->|"returns rendered output"| node_video
node_evaluator -->|"formats commands"| node_syntax
node_dispatch -.->|"applies theme"| node_themes

click node_cli "https://github.com/charmbracelet/vhs/blob/main/main.go"
click node_recorder "https://github.com/charmbracelet/vhs/blob/main/record.go"
click node_publisher "https://github.com/charmbracelet/vhs/blob/main/publish.go"
click node_sshserver "https://github.com/charmbracelet/vhs/blob/main/serve.go"
click node_tape "https://github.com/charmbracelet/vhs/blob/main/lexer/lexer.go"
click node_tokens "https://github.com/charmbracelet/vhs/blob/main/token/token.go"
click node_parser "https://github.com/charmbracelet/vhs/blob/main/parser/parser.go"
click node_evaluator "https://github.com/charmbracelet/vhs/blob/main/evaluator.go"
click node_dispatch "https://github.com/charmbracelet/vhs/blob/main/command.go"
click node_session "https://github.com/charmbracelet/vhs/blob/main/vhs.go"
click node_shell "https://github.com/charmbracelet/vhs/blob/main/shell.go"
click node_framecapture "https://github.com/charmbracelet/vhs/blob/main/vhs.go"
click node_decoration "https://github.com/charmbracelet/vhs/blob/main/draw.go"
click node_renderer "https://github.com/charmbracelet/vhs/blob/main/ffmpeg.go"
click node_syntax "https://github.com/charmbracelet/vhs/blob/main/syntax.go"
click node_themes "https://github.com/charmbracelet/vhs/blob/main/themes.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_cli,node_recorder,node_syntax,node_sshuser toneBlue
class node_tape,node_tokens,node_parser toneAmber
class node_evaluator,node_dispatch,node_session,node_shell,node_terminal,node_themes toneMint
class node_framecapture,node_decoration,node_renderer,node_video toneRose
class node_publisher,node_sshserver,node_author toneIndigo
```

## Components

### CLI and authoring

- [VHS CLI](https://github.com/charmbracelet/vhs/blob/main/main.go): `main.go`
- [Action recorder](https://github.com/charmbracelet/vhs/blob/main/record.go): `record.go`
- [Command formatting](https://github.com/charmbracelet/vhs/blob/main/syntax.go): `syntax.go`

### Tape language

- [Tape lexer](https://github.com/charmbracelet/vhs/blob/main/lexer/lexer.go): `lexer/lexer.go`
- [Token definitions](https://github.com/charmbracelet/vhs/blob/main/token/token.go): `token/token.go`
- [Tape parser](https://github.com/charmbracelet/vhs/blob/main/parser/parser.go): `parser/parser.go`

### Terminal runtime

- [Command evaluator](https://github.com/charmbracelet/vhs/blob/main/evaluator.go): `evaluator.go`
- [Command handlers](https://github.com/charmbracelet/vhs/blob/main/command.go): `command.go`
- [Terminal session](https://github.com/charmbracelet/vhs/blob/main/vhs.go): `vhs.go`
- [PTY shell](https://github.com/charmbracelet/vhs/blob/main/shell.go): `shell.go`
- **Virtual terminal**
- [Theme catalog](https://github.com/charmbracelet/vhs/blob/main/themes.go): `themes.go`

### Capture and output

- [Frame capture](https://github.com/charmbracelet/vhs/blob/main/vhs.go): `vhs.go`
- [Frame decoration](https://github.com/charmbracelet/vhs/blob/main/draw.go): `draw.go`
- [Video renderer](https://github.com/charmbracelet/vhs/blob/main/ffmpeg.go): `ffmpeg.go`
- **Rendered video**

### Sharing and access

- [Tape publisher](https://github.com/charmbracelet/vhs/blob/main/publish.go): `publish.go`
- [SSH server](https://github.com/charmbracelet/vhs/blob/main/serve.go): `serve.go`

### Other components

- **Tape author**
- **SSH user**

## Connections

- Tape author → VHS CLI: runs tape (evidence: `README.md`)
- VHS CLI → Command evaluator: evaluates tape (evidence: `main.go`)
- Command evaluator → Tape lexer: lexes input (evidence: `evaluator.go`)
- Command evaluator → Tape parser: parses tokens (evidence: `evaluator.go`)
- Tape lexer → Token definitions: emits tokens (evidence: `lexer/lexer.go`)
- Tape parser → Token definitions: uses token types (evidence: `parser/parser.go`)
- Tape parser → Tape lexer: reads tokens (evidence: `parser/parser.go`)
- Command evaluator → Command handlers: executes commands (evidence: `evaluator.go`)
- Command evaluator → Terminal session: starts and configures (evidence: `evaluator.go`)
- Command handlers → Terminal session: updates session (evidence: `command.go`)
- Terminal session → PTY shell: starts shell (evidence: `vhs.go`)
- Terminal session → Virtual terminal: connects browser terminal (evidence: `vhs.go`)
- Command handlers → Virtual terminal: sends key input (evidence: `command.go`)
- Terminal session → Frame capture: records frames (evidence: `vhs.go`)
- Frame capture → Frame decoration: adds window styling
- Terminal session → Video renderer: renders recording
- Video renderer → Rendered video: writes video output
- VHS CLI → Action recorder: starts recording (evidence: `main.go`)
- Action recorder → Tape author: writes tape text (evidence: `README.md`)
- VHS CLI → Tape publisher: publishes output (evidence: `README.md`)
- VHS CLI → SSH server: starts server (evidence: `README.md`)
- SSH user → SSH server: submits tape (evidence: `README.md`)
- SSH server → Rendered video: returns rendered output
- Command evaluator → Command formatting: formats commands (evidence: `evaluator.go`)
- Command handlers → Theme catalog: applies theme
