> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/warpdotdev/warp/llms.txt
> Use this file to discover all available pages before exploring further.

# Warp codebase architecture and key patterns

> Explore Warp's Cargo workspace of 34+ crates, the WarpUI framework, Entity-Component-Handle pattern, and cross-platform build strategy.

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

<Accordion title="Elements">
  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.
</Accordion>

<Accordion title="Actions">
  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.
</Accordion>

<Accordion title="AppContext">
  `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.
</Accordion>

## 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.

```rust theme={null}
// A view holds handles to other views it collaborates with
pub struct DrivePanel {
    index_view: ViewHandle<DriveIndex>,
    mouse_state_handles: MouseStateHandles,
}
```

<Warning>
  `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.
</Warning>

## Key application modules

### Terminal emulation (`app/src/terminal/`)

The terminal emulator is built on top of [Alacritty](https://github.com/alacritty/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](https://diesel.rs/) 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:

<CardGroup cols={2}>
  <Card title="Conditional compilation" icon="code">
    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.
  </Card>

  <Card title="Runtime feature flags" icon="toggle-on">
    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.
  </Card>
</CardGroup>

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](https://github.com/warpdotdev/warp/blob/master/WARP.md) for the full style guide.