# Developer Skills & Environment Setup

> How do you set up this terminal-robot's environment? By running script/bootstrap, which installs Cargo dependencies and restores shared agent skills from a lock file called skills-lock.json. This lock file works like a toy chest list, ensuring everyone has the same common skills. Developers build with script/run, test with cargo nextest, and verify formatting and clippy lints with script/presubmit before opening a pull request.

- Repository: warpdotdev/warp
- GitHub: https://github.com/warpdotdev/warp
- Human wiki: https://grok-wiki.com/public/wiki/warpdotdev-warp-a2a3b9202160
- Complete Markdown: https://grok-wiki.com/public/wiki/warpdotdev-warp-a2a3b9202160/llms-full.txt

## Source Files

- `script/bootstrap`
- `script/run`
- `script/presubmit`
- `script/resolve_common_skills`
- `skills-lock.json`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [script/bootstrap](script/bootstrap)
- [script/run](script/run)
- [script/presubmit](script/presubmit)
- [script/resolve_common_skills](script/resolve_common_skills)
- [skills-lock.json](skills-lock.json)
</details>

# Developer Skills & Environment Setup

Welcome to the Warp developer environment! Setting up your local machine to build, test, and contribute to an advanced terminal client is made straightforward by a suite of helper scripts. These scripts automate installing platform dependencies, pulling media assets, and synchronizing shared instructions known as **agent skills**. 

Think of this repository like a software engineering workshop. Before starting any work, you need your workbench fully loaded with the correct tools (compilers, linters, and formatters) and a clean toy chest containing all the common skills. The repository provides built-in automation to guarantee that every developer starts with the exact same standardized workshop setup, ensuring compilation and validation remain predictable across macOS, Linux, and Windows.

---

## Bootstrapping the Workshop

To begin development, you must first prepare your environment by executing the bootstrapping process. The entry point is `./script/bootstrap`. This script is a smart shell manager that runs setup tasks tailored to your workstation's operating system.

### Core Bootstrap Phases
1. **Large Asset Retrieval (Git LFS)**: Warp relies on Large File Storage (LFS) for graphics, fonts, and binary assets. The bootstrap script automatically verifies if `git-lfs` is on your path, installs it locally if needed, and downloads any heavy assets (`Sources: [script/bootstrap:136-151]()`).
2. **Platform Identification**: The script inspects your machine's OS type (such as macOS `Darwin`, generic `Linux`, or Windows console environments like `MSYS`/`MINGW`) to call the appropriate helper (`Sources: [script/bootstrap:9-10]()`).
3. **Platform Dependency Installation**: It dispatches work to target-specific scripts such as `script/macos/bootstrap`, `script/linux/bootstrap`, or `script/windows/bootstrap.ps1` (`Sources: [script/bootstrap:155-172]()`):
   - **macOS**: Configures Xcode command line tools, installs Cargo, Homebrew packages (such as PowerShell, Docker, and gcloud), and adds the standard Apple Silicon Rust compilation target `aarch64-apple-darwin` (`Sources: [script/bootstrap:54-57]()`).
   - **Linux**: Pulls updated package metadata via `apt`, installs system-level dependencies for building graphics/terminal engines, configures package creation tools (`linuxdeploy`), and prompts for Google Cloud authentication (`Sources: [script/bootstrap:58-62]()`).
4. **Agent Skill Synchronization**: It invokes the skill resolver to synchronize your local workspace with the shared agent capabilities needed for developer automation (`Sources: [script/bootstrap:115-132]()`).

`Sources: [script/bootstrap:9-10]()`, `Sources: [script/bootstrap:54-62]()`, `Sources: [script/bootstrap:115-132]()`, `Sources: [script/bootstrap:136-151]()`, `Sources: [script/bootstrap:155-172]()`

---

## Agent Skills and the Toy Chest Lock

Warp utilizes specialized, versioned AI behaviors called **agent skills** to assist with coding tasks, PR walkthroughs, and error debugging. 

