Skip to main content
Warp is a Rust application built on a custom UI framework called WarpUI. The repository is a Cargo workspace with 34+ member crates that separates platform-specific code, core utilities, the UI framework, and the main application binary. Understanding the workspace layout and a handful of recurring architectural patterns will help you navigate the codebase quickly and write changes that fit naturally alongside existing code.

​
Workspace layout

warp/
├── app/                  # Main binary — terminal, AI, Drive, auth, settings
│   └── src/
│       ├── ai/           # Agent Mode, AI integration, codebase indexing
│       ├── auth/         # Authentication and user management
│       ├── drive/        # Warp Drive: cloud sync, panel, sharing, workflows
│       ├── settings/     # Settings and preferences
│       ├── terminal/     # Terminal emulation and shell management
│       └── workspace/    # Workspace and session management
├── crates/
│   ├── warp_features/    # FeatureFlag enum and flag state management
│   ├── warp_core/        # Core utilities and platform abstractions
│   ├── editor/           # Text editing functionality
│   ├── graphql/          # GraphQL client and generated schema code
│   ├── ipc/              # Inter-process communication
│   ├── integration/      # End-to-end integration tests
│   └── …                 # 28+ additional crates
├── ui/                   # WarpUI framework (warpui_core + warpui)
├── migrations/           # Diesel ORM database migrations
└── specs/                # Contributor specs (product.md + tech.md per issue)
The main binary lives in app/. The UI framework lives in ui/ and is published separately under the MIT license (the rest of the code is AGPL v3).

​
WarpUI framework

WarpUI is a custom retained-mode UI framework inspired by Flutter’s element model and GPUI’s entity system. It consists of two crates:
  • warpui_core — platform-agnostic primitives: layout elements, the entity/handle system, the action dispatch system, and the rendering model.
  • warpui — the full framework, including native platform integration, windowing, and the component library (ui_components).

​
Key WarpUI concepts

Elements describe visual layout and are Flutter-inspired: they are immutable descriptions of what to render, not the rendered output itself. Common elements include Flex, Align, Shrinkable, Hoverable, SavePosition, and ParentElement. Elements are composed into a tree during the render method of a view.
The actions system is the event-handling mechanism. Views declare the actions they handle, and the framework dispatches user input (keyboard, mouse, window events) to the correct handler through a StateEvent dispatch chain. The TypedActionView trait marks views that handle a specific action type.
AppContext provides temporary access to the global application state and all entity handles during render and event handling. It is passed as the last parameter to any function that needs access to other views or models — by convention, the parameter is always named ctx. Never store AppContext beyond the scope of a single function call.

​
Entity-Component-Handle pattern

The central architectural pattern in WarpUI is the Entity-Handle system.
  • A View (or Model) is an entity owned by the global App object.
  • Views reference other views via ViewHandle<T> — a lightweight reference-counted handle, not a direct ownership transfer.
  • During render and event handling, AppContext is used to dereference handles and access entity state.
  • WeakViewHandle<T> avoids retain cycles in cases where a child needs to reference its parent.
// A view holds handles to other views it collaborates with
pub struct DrivePanel {
    index_view: ViewHandle<DriveIndex>,
    mouse_state_handles: MouseStateHandles,
}
MouseStateHandle must be created once during view construction and then referenced or cloned anywhere mouse input tracking is needed. Creating a MouseStateHandle::default() inline during rendering will cause all mouse interactions for that element to silently stop working.

​
Key application modules

​
Terminal emulation (app/src/terminal/)

The terminal emulator is built on top of Alacritty’s grid and VTE parser. Warp adds its own block model on top, turning runs of output into structured, individually addressable blocks. Locking discipline: The TerminalModel uses an explicit mutex. Acquiring multiple locks on the same model from different call sites causes deadlocks. Always verify that no caller in the current call stack already holds the lock before adding a new model.lock() call.

​
AI integration (app/src/ai/)

Agent Mode and the AI assistant live here. Key sub-modules include the conversation model, the codebase indexing pipeline, the AI fact store, and the agent dispatch layer. The agent can call tools (grep, file retrieval, MCP servers) and produces structured diffs that feed into the code review panel.

​
Warp Drive (app/src/drive/)

Drive handles cloud synchronization of terminal objects. The DrivePanel component manages the sidebar UI and its interactions with the rest of the workspace. The DriveIndex view manages the internal tree, filtering, and item rendering. The sharing/ sub-module implements the ACL model and session sharing protocol.

​
Authentication (app/src/auth/)

Handles Firebase authentication, token refresh, and the server-side account and team model. Authentication state is used to gate Drive sync and team object visibility.

​
Settings (app/src/settings/)

Stores user preferences using a typed preferences model. When the SettingsFile feature flag is enabled, preferences can also be loaded from a settings.toml file with hot reload.

​
Persistence: Diesel and SQLite

Warp persists local state (Drive object cache, terminal history, settings) using Diesel ORM with a SQLite backend. The database schema is defined in app/src/persistence/schema.rs and migrations live in migrations/. Each Drive object carries a SyncId (local) and a ServerId (server-assigned) to reconcile offline changes with the server.

​
GraphQL client

Server communication is done over GraphQL. The schema lives in graphql/api/schema.graphql, and Rust client code is generated from it. WebSocket subscriptions (WS_SERVER_URL) are used for real-time updates such as session sharing events and Drive sync notifications.

​
Cross-platform strategy

Warp runs on macOS, Linux, Windows, and a WASM target. The strategy is:

Conditional compilation

Platform-specific code is gated with #[cfg(target_os = "...")]. Imports inside cfg-guarded branches may use absolute paths instead of top-level use statements to avoid polluting other platforms.

Runtime feature flags

Behavioral differences that do not require separate compilation paths (e.g., MSYS2 shell support on Windows) are gated with FeatureFlag variants so they can be toggled without recompilation.
Integration tests under crates/integration/ run on all supported platforms in CI to catch cross-platform regressions.

​
Coding style highlights

A few rules that differ from default Rust style:
  • No unnecessary type annotations in closure parameters.
  • Imports over path qualifiers: prefer use foo::Bar and then Bar over foo::Bar at each call site. Exception: inside #[cfg(...)] branches.
  • ctx goes last: any function taking an AppContext, ViewContext, or ModelContext names it ctx and puts it last. Exception: when a closure is the last parameter.
  • Remove unused parameters entirely — do not prefix with _. Update the signature and all call sites.
  • Inline format arguments: write eprintln!("{message}") not eprintln!("{}", message).
  • Exhaustive match: avoid _ wildcards in match statements wherever possible.
See WARP.md for the full style guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us