# Warp AI: Built-in Agents & Codebase Context

> How does the built-in AI help you? It isn't just a text box; it is connected to a skill provider and codebase indexer that scans file paths and reads skills. The system can parse special instructions to let agents plan, triage issues, review PRs, and run shell tools, keeping the design provider-neutral so you can bring any AI provider (like Claude or GPT).

- 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

- `crates/ai/src/lib.rs`
- `crates/ai/src/skills/skill_provider.rs`
- `crates/ai/src/skills/parse_skill.rs`
- `crates/ai/src/workspace.rs`
- `crates/ai/src/paths.rs`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [crates/ai/src/lib.rs](crates/ai/src/lib.rs)
- [crates/ai/src/skills/skill_provider.rs](crates/ai/src/skills/skill_provider.rs)
- [crates/ai/src/skills/parse_skill.rs](crates/ai/src/skills/parse_skill.rs)
- [crates/ai/src/workspace.rs](crates/ai/src/workspace.rs)
- [crates/ai/src/paths.rs](crates/ai/src/paths.rs)
- [crates/ai/src/skills/read_skills.rs](crates/ai/src/skills/read_skills.rs)
- [crates/ai/src/skills/parser.rs](crates/ai/src/skills/parser.rs)
- [crates/ai/src/skills/skill_reference.rs](crates/ai/src/skills/skill_reference.rs)
- [crates/ai/src/project_context/model.rs](crates/ai/src/project_context/model.rs)
- [crates/ai/src/project_context/global_rules.rs](crates/ai/src/project_context/global_rules.rs)
- [crates/ai/src/agent/orchestration_config.rs](crates/ai/src/agent/orchestration_config.rs)
- [crates/ai/src/agent/action/mod.rs](crates/ai/src/agent/action/mod.rs)
- [WARP.md](WARP.md)
</details>

# Warp AI: Built-in Agents & Codebase Context

Warp is far more than a standard terminal window; it features a deeply integrated AI agent orchestration system and codebase context engine. This architecture allows developers to bring their own intelligence provider (BYOC/BYOK)—whether that is Claude, GPT, Gemini, or a custom model—while leveraging powerful, file-based capabilities (skills) and local codebase understanding. 

This wiki page breaks down the architectural components that make Warp AI work, including the local context engine (project/global rules), skill providers, multi-agent orchestrator, cross-platform path translator, and persistent workspace metrics.

---

## 1. ELI5: How Warp AI Thinks (The Smart Newcomer's Guide)

To understand Warp AI's design, imagine a **highly specialized developer** joining your team. 

*   **The Desk (Workspace Metadata):** Before the developer starts working, they check their desk space. The workspace metadata acts like a diary, tracking which projects they touched most recently (`WorkspaceMetadata` persisted in SQLite) so they know where to focus first.
*   **The Office Rulebooks (Project & Global Rules):** At the entrance of the office is a general guide everyone must follow (`~/.agents/AGENTS.md` under Global Rules). When the developer enters a specific team's room, they read the team-specific chalkboard (`WARP.md` or `AGENTS.md` at the project level). This ensures they adhere to local coding styles and guidelines.
*   **The Training Manuals (Skill Providers & Parsers):** When the developer needs to do a specialized task (like adding a feature flag or reviewing a PR), they read a short step-by-step instruction manual (`SKILL.md` from a directory like `.agents/skills`). Warp's skill provider locates and parses these manuals dynamically.
*   **The Translator (Paths Abstraction):** The developer writes code on their laptop (e.g., Windows running WSL), but the terminal executes the code in a Linux environment. The path translator (`paths.rs`) bridges this gap, translating paths so that commands run smoothly across differing filesystems.
*   **The Subcontractors (Agent Orchestration & Action Harnesses):** If the task is too large, the lead developer hires specialized subcontractors (agent harnesses like `oz`, `claude`, `opencode`, `gemini`, or `codex`). They give them specific tasks (read a file, write a file, run a terminal command, or ask the user a question) using a standard project layout, completely independent of who actually "employs" them.