To ensure every developer and automated agent uses the exact same version of these skills, they are tracked inside `skills-lock.json`. 

### The Skills Lock File
Think of `skills-lock.json` as a toy chest inventory list. It catalogues every authorized agent skill (such as `brandalf`, `create-pr`, `review-pr`, and `diagnose-ci-failures`), referencing its source location on GitHub and its unique cryptographically computed checksum hash (`computedHash`) (`Sources: [skills-lock.json:1-78]()`). This lock file prevents anyone from running modified or untrusted versions of these common skills.

### Resolving and Installing Skills
The utility `./script/resolve_common_skills` acts as the transporter to fetch and verify these skills:
- **Local Directory Overrides**: If you have a custom folder of skills defined by the environment variable `WARP_COMMON_SKILLS_SCRIPTS_DIR`, the resolver uses it (`Sources: [script/resolve_common_skills:10-23]()`).
- **Remote Fallback**: Otherwise, the resolver fetches the latest standard installer script directly from the remote `warpdotdev/common-skills` GitHub repository using `curl` (`Sources: [script/resolve_common_skills:25-51]()`).
- **Target Directories**: Skills are checked out and verified against their hashes. They can be installed locally into the repository checkout (`.agents/skills`) or globally in your user directory (`~/.agents/skills`) (`Sources: [script/bootstrap:25-30]()`).

`Sources: [skills-lock.json:1-78]()`, `Sources: [script/resolve_common_skills:10-51]()`, `Sources: [script/bootstrap:25-30]()`

---

## Building and Running Warp

Once the workstation is bootstrapped, you build and run your local copy of Warp using `./script/run`.

```mermaid
sequenceDiagram
    autonumber
    actor Developer
    participant Run as script/run
    participant RC as script/resolve_common_skills
    participant Lock as skills-lock.json
    participant Cargo as Cargo compiler

    Developer->>Run: Executes ./script/run [arguments]
    Run->>Run: Detects build channel (Local vs OSS)
    Run->>RC: Verifies installed agent skills
    RC->>Lock: Compares hashes
    alt Skills Out of Date
        RC->>RC: Pulls & Updates matching skills
    end
    Run->>Run: Translates deprecated cargo features to environment variables
    Run->>Cargo: Runs cargo build & run
    Cargo-->>Developer: Launches local Warp terminal
```

### Channel Selection
The build script automatically detects whether you have access to proprietary configuration layers. If the premium utility `warp-channel-config` is available on your shell's command path, it compiles the standard `warp` binary using the `local` channel; otherwise, it builds the open-source `warp-oss` binary on the `oss` channel (`Sources: [script/run:29-36]()`).

### Dependency and Argument Parsing
- **Skill Integrity Verification**: Every time you launch a build, the script executes a quiet, rapid verification via `./script/resolve_common_skills --verify-only` to guarantee your active skills still match the hashes recorded in the lock file (`Sources: [script/run:98-128]()`).
- **Feature Mapping**: Modern configurations read certain flags from environment variables rather than cargo features. The script intercepts legacy features (like `with_local_server`, `with_local_session_sharing_server`, and `with_sandbox_telemetry`) and maps them to environment variables before calling Cargo (`Sources: [script/run:130-145]()`).
- **Execution**: On macOS, it delegates compilation to `./script/macos/run` to handle native `.app` application bundle code-signing and packaging. On Linux and Windows, it calls `cargo run` directly (`Sources: [script/run:151-167]()`).

```bash
# File: script/run (Lines 29-36)
# If warp_channel_config is on PATH, build the Local channel binary; otherwise build the OSS channel.
if command -v warp-channel-config &>/dev/null; then
    WARP_BIN_NAME="warp"
    WARP_CHANNEL="local"
else
    WARP_BIN_NAME="warp-oss"
    WARP_CHANNEL="oss"
fi
```

