# b-3llum/lterm architecture

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

- Interactive diagram: https://gitdiagram.com/b-3llum/lterm
- Repository: https://github.com/b-3llum/lterm

## Overview

lterm is a cross-platform terminal for interactive panes, persistent local/SSH/WSL sessions, coding-agent visibility and control, and browser automation; it also includes a Markdown-with-images reader. The main interactive path runs from CLI dispatch through the window, pane layout and PTYs, then terminal-state updates and rendering. Separate branches cover persistent sessions, pane-control requests, agent integrations, and browser panes. The graph includes documented capabilities whose implementation was not sampled; their internal links are omitted where source evidence is limited.

Main entry points: [`src/app.rs`](https://github.com/b-3llum/lterm/blob/main/src/app.rs) (Window and panes), [`src/main.rs`](https://github.com/b-3llum/lterm/blob/main/src/main.rs) (CLI dispatch), [`mdterm/src/render.rs`](https://github.com/b-3llum/lterm/blob/main/mdterm/src/render.rs) (Markdown rendering), [`src/control.rs`](https://github.com/b-3llum/lterm/blob/main/src/control.rs) (Pane control API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Terminal runtime"]
  node_cli["CLI dispatch<br/>[main.rs]"]
  node_window["Window and panes<br/>[app.rs]"]
  node_layout["Pane layout<br/>[layout.rs]"]
  node_pty["PTY processes<br/>[pty.rs]"]
  node_term["Terminal state<br/>[term.rs]"]
  node_renderer["Terminal renderer<br/>[render.rs]"]
  node_graphics["Terminal graphics<br/>[graphics.rs]"]
  node_input["Input handling<br/>[input.rs]"]
  node_keymap["Keyboard shortcuts<br/>[keymap.rs]"]
  node_copy["Copy mode<br/>[copymode.rs]"]
  node_install["Installer<br/>[install.rs]"]
end

subgraph group_sessions["Persistent sessions"]
  node_session["Session server and proxy<br/>[session.rs]"]
  node_push["Remote install<br/>[push.rs]"]
end

subgraph group_agents["Agent tools"]
  node_control["Pane control API<br/>[control.rs]"]
  node_agents_state["Agent state tracking<br/>[agents.rs]"]
  node_integration["Agent integrations<br/>[integration.rs]"]
end

subgraph group_browser["Browser automation"]
  node_browser["Browser pane commands<br/>[browse.rs]"]
  node_cdp["Chrome DevTools client<br/>[cdp.rs]"]
end

subgraph group_reader["Markdown reader"]
  node_mdterm["Markdown reader<br/>[lib.rs]"]
  node_mdrender["Markdown rendering<br/>[render.rs]"]
  node_mdgraphics["Markdown images<br/>[graphics.rs]"]
  node_mdstyle["Markdown styling<br/>[style.rs]"]
  node_mdwrap["Text wrapping<br/>[wrap.rs]"]
end

node_user(("User or script"))
node_browser_engine["Chrome or Edge"]

node_user -->|"runs commands"| node_cli
node_cli -->|"opens terminal"| node_window
node_cli -->|"dispatches md"| node_mdterm
node_window -->|"lays out panes"| node_layout
node_window -.->|"starts processes"| node_pty
node_window -->|"creates terminal state"| node_term
node_window -->|"draws panes"| node_renderer
node_term -->|"decodes images"| node_graphics
node_user -.->|"presses keys"| node_input
node_input -.->|"routes input"| node_window
node_window -.->|"uses shortcuts"| node_keymap
node_window -.->|"uses copy mode"| node_copy
node_cli -->|"dispatches session commands"| node_session
node_window -->|"connects to session"| node_session
node_cli -->|"dispatches push"| node_push
node_push -->|"targets remote session"| node_session
node_user -->|"drives panes"| node_control
node_cli -->|"dispatches pane commands"| node_control
node_control -->|"controls panes"| node_window
node_control -.->|"controls session panes"| node_session
node_window -->|"shows agent status"| node_agents_state
node_cli -->|"dispatches integration"| node_integration
node_integration -.->|"reports agent state"| node_agents_state
node_cli -->|"dispatches browse"| node_browser
node_browser -->|"uses DevTools client"| node_cdp
node_cdp -.->|"controls browser"| node_browser_engine
node_browser -->|"opens browser pane"| node_window
node_mdterm -->|"renders documents"| node_mdrender
node_mdrender -->|"renders images"| node_mdgraphics
node_mdrender -->|"applies styles"| node_mdstyle
node_mdrender -->|"wraps text"| node_mdwrap
node_cli -->|"dispatches install"| node_install

click node_cli "https://github.com/b-3llum/lterm/blob/main/src/main.rs"
click node_window "https://github.com/b-3llum/lterm/blob/main/src/app.rs"
click node_layout "https://github.com/b-3llum/lterm/blob/main/src/layout.rs"
click node_pty "https://github.com/b-3llum/lterm/blob/main/src/pty.rs"
click node_term "https://github.com/b-3llum/lterm/blob/main/src/term.rs"
click node_renderer "https://github.com/b-3llum/lterm/blob/main/src/render.rs"
click node_graphics "https://github.com/b-3llum/lterm/blob/main/src/graphics.rs"
click node_input "https://github.com/b-3llum/lterm/blob/main/src/input.rs"
click node_keymap "https://github.com/b-3llum/lterm/blob/main/src/keymap.rs"
click node_copy "https://github.com/b-3llum/lterm/blob/main/src/copymode.rs"
click node_session "https://github.com/b-3llum/lterm/blob/main/src/session.rs"
click node_push "https://github.com/b-3llum/lterm/blob/main/src/push.rs"
click node_control "https://github.com/b-3llum/lterm/blob/main/src/control.rs"
click node_agents_state "https://github.com/b-3llum/lterm/blob/main/src/agents.rs"
click node_integration "https://github.com/b-3llum/lterm/blob/main/src/integration.rs"
click node_browser "https://github.com/b-3llum/lterm/blob/main/src/browse.rs"
click node_cdp "https://github.com/b-3llum/lterm/blob/main/src/cdp.rs"
click node_install "https://github.com/b-3llum/lterm/blob/main/src/install.rs"
click node_mdterm "https://github.com/b-3llum/lterm/blob/main/mdterm/src/lib.rs"
click node_mdrender "https://github.com/b-3llum/lterm/blob/main/mdterm/src/render.rs"
click node_mdgraphics "https://github.com/b-3llum/lterm/blob/main/mdterm/src/graphics.rs"
click node_mdstyle "https://github.com/b-3llum/lterm/blob/main/mdterm/src/style.rs"
click node_mdwrap "https://github.com/b-3llum/lterm/blob/main/mdterm/src/wrap.rs"

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_window,node_layout,node_pty,node_term,node_renderer,node_graphics,node_input,node_keymap,node_copy,node_install,node_user toneBlue
class node_session,node_push toneAmber
class node_control,node_agents_state,node_integration toneMint
class node_browser,node_cdp toneRose
class node_mdterm,node_mdrender,node_mdgraphics,node_mdstyle,node_mdwrap,node_browser_engine toneIndigo
```

## Components

### Terminal runtime

- [CLI dispatch](https://github.com/b-3llum/lterm/blob/main/src/main.rs): `src/main.rs`
- [Window and panes](https://github.com/b-3llum/lterm/blob/main/src/app.rs): `src/app.rs`
- [Pane layout](https://github.com/b-3llum/lterm/blob/main/src/layout.rs): `src/layout.rs`
- [PTY processes](https://github.com/b-3llum/lterm/blob/main/src/pty.rs): `src/pty.rs`
- [Terminal state](https://github.com/b-3llum/lterm/blob/main/src/term.rs): `src/term.rs`
- [Terminal renderer](https://github.com/b-3llum/lterm/blob/main/src/render.rs): `src/render.rs`
- [Terminal graphics](https://github.com/b-3llum/lterm/blob/main/src/graphics.rs): `src/graphics.rs`
- [Input handling](https://github.com/b-3llum/lterm/blob/main/src/input.rs): `src/input.rs`
- [Keyboard shortcuts](https://github.com/b-3llum/lterm/blob/main/src/keymap.rs): `src/keymap.rs`
- [Copy mode](https://github.com/b-3llum/lterm/blob/main/src/copymode.rs): `src/copymode.rs`
- [Installer](https://github.com/b-3llum/lterm/blob/main/src/install.rs): `src/install.rs`

### Persistent sessions

- [Session server and proxy](https://github.com/b-3llum/lterm/blob/main/src/session.rs): `src/session.rs`
- [Remote install](https://github.com/b-3llum/lterm/blob/main/src/push.rs): `src/push.rs`

### Agent tools

- [Pane control API](https://github.com/b-3llum/lterm/blob/main/src/control.rs): `src/control.rs`
- [Agent state tracking](https://github.com/b-3llum/lterm/blob/main/src/agents.rs): `src/agents.rs`
- [Agent integrations](https://github.com/b-3llum/lterm/blob/main/src/integration.rs): `src/integration.rs`

### Browser automation

- [Browser pane commands](https://github.com/b-3llum/lterm/blob/main/src/browse.rs): `src/browse.rs`
- [Chrome DevTools client](https://github.com/b-3llum/lterm/blob/main/src/cdp.rs): `src/cdp.rs`

### Markdown reader

- [Markdown reader](https://github.com/b-3llum/lterm/blob/main/mdterm/src/lib.rs): `mdterm/src/lib.rs`
- [Markdown rendering](https://github.com/b-3llum/lterm/blob/main/mdterm/src/render.rs): `mdterm/src/render.rs`
- [Markdown images](https://github.com/b-3llum/lterm/blob/main/mdterm/src/graphics.rs): `mdterm/src/graphics.rs`
- [Markdown styling](https://github.com/b-3llum/lterm/blob/main/mdterm/src/style.rs): `mdterm/src/style.rs`
- [Text wrapping](https://github.com/b-3llum/lterm/blob/main/mdterm/src/wrap.rs): `mdterm/src/wrap.rs`

### Other components

- **User or script**
- **Chrome or Edge**

## Connections

- User or script → CLI dispatch: runs commands (evidence: `README.md`)
- CLI dispatch → Window and panes: opens terminal (evidence: `README.md`)
- CLI dispatch → Markdown reader: dispatches md (evidence: `src/main.rs`)
- Window and panes → Pane layout: lays out panes (evidence: `src/app.rs`)
- Window and panes → PTY processes: starts processes (evidence: `src/app.rs`)
- Window and panes → Terminal state: creates terminal state (evidence: `src/app.rs`)
- Window and panes → Terminal renderer: draws panes (evidence: `src/app.rs`)
- Terminal state → Terminal graphics: decodes images (evidence: `src/term.rs`)
- User or script → Input handling: presses keys
- Input handling → Window and panes: routes input (evidence: `src/app.rs`)
- Window and panes → Keyboard shortcuts: uses shortcuts (evidence: `src/app.rs`)
- Window and panes → Copy mode: uses copy mode (evidence: `src/app.rs`)
- CLI dispatch → Session server and proxy: dispatches session commands (evidence: `src/main.rs`)
- Window and panes → Session server and proxy: connects to session (evidence: `README.md`)
- CLI dispatch → Remote install: dispatches push (evidence: `README.md`)
- Remote install → Session server and proxy: targets remote session (evidence: `src/push.rs`)
- User or script → Pane control API: drives panes (evidence: `README.md`)
- CLI dispatch → Pane control API: dispatches pane commands (evidence: `README.md`)
- Pane control API → Window and panes: controls panes (evidence: `src/control.rs`)
- Pane control API → Session server and proxy: controls session panes (evidence: `src/session.rs`)
- Window and panes → Agent state tracking: shows agent status (evidence: `src/app.rs`)
- CLI dispatch → Agent integrations: dispatches integration (evidence: `README.md`)
- Agent integrations → Agent state tracking: reports agent state
- CLI dispatch → Browser pane commands: dispatches browse (evidence: `src/main.rs`)
- Browser pane commands → Chrome DevTools client: uses DevTools client (evidence: `src/browse.rs`)
- Chrome DevTools client → Chrome or Edge: controls browser
- Browser pane commands → Window and panes: opens browser pane (evidence: `README.md`)
- Markdown reader → Markdown rendering: renders documents (evidence: `mdterm/src/lib.rs`)
- Markdown rendering → Markdown images: renders images (evidence: `mdterm/src/render.rs`)
- Markdown rendering → Markdown styling: applies styles (evidence: `mdterm/src/render.rs`)
- Markdown rendering → Text wrapping: wraps text (evidence: `mdterm/src/render.rs`)
- CLI dispatch → Installer: dispatches install (evidence: `README.md`)
