# zellij-org/zellij architecture

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

- Interactive diagram: https://gitdiagram.com/zellij-org/zellij
- Repository: https://github.com/zellij-org/zellij

## Overview

Zellij is a terminal workspace and multiplexer. A user starts or joins a session, interacts through a local terminal or built-in web client, and uses server-managed tabs and panes to run terminal programs and plugins. The map preserves documented layouts, collaboration, floating/stacked panes, and plugin capabilities. Source-index references support several internal links; broader product relationships are cited to the README. Many subsystems are unsampled, so their internal wiring is not asserted.

Main entry points: [`zellij-server/src/screen.rs`](https://github.com/zellij-org/zellij/blob/main/zellij-server/src/screen.rs) (Session server), [`zellij-client/src/lib.rs`](https://github.com/zellij-org/zellij/blob/main/zellij-client/src/lib.rs) (Terminal client), [`default-plugins/bars/src/main.rs`](https://github.com/zellij-org/zellij/blob/main/default-plugins/bars/src/main.rs) (Workspace bars), [`zellij-client/src/web_client/connection_manager.rs`](https://github.com/zellij-org/zellij/blob/main/zellij-client/src/web_client/connection_manager.rs) (Web client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and clients"]
  node_cli["CLI startup<br/>[lib.rs]"]
  node_client["Terminal client<br/>[lib.rs]"]
  node_osio["OS I/O<br/>[os_input_output.rs]"]
  node_webclient["Web client"]
end

subgraph group_session["Session runtime"]
  node_server["Session server<br/>[screen.rs]"]
  node_pty["PTY processes<br/>[pty.rs]"]
  node_panes["Pane management<br/>[mod.rs]"]
  node_tabmouse["Tab interactions<br/>[mouse_handler.rs]"]
  node_layout["Layout parsing"]
end

subgraph group_terminal["Terminal capabilities"]
  node_terminalapp["Terminal emulation<br/>[client_loop.rs]"]
  node_attention["Attention policy<br/>[engine.rs]"]
end

subgraph group_plugins["Built-in plugins"]
  node_bars["Workspace bars<br/>[main.rs]"]
  node_baractions["Bar actions<br/>[click_actions.rs]"]
  node_bardrag["Tab dragging<br/>[tab_drag.rs]"]
  node_configuration["Configuration UI<br/>[main.rs]"]
  node_configeditor["Settings editor<br/>[list_editor.rs]"]
  node_about["About and onboarding<br/>[main.rs]"]
  node_aboutpages["About pages<br/>[pages.rs]"]
  node_aboutcomponents["Interactive components"]
  node_sessions["Session manager<br/>[main.rs]"]
  node_prompt["Prompt plugin<br/>[app.rs]"]
  node_share["Sharing plugin<br/>[main.rs]"]
  node_strider["File browser<br/>[main.rs]"]
end

subgraph group_shared["Shared contracts"]
  node_webprotocol["Web messages<br/>[control_message.rs]"]
  node_contracts["Client-server protocol"]
  node_pluginapi["Plugin API<br/>[lib.rs]"]
end

node_user(("User"))

node_user -->|"starts or joins"| node_cli
node_cli -.->|"launches"| node_client
node_client -->|"uses"| node_osio
node_client -.->|"connects to"| node_server
node_webclient -.->|"collaborates with"| node_server
node_webclient -->|"uses messages"| node_webprotocol
node_client -.->|"exchanges protocol"| node_contracts
node_server -.->|"exchanges protocol"| node_contracts
node_server -.->|"manages"| node_panes
node_server -.->|"manages processes"| node_pty
node_server -.->|"applies layouts"| node_layout
node_server -.->|"serves terminal sessions"| node_terminalapp
node_panes -->|"handles interactions"| node_tabmouse
node_terminalapp -.->|"evaluates attention"| node_attention
node_server -.->|"hosts plugin UI"| node_bars
node_bars -->|"dispatches actions"| node_baractions
node_bars -->|"delegates dragging"| node_bardrag
node_server -.->|"hosts plugin UI"| node_configuration
node_configuration -->|"uses editor"| node_configeditor
node_server -.->|"hosts plugin UI"| node_about
node_about -->|"renders pages"| node_aboutpages
node_aboutpages -->|"uses components"| node_aboutcomponents
node_server -.->|"hosts plugin UI"| node_sessions
node_server -.->|"hosts plugin UI"| node_prompt
node_server -.->|"hosts plugin UI"| node_share
node_server -.->|"hosts plugin UI"| node_strider
node_pluginapi -.->|"supports plugins"| node_bars
node_pluginapi -.->|"supports plugins"| node_sessions

click node_cli "https://github.com/zellij-org/zellij/blob/main/src/lib.rs"
click node_client "https://github.com/zellij-org/zellij/blob/main/zellij-client/src/lib.rs"
click node_osio "https://github.com/zellij-org/zellij/blob/main/zellij-client/src/os_input_output.rs"
click node_webclient "https://github.com/zellij-org/zellij/blob/main/zellij-client/src/web_client/connection_manager.rs"
click node_server "https://github.com/zellij-org/zellij/blob/main/zellij-server/src/screen.rs"
click node_pty "https://github.com/zellij-org/zellij/blob/main/zellij-server/src/pty.rs"
click node_panes "https://github.com/zellij-org/zellij/blob/main/zellij-server/src/panes/mod.rs"
click node_tabmouse "https://github.com/zellij-org/zellij/blob/main/zellij-server/src/tab/mouse_handler.rs"
click node_layout "https://github.com/zellij-org/zellij/blob/main/zellij-utils/src/kdl/kdl_layout_parser.rs"
click node_terminalapp "https://github.com/zellij-org/zellij/blob/main/zellij-terminal/src/session/client_loop.rs"
click node_attention "https://github.com/zellij-org/zellij/blob/main/zellij-terminal/src/app/policy/engine.rs"
click node_webprotocol "https://github.com/zellij-org/zellij/blob/main/zellij-client/src/web_client/control_message.rs"
click node_contracts "https://github.com/zellij-org/zellij/blob/main/zellij-utils/src/client_server_contract/client_to_server.proto"
click node_bars "https://github.com/zellij-org/zellij/blob/main/default-plugins/bars/src/main.rs"
click node_baractions "https://github.com/zellij-org/zellij/blob/main/default-plugins/bars/src/click_actions.rs"
click node_bardrag "https://github.com/zellij-org/zellij/blob/main/default-plugins/bars/src/tab_drag.rs"
click node_configuration "https://github.com/zellij-org/zellij/blob/main/default-plugins/configuration/src/main.rs"
click node_configeditor "https://github.com/zellij-org/zellij/blob/main/default-plugins/configuration/src/list_editor.rs"
click node_about "https://github.com/zellij-org/zellij/blob/main/default-plugins/about/src/main.rs"
click node_aboutpages "https://github.com/zellij-org/zellij/blob/main/default-plugins/about/src/pages.rs"
click node_aboutcomponents "https://github.com/zellij-org/zellij/blob/main/default-plugins/about/src/active_component.rs"
click node_sessions "https://github.com/zellij-org/zellij/blob/main/default-plugins/session-manager/src/main.rs"
click node_prompt "https://github.com/zellij-org/zellij/blob/main/default-plugins/prompt/src/app.rs"
click node_share "https://github.com/zellij-org/zellij/blob/main/default-plugins/share/src/main.rs"
click node_strider "https://github.com/zellij-org/zellij/blob/main/default-plugins/strider/src/main.rs"
click node_pluginapi "https://github.com/zellij-org/zellij/blob/main/zellij-tile/src/lib.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_client,node_osio,node_webclient,node_user toneBlue
class node_server,node_pty,node_panes,node_tabmouse,node_layout toneAmber
class node_terminalapp,node_attention toneMint
class node_bars,node_baractions,node_bardrag,node_configuration,node_configeditor,node_about,node_aboutpages,node_aboutcomponents,node_sessions,node_prompt,node_share,node_strider toneRose
class node_webprotocol,node_contracts,node_pluginapi toneIndigo
```

## Components

### Entry and clients

- [CLI startup](https://github.com/zellij-org/zellij/blob/main/src/lib.rs): `src/lib.rs`
- [Terminal client](https://github.com/zellij-org/zellij/blob/main/zellij-client/src/lib.rs): `zellij-client/src/lib.rs`
- [OS I/O](https://github.com/zellij-org/zellij/blob/main/zellij-client/src/os_input_output.rs): `zellij-client/src/os_input_output.rs`
- [Web client](https://github.com/zellij-org/zellij/blob/main/zellij-client/src/web_client/connection_manager.rs): `zellij-client/src/web_client/connection_manager.rs`

### Session runtime

- [Session server](https://github.com/zellij-org/zellij/blob/main/zellij-server/src/screen.rs): `zellij-server/src/screen.rs`
- [PTY processes](https://github.com/zellij-org/zellij/blob/main/zellij-server/src/pty.rs): `zellij-server/src/pty.rs`
- [Pane management](https://github.com/zellij-org/zellij/blob/main/zellij-server/src/panes/mod.rs): `zellij-server/src/panes/mod.rs`
- [Tab interactions](https://github.com/zellij-org/zellij/blob/main/zellij-server/src/tab/mouse_handler.rs): `zellij-server/src/tab/mouse_handler.rs`
- [Layout parsing](https://github.com/zellij-org/zellij/blob/main/zellij-utils/src/kdl/kdl_layout_parser.rs): `zellij-utils/src/kdl/kdl_layout_parser.rs`

### Terminal capabilities

- [Terminal emulation](https://github.com/zellij-org/zellij/blob/main/zellij-terminal/src/session/client_loop.rs): `zellij-terminal/src/session/client_loop.rs`
- [Attention policy](https://github.com/zellij-org/zellij/blob/main/zellij-terminal/src/app/policy/engine.rs): `zellij-terminal/src/app/policy/engine.rs`

### Built-in plugins

- [Workspace bars](https://github.com/zellij-org/zellij/blob/main/default-plugins/bars/src/main.rs): `default-plugins/bars/src/main.rs`
- [Bar actions](https://github.com/zellij-org/zellij/blob/main/default-plugins/bars/src/click_actions.rs): `default-plugins/bars/src/click_actions.rs`
- [Tab dragging](https://github.com/zellij-org/zellij/blob/main/default-plugins/bars/src/tab_drag.rs): `default-plugins/bars/src/tab_drag.rs`
- [Configuration UI](https://github.com/zellij-org/zellij/blob/main/default-plugins/configuration/src/main.rs): `default-plugins/configuration/src/main.rs`
- [Settings editor](https://github.com/zellij-org/zellij/blob/main/default-plugins/configuration/src/list_editor.rs): `default-plugins/configuration/src/list_editor.rs`
- [About and onboarding](https://github.com/zellij-org/zellij/blob/main/default-plugins/about/src/main.rs): `default-plugins/about/src/main.rs`
- [About pages](https://github.com/zellij-org/zellij/blob/main/default-plugins/about/src/pages.rs): `default-plugins/about/src/pages.rs`
- [Interactive components](https://github.com/zellij-org/zellij/blob/main/default-plugins/about/src/active_component.rs): `default-plugins/about/src/active_component.rs`
- [Session manager](https://github.com/zellij-org/zellij/blob/main/default-plugins/session-manager/src/main.rs): `default-plugins/session-manager/src/main.rs`
- [Prompt plugin](https://github.com/zellij-org/zellij/blob/main/default-plugins/prompt/src/app.rs): `default-plugins/prompt/src/app.rs`
- [Sharing plugin](https://github.com/zellij-org/zellij/blob/main/default-plugins/share/src/main.rs): `default-plugins/share/src/main.rs`
- [File browser](https://github.com/zellij-org/zellij/blob/main/default-plugins/strider/src/main.rs): `default-plugins/strider/src/main.rs`

### Shared contracts

- [Web messages](https://github.com/zellij-org/zellij/blob/main/zellij-client/src/web_client/control_message.rs): `zellij-client/src/web_client/control_message.rs`
- [Client-server protocol](https://github.com/zellij-org/zellij/blob/main/zellij-utils/src/client_server_contract/client_to_server.proto): `zellij-utils/src/client_server_contract/client_to_server.proto`
- [Plugin API](https://github.com/zellij-org/zellij/blob/main/zellij-tile/src/lib.rs): `zellij-tile/src/lib.rs`

### Other components

- **User**

## Connections

- User → CLI startup: starts or joins (evidence: `README.md`)
- CLI startup → Terminal client: launches
- Terminal client → OS I/O: uses (evidence: `zellij-client/src/lib.rs`)
- Terminal client → Session server: connects to
- Web client → Session server: collaborates with (evidence: `README.md`)
- Web client → Web messages: uses messages (evidence: `zellij-client/src/web_client/connection_manager.rs`)
- Terminal client → Client-server protocol: exchanges protocol
- Session server → Client-server protocol: exchanges protocol
- Session server → Pane management: manages (evidence: `zellij-server/src/tab/mouse_handler.rs`)
- Session server → PTY processes: manages processes
- Session server → Layout parsing: applies layouts (evidence: `README.md`)
- Session server → Terminal emulation: serves terminal sessions (evidence: `README.md`)
- Pane management → Tab interactions: handles interactions (evidence: `zellij-server/src/tab/mouse_handler.rs`)
- Terminal emulation → Attention policy: evaluates attention
- Session server → Workspace bars: hosts plugin UI (evidence: `README.md`)
- Workspace bars → Bar actions: dispatches actions (evidence: `default-plugins/bars/src/main.rs`)
- Workspace bars → Tab dragging: delegates dragging (evidence: `default-plugins/bars/src/main.rs`)
- Session server → Configuration UI: hosts plugin UI (evidence: `README.md`)
- Configuration UI → Settings editor: uses editor (evidence: `default-plugins/configuration/src/main.rs`)
- Session server → About and onboarding: hosts plugin UI (evidence: `README.md`)
- About and onboarding → About pages: renders pages (evidence: `default-plugins/about/src/main.rs`)
- About pages → Interactive components: uses components (evidence: `default-plugins/about/src/pages.rs`)
- Session server → Session manager: hosts plugin UI (evidence: `README.md`)
- Session server → Prompt plugin: hosts plugin UI (evidence: `README.md`)
- Session server → Sharing plugin: hosts plugin UI (evidence: `README.md`)
- Session server → File browser: hosts plugin UI (evidence: `README.md`)
- Plugin API → Workspace bars: supports plugins (evidence: `README.md`)
- Plugin API → Session manager: supports plugins (evidence: `README.md`)