`Sources: [script/run:29-36]()`, `Sources: [script/run:98-128]()`, `Sources: [script/run:130-145]()`, `Sources: [script/run:151-167]()`

---

## Configuration Options & Parameters

The behavior of these onboarding and execution scripts can be customized through specific parameters and environment variables:

| Option / Variable | Script Context | Purpose & Effect |
| :--- | :--- | :--- |
| `WARP_SKIP_COMMON_SKILLS_INSTALL` | Bootstrap & Run | Set to `1` to bypass downloading or verifying agent skills entirely (`Sources: [script/bootstrap:33-34]()`, `Sources: [script/run:111-112]()`). |
| `WARP_COMMON_SKILLS_INSTALL_TARGET` | Bootstrap & Run | Set to `project` (installing in `.agents/skills`) or `global` (installing in `~/.agents/skills`) to skip target selection prompts (`Sources: [script/bootstrap:35-38]()`, `Sources: [script/run:24-25]()`). |
| `--skip-common-skills` | Bootstrap option | Disables all agent skill setups during the initial bootstrap run (`Sources: [script/bootstrap:23-30]()`). |
| `--install-common-skills` | Run option | Forcefully re-installs and updates common skills matching the lock file (`Sources: [script/run:70-73]()`). |
| `WARP_SKIP_SUDO_PROMPT` | Bootstrap variable | Set to `1` (or pass `-y`/`--yes`) to run non-interactively in CI and bypass manual confirmation popups (`Sources: [script/bootstrap:5-7]()`). |

`Sources: [script/bootstrap:5-7]()`, `Sources: [script/bootstrap:23-38]()`, `Sources: [script/run:24-25]()`, `Sources: [script/run:70-73]()`, `Sources: [script/run:111-112]()`

---

## Presubmit Quality Guardrails

Before pushing your changes and opening a pull request, you should run `./script/presubmit` locally. This script mirrors the automated verification checks performed on CI, ensuring your code aligns with standard requirements before manual review.

### Standard Quality Checks
- **Code Formatting**: Validates Rust code aesthetics using `cargo fmt -- --check` (`Sources: [script/presubmit:9-17]()`).
- **Static Analysis (Clippy)**: Evaluates Rust code quality using `cargo clippy`. The script intentionally runs workspace checks excluding the `warp_completer` crate so it can run it separately under default features (to safeguard feature-gated JavaScript completions development) (`Sources: [script/presubmit:21-29]()`).
- **Clang and Shader Formatting**: Formats native C, C++, Objective-C, and Metal headers (`.crates/warpui/src/` and `app/src/`) using `script/run-clang-format.py` (`Sources: [script/presubmit:31-33]()`) and WebGPU Shader Language files using `wgslfmt --check` (`Sources: [script/presubmit:35-39]()`).
- **PowerShell Script Linting**: If a PowerShell installation (`pwsh`) is detected (or if running within a GitHub Actions runner), it executes `PSScriptAnalyzer` over automation assets (`Sources: [script/presubmit:41-53]()`).
- **Test Executions**: Runs the core test suite utilizing the high-performance `cargo nextest` runner (`Sources: [script/presubmit:55-59]()`) and tests code examples embedded in documentation using `cargo test --doc` (`Sources: [script/presubmit:60-62]()`).

`Sources: [script/presubmit:9-17]()`, `Sources: [script/presubmit:21-29]()`, `Sources: [script/presubmit:31-39]()`, `Sources: [script/presubmit:41-53]()`, `Sources: [script/presubmit:55-62]()`

---

## Summary

Maintaining a highly standardized developer environment reduces onboarding hurdles and captures errors long before they hit production. By verifying all active agent tools against a cryptographic hash index, tracking dependencies automatically across macOS, Linux, and Windows, and running local lint and test suits via presubmit guardrails, the Warp repository ensures a predictable, clean, and productive workflow for all contributors (`Sources: [script/presubmit:64-65]()`).