AGENTS.md

1# AGENTS.md
2 
3This file provides guidance when working with code in this repository.
4 
5## Development Commands
6 
7### Build and Run
8- `cargo run` / `./script/run` - Build and run the GUI desktop app locally
9- `./script/run-tui` - Build and run the headless TUI front-end (`crates/warp_tui`)
10- `cargo bundle --bin warp` - Bundle the main (GUI) app
11 
12### Running with local warp-server
13To connect Warp client to a local warp-server instance:
14 
15```bash
16# Connect to server on default port 8080
17WITH_LOCAL_SERVER=1 ./script/run
18 
19# Connect to server on custom port (e.g., 8082)
20WITH_LOCAL_SERVER=1 SERVER_ROOT_URL=http://localhost:8082 WS_SERVER_URL=ws://localhost:8082/graphql/v2 ./script/run
21```
22 
23Environment variables:
24- `SERVER_ROOT_URL` - HTTP endpoint (default: `http://localhost:8080`)
25- `WS_SERVER_URL` - WebSocket endpoint (default: `ws://localhost:8080/graphql/v2`)
26 
27### Testing
28- `cargo nextest run --no-fail-fast --workspace --exclude command-signatures-v2` - Run tests with nextest
29- `cargo nextest run -p warp_completer --features v2` - Run completer tests with v2 features
30- `cargo test --doc` - Run doc tests
31- `cargo test` - Run standard tests for individual packages
32 
33### Linting and Formatting
34- `./script/presubmit` - Run all presubmit checks (fmt, clippy, tests)
35- `./script/format` - Format code
36- `cargo clippy --workspace --all-targets --all-features --tests -- -D warnings` - Run clippy
37- `./script/run-clang-format.py -r --extensions 'c,h,cpp,m' ./crates/warpui/src/ ./app/src/` - Format C/C++/Obj-C code
38- `find . -name "*.wgsl" -exec wgslfmt --check {} +` - Check WGSL shader formatting
39 
40### Platform Setup
41- `./script/bootstrap` - Platform-specific setup plus common agent skill installation from `skills-lock.json`; prompts for project/global when an install or update is needed unless a target flag or environment override is provided.
42- `./script/bootstrap --skip-common-skills` - Platform setup without installing or updating common agent skills.
43- `./script/bootstrap --install-common-skills` - Explicitly install common agent skills from `skills-lock.json`; this is the default behavior.
44- `./script/bootstrap --install-common-skills-in-repo` - Platform setup plus common agent skill installation in this checkout's `.agents/skills`.
45- `./script/bootstrap --install-common-skills-globally` - Platform setup plus common agent skill installation in `~/.agents/skills`.
46- `../common-skills/scripts/install_common_skills --repo-root "$PWD" --project --if-needed` - Install or refresh shared agent skills in this checkout's `.agents/skills`.
47- `../common-skills/scripts/install_common_skills --repo-root "$PWD" --global --if-needed` - Install or refresh shared agent skills in `~/.agents/skills`.
48- `../common-skills/scripts/remove_common_skills --repo-root "$PWD"` - Remove shared agent skills listed in `skills-lock.json` from this checkout's `.agents/skills`.
49- `../common-skills/scripts/remove_common_skills --repo-root "$PWD" --global` - Remove shared agent skills listed in `skills-lock.json` from `~/.agents/skills`.
50- `../common-skills/scripts/remove_common_skills --repo-root "$PWD" --clear-lock` - Remove shared agent skills from this checkout and delete `skills-lock.json`.
51- `./script/install_cargo_build_deps` - Install Cargo build dependencies
52- `./script/install_cargo_test_deps` - Install Cargo test dependencies
53 
54`skills-lock.json` is the standard project lock file managed by `npx skills`. `warpdotdev/common-skills/scripts/install_common_skills` requires an explicit install target before restoring: pass `--project`, pass `--global`, set `WARP_COMMON_SKILLS_INSTALL_TARGET`, or answer the interactive prompt from bootstrap. Non-interactive flows fail if no target is explicit. The installer creates `skills-lock.json` from `warpdotdev/common-skills` if it is missing, uses global as the recommended interactive default, errors if common skills are present in both project and global locations, prevents a global install pinned to one lock from being silently overwritten by another checkout pinned to a different lock, and verifies installed skills against the lock after successful install or skip paths. `script/run` and `script/bootstrap` execute this installer with `script/resolve_common_skills`, which uses `WARP_COMMON_SKILLS_SCRIPTS_DIR` only when explicitly set and otherwise runs the raw script from `warpdotdev/common-skills`. To test a remote common-skills branch, set `WARP_COMMON_SKILLS_REF=<branch>`. Cloud setup should use `common-skills/scripts/install_common_skills --repo-root <warp-checkout> --project --if-needed --non-interactive` or set `WARP_COMMON_SKILLS_INSTALL_TARGET=project` to avoid the prompt. To update the locked common skills, run `npx --yes skills@1.5.6 update -p -y` and commit the resulting `skills-lock.json` changes.
55 
56## Architecture Overview
57 
58This is a Rust-based terminal emulator with a custom UI framework called **WarpUI**. It has **two front-ends** that share a common core.
59 
60### Front-ends: GUI and TUI
61 
62Warp has two front-ends that share the `warp_core`/`warpui` Entity/model core (App/Entity/`AppContext`, actions, `Appearance`, `FeatureFlag`, telemetry, logging) but differ in UI framework, rendering, input, and verification:
63- **GUI desktop app** — the `app/` crate on the WarpUI pixel/GPU framework (`warpui`, `crates/warpui_core`): `Element`/`View` layout, GPU/WGSL rendering, mouse input, `.app` bundles. Run with `cargo run` / `./script/run`; verify visually with `computer_use` or the real-display integration framework (`crates/integration`).
64- **Headless TUI** — the `crates/warp_tui` crate: a console app (run with `./script/run-tui`; no `.app`/GPU) rendered with a parallel cell-grid element library at `crates/warpui_core/src/elements/tui` (the `TuiElement` trait), behind the `tui` cargo feature. Verify by running it in a real terminal and observing output; test with render-to-lines unit tests.
65 
66**Skill convention:** a skill specific to one front-end says so in its name and/or description (e.g. `gui-ui-guidelines` / `gui-integration-test` are GUI-only; `tui-ui-guidelines`, `tui-testing`, and `tui-verify-change` are TUI-specific). Skills with no front-end call-out are surface-agnostic and apply to both. For TUI work prefer the `tui-*` skills and ignore GUI-only ones — and vice versa.
67 
68### Key Components
69 
70**Shared UI core** (`crates/warpui`, `crates/warpui_core`) — used by **both** front-ends:
71- Entity-Component-Handle pattern: a global `App` object owns all views/models (entities); views hold `ViewHandle<T>` references to other views; `AppContext` provides temporary access to handles during render/events.
72- Actions system for event handling.
73- `crates/warpui_core` also hosts the TUI cell-grid element library under `src/elements/tui` (behind the `tui` feature).
74 
75**GUI rendering** (WarpUI GUI elements — GUI-specific):
76- `Element`s describe visual layout (Flutter-inspired), rendered on the GPU (WGSL).
77- Mouse input uses `MouseStateHandle`: create it once during construction and reference/clone it wherever mouse input is tracked. An inline `MouseStateHandle::default()` while rendering means no mouse interactions work. (The TUI's hover/click elements — `TuiHoverable`, `tui_collapsible` — also build on `MouseStateHandle`, so the same ownership rule applies there.)
78 
79**TUI rendering** (`crates/warp_tui` + `crates/warpui_core/src/elements/tui` — TUI-specific):
80- Headless console front-end. The `TuiElement` trait lays out and paints into a cell-grid `TuiBuffer`; crossterm input is converted to `TuiEvent`. No GPU/WGSL, pixel geometry, or `.app` bundle.
81 
82**Main app / shared surfaces** (`app/`) — the GUI desktop app plus feature surfaces the TUI reuses:
83- Terminal emulation and shell management (`terminal/`)
84- AI integration including Agent Mode (`ai/`)
85- Cloud synchronization and Drive features (`drive/`)
86- Authentication and user management (`auth/`)
87- Settings and preferences (`settings/`)
88- Workspace and session management (`workspace/`)
89 
90**Core Libraries**:
91- `crates/warp_core/` - Core utilities and platform abstractions (shared)
92- `crates/warp_tui/` - Headless TUI front-end
93- `crates/editor/` - Text editing functionality
94- `crates/warpui/` and `crates/warpui_core/` - Custom UI framework (shared core plus the GUI and TUI element libraries)
95- `crates/ipc/` - Inter-process communication
96- `crates/graphql/` - GraphQL client and schema
97 
98### Key Architectural Patterns
99 
1001. **Entity-Handle System**: Views reference other views via handles, not direct ownership
1012. **Modular Structure**: Workspace contains multiple workspace configurations, each with terminals, notebooks, etc.
1023. **Cross-Platform**: Native implementations for macOS, Windows, Linux, plus WASM target
1034. **AI Integration**: Built-in AI assistant with context awareness and codebase indexing
1045. **Cloud Sync**: Objects can be synchronized across devices via Warp Drive
105 
106### Development Guidelines
107 
108**Workspace Structure**:
109- This is a Cargo workspace with 60+ member crates
110- Main binary is in `app/`, UI framework in `crates/warpui/`
111- Platform-specific code is conditionally compiled
112- Integration tests are in `crates/integration/`
113 
114**Coding Style Preferences**:
115- Avoid unnecessary type annotations, especially in closure params.
116- Avoid using too many Rust path qualifiers and use imports for concision. Place import statements at the top of the file as per convention.
117  An exception to this is inside cfg-guarded code branches. In those cases, you can either embed the import into the relevant scope or just use an absolute path for one-offs.
118- If a function takes a context parameter (`AppContext`, `ViewContext`, or `ModelContext`), it should be named `ctx` and go last. The one exception is for
119  functions that take a closure parameter, in which case the closure should be last.
120- Always remove unused parameters completely rather than prefixing them with `_`. Update the function signature and all call sites accordingly.
121- Prefer inline format arguments in macros like `println!`, `eprintln!`, and `format!` (for example, `eprintln!("{message}")` instead of `eprintln!("{}", message)`) to satisfy Clippy's `uninlined_format_args` lint.
122- Do not pass `Itertools::format` results directly to logging macros (`log::*`, `safe_*`, etc.). `Itertools::format` produces a single-use formatter, while logging implementations may format a message more than once. Use a reusable `String` such as `iter.join(", ")` for logging arguments instead. Direct use in `format!` or `write!` is fine.
123- Do not remove existing comments when making unrelated changes. Only remove or modify a comment if the logic it describes has changed.
124- When adding a toggleable setting, also add the matching Command Palette enable/disable entry and any required context flags so the setting is discoverable outside Settings.
125 
126**Terminal Model Locking**:
127- Be extremely careful when calling `model.lock()` on the terminal model (`TerminalModel`). Acquiring multiple locks on the same model from different call sites can cause a deadlock, resulting in a UI freeze (beach ball on macOS).
128- Before adding a new `model.lock()` call, verify that no caller in the current call stack already holds the lock.
129- Prefer passing already-locked model references down the call stack rather than acquiring new locks.
130- If you must lock the model, keep the lock scope as short as possible and avoid calling other functions that might also attempt to lock.
131 
132**Testing**:
133- Use `cargo nextest` for parallel test execution
134- Integration tests use the custom framework in `crates/integration/` — this is **GUI-only**. TUI elements/screens are covered by render-to-lines unit tests instead (see the `tui-testing` skill).
135- Tests should be run via presubmit script before submitting
136- Unit tests should be placed in separate files using the naming convention `${filename}_tests.rs` or `mod_test.rs`
137- Test files should be included at the end of their corresponding module with:
138```rust
139  #[cfg(test)]
140  #[path = "filename_tests.rs"]  // or "mod_test.rs"
141  mod tests;
142```
143 
144**Pull Request Workflow**:
145- **ALWAYS** run `./script/format` and `cargo clippy` (the versions specified in ./script/presubmit) before opening a PR or pushing updates to an existing PR branch
146- Those commands must pass completely before creating or updating a pull request
147- Specifically, ensure `./script/format` and `cargo clippy` checks pass
148- If they fail, fix all issues before proceeding with the PR
149- Do not create public pull requests or public issues that disclose a non-public security vulnerability. Refer users to `SECURITY.md` for the proper disclosure methods instead.
150- This applies to:
151  - Opening new pull requests
152  - Pushing new commits to existing PR branches
153  - Any branch updates that will be reviewed
154 - When opening PRs, use the PR template at `.github/pull_request_template.md`
155 - Add changelog entries when appropriate using the format at the bottom of the PR template. Use the following prefixes (without the `{{}}` brackets):
156   - `CHANGELOG-NEW-FEATURE:` for new, relatively sizable features (use sparingly - these may get marketing/docs)
157   - `CHANGELOG-IMPROVEMENT:` for new functionality of existing features
158   - `CHANGELOG-BUG-FIX:` for fixes related to known bugs or regressions
159   - `CHANGELOG-IMAGE:` for GCP-hosted image URLs
160   - Leave changelog lines blank or remove them if no changelog entry is needed
161 
162**Database**:
163- Uses Diesel ORM with SQLite
164- Migrations in `crates/persistence/migrations/`
165- Schema defined in `crates/persistence/src/schema.rs`
166 
167**GraphQL**:
168- Schema and client code generation from `crates/warp_graphql_schema/api/schema.graphql`
169- TypeScript types generated for frontend integration
170 
171### Feature Flags
172 
173Warp uses compile-time feature flags with a small runtime plumbing layer.
174 
175How to add a feature flag:
176- Add a new variant to `warp_core/src/features.rs` in the `FeatureFlag` enum
177- (Optional) Enable it by default for dogfood builds by listing it in `DOGFOOD_FLAGS`
178- Gate code paths with `FeatureFlag::YourFlag.is_enabled()`
179- For preview or release rollout, add to `PREVIEW_FLAGS` or `RELEASE_FLAGS` respectively (as appropriate)
180 
181Best practices:
182- **Prefer runtime checks over cfg directives**: Prefer `FeatureFlag::YourFlag.is_enabled()` over `#[cfg(...)]` compile-time directives so flags can be toggled without recompilation and are easier to clean up later. Use `#[cfg(...)]` only when the code cannot compile without them (for example, platform-specific code or dependencies that do not exist when the feature is disabled).
183- Keep flags high-level and product-focused rather than per-call-site
184- Remove the flag and dead branches after launch has stabilized
185- For UI sections that expose a new feature, hide the UI behind the same flag
186 
187Example:
188```rust
189#[derive(Sequence)]
190pub enum FeatureFlag {
191    YourNewFeature,
192}
193 
194// Default-on for dogfood builds
195pub const DOGFOOD_FLAGS: &[FeatureFlag] = &[
196    FeatureFlag::YourNewFeature,
197];
198 
199// Use in code
200if FeatureFlag::YourNewFeature.is_enabled() {
201    // gated behavior
202}
203```
204 
205### Exhaustive Matching
206 
207When adding/editing match statements, avoid using the wildcard _ when at all possible. Exhaustive matching is helpful for ensuring that all variants are handled, especially when adding new variants to enums in the future.
208