Sources: [crates/ai/src/workspace.rs:7-65](crates/ai/src/workspace.rs#L7-L65), [crates/ai/src/project_context/model.rs:27-51](crates/ai/src/project_context/model.rs#L27-L51), [crates/ai/src/skills/skill_provider.rs:17-41](crates/ai/src/skills/skill_provider.rs#L17-L41), [crates/ai/src/paths.rs:19-32](crates/ai/src/paths.rs#L19-L32), [crates/ai/src/agent/orchestration_config.rs:186-198](crates/ai/src/agent/orchestration_config.rs#L186-L198)

---

## 2. High-Signal System Architecture

Warp AI decouples UI presentation, filesystem indexing, rule parsing, and external model orchestration. The following diagram illustrates the lifecycle of a user query and how codebase context is assembled:

```mermaid
flowchart TB
    subgraph UI ["User Interface (Warp UI)"]
        Chat["Built-in AI Assistant Chat Box"]
        Confirm["Agent Tool Approval Card"]
    end

    subgraph Runtime ["AI Runtime & Context (crates/ai)"]
        PCModel["ProjectContextModel"]
        SPMap["SkillProvider Map"]
        WMetadata["WorkspaceMetadata (SQLite)"]
        Paths["Paths Conversion Handler"]
    end

    subgraph Storage ["Context Configuration Files"]
        GlobalRules["Global Rules (~/.agents/AGENTS.md)"]
        ProjRules["Project Rules (WARP.md / AGENTS.md)"]
        SkillMD["Skill Catalog (SKILL.md in .claude/, .agents/, etc.)"]
    end

    subgraph AgentOrch ["Multi-Agent Orchestration"]
        Orch["OrchestrationConfig"]
        Harness["Harness Options: oz, claude, opencode, gemini, codex"]
        Actions["AIAgentActionType (ReadFiles, ShellCmd, FileEdits, AskUser)"]
    end

    Chat -->|1. Triggers Query| PCModel
    PCModel -->|2. Pulls Rules| GlobalRules & ProjRules
    PCModel -->|3. Retrieves Skills| SPMap
    SPMap -->|Reads SKILL.md| SkillMD
    PCModel -->|4. Path Mapping| Paths
    PCModel -->|5. Metadata SQLite Store| WMetadata
    PCModel -->|6. Spawns Orchestrator| Orch
    Orch -->|7. Dispatches Harness| Harness
    Harness -->|8. Executes Tools| Actions
    Actions -->|9. Requests Confirmation| Confirm
```

Sources: [crates/ai/src/lib.rs:1-16](crates/ai/src/lib.rs#L1-L16), [WARP.md:55-91](WARP.md#L55-L91)

---

## 3. Multi-Agent Orchestration & Action Harnesses

At the core of Warp AI's execution system is a multi-agent framework that translates natural language prompts into concrete local actions. It supports five primary client-side execution environments (harnesses):

*   `oz` (custom cloud browser/computer use agent)
*   `claude` (ClaudeCode integration)
*   `opencode` (Open-source agent runner)
*   `gemini` (Gemini-powered agent runner)
*   `codex` (Codex-powered agent runner)

The agent runtime is managed via the `OrchestrationConfig` struct, which tracks the `model_id`, execution mode (local vs. remote), and approval state (`OrchestrationConfigStatus::Approved` or `Disapproved`). This architecture ensures provider neutrality: the agent framework defines **how** actions are executed, while the LLM provider merely defines **what** to do.

```rust
// crates/ai/src/agent/orchestration_config.rs
pub struct OrchestrationConfig {
    pub model_id: String,
    pub harness_type: String,
    pub execution_mode: OrchestrationExecutionMode,
}

pub enum OrchestrationExecutionMode {
    Local,
    Remote {
        environment_id: String,
        worker_host: String,
    },
}
```

### Supported Actions (AIAgentActionType)

When an agent executes, it interacts with the system using client-gated actions that protect user safety (e.g., prompting for terminal command approvals). Key actions include:

| Action Name | Description |
| :--- | :--- |
| `RequestCommandOutput` | Requests shell execution; flags risky commands and identifies read-only calls. |
| `ReadFiles` | Reads content from specified local files. |
| `RequestFileEdits` | Proposes a list of file diffs to be applied to the codebase. |
| `CallMCPTool` | Invokes an external tool using the Model Context Protocol (MCP). |
| `AskUserQuestion` | Requests direct clarification or feedback from the user. |
| `RunAgents` | Coordinates and runs multiple child agents under an unified implementation plan. |

Sources: [crates/ai/src/agent/orchestration_config.rs:11-24](crates/ai/src/agent/orchestration_config.rs#L11-L24), [crates/ai/src/agent/orchestration_config.rs:186-198](crates/ai/src/agent/orchestration_config.rs#L186-L198), [crates/ai/src/agent/action/mod.rs:30-175](crates/ai/src/agent/action/mod.rs#L30-L175)

---

## 4. Local Context Engine: Project & Global Rules

To prevent agents from hallucinating rules or writing standard code that conflicts with team conventions, Warp's `ProjectContextModel` dynamically aggregates local rule configuration files.

### Project-Scoped Rules
The indexer scans the project directories for `WARP.md` and `AGENTS.md` files.
*   **Active Rules:** Rules found in directories that are direct ancestors of the file currently being edited. These are eagerly injected into the agent's context.
*   **Available Rules:** Rules located in sibling or parallel directories. They remain in-memory and become active if the agent navigates into those directories.
*   **Scanning Limits:** To prevent system lag, Warp limits directory depth scans to `MAX_SCAN_DEPTH = 3` and maximum files scanned to `MAX_FILES_TO_SCAN = 5000`.

### Global-Scoped Rules
Users can establish persistent, system-wide behavior across all terminal sessions and codebases.
*   Warp indexes global rule sources from `~/.agents/AGENTS.md` (`GlobalRuleSource::Agents`).
*   It subscribes to `HomeDirectoryWatcher` and `DirectoryWatcher` to monitor when global rules are edited, created, or deleted at runtime without blocking application startup.

Sources: [crates/ai/src/project_context/model.rs:21-25](crates/ai/src/project_context/model.rs#L21-L25), [crates/ai/src/project_context/model.rs:78-104](crates/ai/src/project_context/model.rs#L78-L104), [crates/ai/src/project_context/global_rules.rs:16-44](crates/ai/src/project_context/global_rules.rs#L16-L44), [crates/ai/src/project_context/global_rules.rs:61-90](crates/ai/src/project_context/global_rules.rs#L61-L90)

---

## 5. Skill Providers, Scopes & Parser Engine

Warp AI relies on **Skills**: standalone, file-based instructions (written in Markdown as `SKILL.md`) that give agents special procedures for complex workflows (like adding telemetry, triaging bugs, or managing feature flags).

### Skill Scope Priority
When an agent searches for a skill, Warp resolves them according to the following precedence order:
1.  **Project Scope (`SkillScope::Project`):** Located inside `./.agents/skills/` or similar folders in the active project.
2.  **Home Scope (`SkillScope::Home`):** System-wide skills located in `~/.agents/skills/`.
3.  **Bundled Scope (`SkillScope::Bundled`):** Core skills distributed directly with the Warp installation package.

### Resolving Provider Directories
Each AI provider looks up skills in its own folder structure inside the home or project directory. Precedence is determined by the order of `SKILL_PROVIDER_DEFINITIONS`:

| Precedence | Provider | Skill Directory Path | Default Icon |
| :--- | :--- | :--- | :--- |
| 1 | `Agents` | `.agents/skills` | WarpLogoLight |
| 2 | `Warp` | `.warp/skills` | WarpLogoLight |
| 3 | `Claude` | `.claude/skills` | ClaudeLogo (Salmon color) |
| 4 | `Codex` | `.codex/skills` | OpenAILogo |
| 5 | `Cursor` | `.cursor/skills` | WarpLogoLight |
| 6 | `Gemini` | `.gemini/skills` | GeminiLogo |
| 7 | `Copilot` | `.copilot/skills` | WarpLogoLight |
| 8 | `Droid` | `.factory/skills` | DroidLogo |
| 9 | `Github` | `.github/skills` | WarpLogoLight |
| 10 | `OpenCode` | `.opencode/skills` | OpenCodeLogo |

### Parsing and Validation
Warp reads these folders and extracts directories containing a `SKILL.md` file. It parses YAML front matter for structural fields:
*   `name`: The display name of the skill (falls back to parent folder name).
*   `description`: The descriptive summary (falls back to a truncated version of the first paragraph of the markdown body, capped at `MAX_SKILL_DESCRIPTION_CHARS = 512`).

```rust
// crates/ai/src/skills/parse_skill.rs
pub struct ParsedSkill {
    pub path: PathBuf,
    pub name: String,
    pub description: String,
    pub content: String,
    pub line_range: Option<Range<usize>>,
    pub provider: SkillProvider,
    pub scope: SkillScope,
}
```

Sources: [crates/ai/src/skills/skill_provider.rs:43-66](crates/ai/src/skills/skill_provider.rs#L43-L66), [crates/ai/src/skills/skill_provider.rs:102-147](crates/ai/src/skills/skill_provider.rs#L102-L147), [crates/ai/src/skills/parse_skill.rs:30-52](crates/ai/src/skills/parse_skill.rs#L30-L52), [crates/ai/src/skills/read_skills.rs:13-46](crates/ai/src/skills/read_skills.rs#L13-L46), [crates/ai/src/skills/parser.rs:39-98](crates/ai/src/skills/parser.rs#L39-L98)

---

## 6. Cross-Platform Paths & Persistent Metadata

To keep the agent experience smooth, Warp maintains internal abstractions for filesystems and project states:

### Dynamic Path Translation
Agents often run commands that span different execution environments. `paths.rs` translates native absolute paths dynamically:
*   **Unix vs. Windows Paths:** Detects if the shell runs in a Unix-native system (Linux/Mac) or a Windows environment.
*   **WSL & MSYS2 Conversions:** Automatically converts Windows host paths to WSL Linux paths or MSYS2 Unix-compatible absolute paths, ensuring that tools like `grep` or file read actions don't fail due to backslash/forward slash mismatch.

### Workspace Index Persistence
Warp tracks workspace metrics inside a local SQLite database using `WorkspaceMetadata` to prevent stale indexes from bloating resources. It keeps track of three key events:
1.  `Queried`: When the AI queries the codebase context.
2.  `Modified`: When code changes are made.
3.  `Created`: When the workspace is initially indexed.

If a codebase index is not touched (navigated, modified, or queried) within a designated shelf life, it is marked as expired and purged from the local cache.

Sources: [crates/ai/src/paths.rs:19-32](crates/ai/src/paths.rs#L19-L32), [crates/ai/src/paths.rs:61-72](crates/ai/src/paths.rs#L61-L72), [crates/ai/src/workspace.rs:7-65](crates/ai/src/workspace.rs#L7-L65)

---

## 7. Product Workflows & Compound Engineering Integration

Warp AI integrates with Every's **Compound Engineering (CE)** model. These are represented as high-level, portable product workflows that run independently of any specific LLM provider:

*   **Plan Workflow:** Synthesizes a compact, structured implementation plan outlining the exact changes, non-goals, risk factors, and concrete test cases before editing any files.
*   **QA Review Workflow:** Performs static and logical reviews of requirements, plans, or codebase pages. It searches for unsupported claims, weak citations, logical contradictions, or scope bloat, and provides immediate repair guidance.
*   **Page Shape Workflow:** Organizes technical documentation and compounds team knowledge. It structures articles and guides, classifying them clearly as concept explanations, architectural patterns, workflows, integrations, failure modes, or developer conventions.

> [!NOTE]
> During this technical synthesis, Warp AI utilized Every's bundled Compound Engineering `SKILL.md` snapshots (located under `plugins/compound-engineering/skills/`) to plan, review, and shape this codebase wiki page.

Sources: [crates/ai/src/skills/skill_reference.rs:7-22](crates/ai/src/skills/skill_reference.rs#L7-L22), [.grok-wiki-antigravity-prompt-5111643d.md:41-81](.grok-wiki-antigravity-prompt-5111643d.md#L41-L81)

---

## Summary

Warp AI establishes a robust, highly modular framework for built-in agents and codebase indexing. By combining project-scoped configurations (`WARP.md`), system-wide home configurations (`~/.agents/AGENTS.md`), multi-platform path conversion utilities, and SQLite-backed workspace lifecycles, it equips developers with context-aware, file-based skills. Because the agent harnesses (`oz`, `claude`, `opencode`, `gemini`, `codex`) are decoupled from LLM APIs, Warp offers a completely portable, provider-neutral, and safety-conscious AI engineering workbench.

Sources: [crates/ai/src/lib.rs:1-16](crates/ai/src/lib.rs#L1-L16), [crates/ai/src/skills/skill_provider.rs:102-147](crates/ai/src/skills/skill_provider.rs#L102-L147), [crates/ai/src/agent/orchestration_config.rs:11-24](crates/ai/src/agent/orchestration_config.rs#L11-L24)