# helix-editor/helix architecture

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

- Interactive diagram: https://gitdiagram.com/helix-editor/helix
- Repository: https://github.com/helix-editor/helix

## Overview

Helix is a terminal modal editor. The principal workflow is: a user launches `hx`, configuration and language resources load, the application runs an event loop, editor state is updated through modal actions and text transformations, and the compositor renders results to the terminal. Major branches include tree-sitter syntax support, LSP assistance, debugging through DAP, VCS integration, completion/pickers, and persistent document writes. Some subsystem links are inferred from documented capabilities and tree structure because their callers were not sampled.

Main entry points: [`helix-term/src/application.rs`](https://github.com/helix-editor/helix/blob/master/helix-term/src/application.rs) (Application Loop), [`helix-term/src/main.rs`](https://github.com/helix-editor/helix/blob/master/helix-term/src/main.rs) (CLI Entry), [`helix-view/src/editor.rs`](https://github.com/helix-editor/helix/blob/master/helix-view/src/editor.rs) (Editor State), [`helix-view/src/document.rs`](https://github.com/helix-editor/helix/blob/master/helix-view/src/document.rs) (Document Model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry_ui["Entry and UI"]
  node_cli["CLI Entry<br/>[main.rs]"]
  node_application["Application Loop<br/>[application.rs]"]
  node_event_runtime["Event Runtime<br/>[runtime.rs]"]
  node_compositor["UI Compositor<br/>[compositor.rs]"]
  node_terminal_ui["Terminal Renderer<br/>[terminal.rs]"]
end

subgraph group_editing["Editing Engine"]
  node_editor["Editor State<br/>[editor.rs]"]
  node_document["Document Model<br/>[document.rs]"]
  node_editing_core["Editing Primitives<br/>[lib.rs]"]
  node_syntax["Syntax Engine<br/>[syntax.rs]"]
end

subgraph group_workspace["Workspace Services"]
  node_config["Editor Config<br/>[config.rs]"]
  node_loader["Workspace Loader<br/>[lib.rs]"]
end

subgraph group_language_tools["Language Tools"]
  node_lsp_handlers["LSP Handlers"]
  node_lsp_client["LSP Client<br/>[client.rs]"]
  node_lsp_protocol["LSP Protocol<br/>[lib.rs]"]
  node_dap_commands["DAP Commands<br/>[dap.rs]"]
  node_dap_client["DAP Client<br/>[client.rs]"]
end

subgraph group_project_tools["Project Tools"]
  node_vcs["VCS Integration<br/>[lib.rs]"]
  node_completion["Completion UI<br/>[completion.rs]"]
  node_picker["Picker Queries<br/>[query.rs]"]
end

node_user(("Editor User"))

node_user -->|"launches hx"| node_cli
node_cli -->|"loads config"| node_config
node_cli -->|"loads resources"| node_loader
node_cli -->|"starts editor"| node_application
node_application -->|"creates editor"| node_editor
node_application -->|"pushes view"| node_compositor
node_application -->|"awaits events"| node_event_runtime
node_event_runtime -->|"dispatches events"| node_application
node_application -->|"renders output"| node_terminal_ui
node_editor -->|"updates documents"| node_document
node_document -->|"applies edits"| node_editing_core
node_document -->|"provides text"| node_syntax
node_application -->|"handles LSP events"| node_lsp_handlers
node_lsp_handlers -->|"requests language features"| node_lsp_client
node_lsp_client -->|"exchanges messages"| node_lsp_protocol
node_application -.->|"dispatches debug commands"| node_dap_commands
node_dap_commands -->|"controls debugger"| node_dap_client
node_editor -.->|"reads project status"| node_vcs
node_lsp_handlers -->|"updates completions"| node_completion
node_completion -->|"filters candidates"| node_picker

click node_cli "https://github.com/helix-editor/helix/blob/master/helix-term/src/main.rs"
click node_application "https://github.com/helix-editor/helix/blob/master/helix-term/src/application.rs"
click node_event_runtime "https://github.com/helix-editor/helix/blob/master/helix-event/src/runtime.rs"
click node_compositor "https://github.com/helix-editor/helix/blob/master/helix-term/src/compositor.rs"
click node_terminal_ui "https://github.com/helix-editor/helix/blob/master/helix-tui/src/terminal.rs"
click node_editor "https://github.com/helix-editor/helix/blob/master/helix-view/src/editor.rs"
click node_document "https://github.com/helix-editor/helix/blob/master/helix-view/src/document.rs"
click node_editing_core "https://github.com/helix-editor/helix/blob/master/helix-core/src/lib.rs"
click node_syntax "https://github.com/helix-editor/helix/blob/master/helix-core/src/syntax.rs"
click node_config "https://github.com/helix-editor/helix/blob/master/helix-term/src/config.rs"
click node_loader "https://github.com/helix-editor/helix/blob/master/helix-loader/src/lib.rs"
click node_lsp_client "https://github.com/helix-editor/helix/blob/master/helix-lsp/src/client.rs"
click node_lsp_protocol "https://github.com/helix-editor/helix/blob/master/helix-lsp-types/src/lib.rs"
click node_dap_commands "https://github.com/helix-editor/helix/blob/master/helix-term/src/commands/dap.rs"
click node_dap_client "https://github.com/helix-editor/helix/blob/master/helix-dap/src/client.rs"
click node_vcs "https://github.com/helix-editor/helix/blob/master/helix-vcs/src/lib.rs"
click node_completion "https://github.com/helix-editor/helix/blob/master/helix-term/src/handlers/completion.rs"
click node_picker "https://github.com/helix-editor/helix/blob/master/helix-term/src/ui/picker/query.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_application,node_event_runtime,node_compositor,node_terminal_ui,node_user toneBlue
class node_editor,node_document,node_editing_core,node_syntax toneAmber
class node_config,node_loader toneMint
class node_lsp_handlers,node_lsp_client,node_lsp_protocol,node_dap_commands,node_dap_client toneRose
class node_vcs,node_completion,node_picker toneIndigo
```

## Components

### Entry and UI

- [CLI Entry](https://github.com/helix-editor/helix/blob/master/helix-term/src/main.rs): `helix-term/src/main.rs`
- [Application Loop](https://github.com/helix-editor/helix/blob/master/helix-term/src/application.rs): `helix-term/src/application.rs`
- [Event Runtime](https://github.com/helix-editor/helix/blob/master/helix-event/src/runtime.rs): `helix-event/src/runtime.rs`
- [UI Compositor](https://github.com/helix-editor/helix/blob/master/helix-term/src/compositor.rs): `helix-term/src/compositor.rs`
- [Terminal Renderer](https://github.com/helix-editor/helix/blob/master/helix-tui/src/terminal.rs): `helix-tui/src/terminal.rs`

### Editing Engine

- [Editor State](https://github.com/helix-editor/helix/blob/master/helix-view/src/editor.rs): `helix-view/src/editor.rs`
- [Document Model](https://github.com/helix-editor/helix/blob/master/helix-view/src/document.rs): `helix-view/src/document.rs`
- [Editing Primitives](https://github.com/helix-editor/helix/blob/master/helix-core/src/lib.rs): `helix-core/src/lib.rs`
- [Syntax Engine](https://github.com/helix-editor/helix/blob/master/helix-core/src/syntax.rs): `helix-core/src/syntax.rs`

### Workspace Services

- [Editor Config](https://github.com/helix-editor/helix/blob/master/helix-term/src/config.rs): `helix-term/src/config.rs`
- [Workspace Loader](https://github.com/helix-editor/helix/blob/master/helix-loader/src/lib.rs): `helix-loader/src/lib.rs`

### Language Tools

- **LSP Handlers**
- [LSP Client](https://github.com/helix-editor/helix/blob/master/helix-lsp/src/client.rs): `helix-lsp/src/client.rs`
- [LSP Protocol](https://github.com/helix-editor/helix/blob/master/helix-lsp-types/src/lib.rs): `helix-lsp-types/src/lib.rs`
- [DAP Commands](https://github.com/helix-editor/helix/blob/master/helix-term/src/commands/dap.rs): `helix-term/src/commands/dap.rs`
- [DAP Client](https://github.com/helix-editor/helix/blob/master/helix-dap/src/client.rs): `helix-dap/src/client.rs`

### Project Tools

- [VCS Integration](https://github.com/helix-editor/helix/blob/master/helix-vcs/src/lib.rs): `helix-vcs/src/lib.rs`
- [Completion UI](https://github.com/helix-editor/helix/blob/master/helix-term/src/handlers/completion.rs): `helix-term/src/handlers/completion.rs`
- [Picker Queries](https://github.com/helix-editor/helix/blob/master/helix-term/src/ui/picker/query.rs): `helix-term/src/ui/picker/query.rs`

### Other components

- **Editor User**

## Connections

- Editor User → CLI Entry: launches hx
- CLI Entry → Editor Config: loads config
- CLI Entry → Workspace Loader: loads resources
- CLI Entry → Application Loop: starts editor
- Application Loop → Editor State: creates editor
- Application Loop → UI Compositor: pushes view
- Application Loop → Event Runtime: awaits events
- Event Runtime → Application Loop: dispatches events
- Application Loop → Terminal Renderer: renders output
- Editor State → Document Model: updates documents
- Document Model → Editing Primitives: applies edits
- Document Model → Syntax Engine: provides text
- Application Loop → LSP Handlers: handles LSP events
- LSP Handlers → LSP Client: requests language features
- LSP Client → LSP Protocol: exchanges messages
- Application Loop → DAP Commands: dispatches debug commands
- DAP Commands → DAP Client: controls debugger
- Editor State → VCS Integration: reads project status
- LSP Handlers → Completion UI: updates completions
- Completion UI → Picker Queries: filters candidates
