Warp & Oz Integration Guide

Evaluation Date: 2026-02-11 Status: Research Complete — Integration Planning Priority: Evaluation / Developer Tooling Enhancement

---

Overview

Warp is an Agentic Development Environment (ADE) — a terminal-first application that replaces your default terminal and integrates AI agents natively. Available on macOS, Windows, and Linux.

Oz is Warp's orchestration platform for cloud agents — the layer that enables running, managing, and scheduling coding agents at scale.

Key Differentiator: Warp is a meta-platform. It can run Claude Code, Codex, and Gemini CLI inside itself, while also providing its own native agents, cloud orchestration, and team collaboration features.

---

Warp Terminal Features

Core Terminal

• Modern terminal with syntax highlighting, rich completions, block-based output
• Native file editor (syntax highlighting, tabs, find-replace — NOT a full IDE)
• Code Review panel for real-time diffs of agent-generated changes
• Warpify — extends Warp features into SSH sessions and subshells (bash/zsh/fish)

Agent Mode

• Switch between command-line and conversational AI
• Local agents for interactive coding assistance
• Full Terminal Use — agents attach to interactive processes (database shells, debuggers)
• Web search — auto-triggered when models deem it useful

Warp Drive (Cloud Knowledge Base)

• Workflows — parameterized commands (YAML format, {{arg}} syntax)
• Prompts — parameterized natural language queries for Agent Mode
• Notebooks — Markdown documentation
• Environment Variables — DOTENV configuration
• Real-time sync, folder hierarchy, team/direct/link sharing
• Import/export (YAML, Markdown, DOTENV)

Benchmarks (Claimed)

• #1 on Terminal-Bench (52%)
• 75.8% on SWE-bench Verified

---

Oz Platform Architecture

Three Layers

Two Agent Types

Local Agents (Interactive):

• Run inside the Warp terminal
• Real-time natural language interaction
• Write/edit code, debug, run commands
• Error recovery (auto-retry with adjustments)
• Full Terminal Use — see live terminal buffer, write to PTY

Cloud Agents (Autonomous, Beta):

• Run in background on Oz cloud or self-hosted infrastructure
• Triggered by events, schedules, or integrations
• Parallel execution at scale
• Team observability through session sharing
• Can create PRs, manage issues, provide live progress updates

Cloud Agent Triggers

Cloud Agent Environments

• Define Docker image (glibc-based required — Debian, Ubuntu; Alpine NOT supported)
• Clone GitHub repositories into execution context
• Setup commands (sequential, idempotent)
• Shared across triggers — same env for Slack, Linear, CLI invocations

Self-Hosting (Enterprise Only)

• Run Oz workers on own infrastructure via Docker
• Oz orchestrator still manages lifecycle, observability, management
• Requires: compute machine (Linux recommended), Docker, outbound internet
• Worker: docker run warpdotdev/oz-agent-worker --worker-id "my-worker"
• Route tasks via --host parameter

---

Agent Capabilities

Skills

• Markdown files with YAML frontmatter (.agents/skills/SKILL.md)
• Auto-discovered based on working directory
• Invoked via natural language or /{skill-name} slash commands
• Project-level (.agents/skills/) or global (~/)
• Cross-compatible: Reads .claude/skills/ directories too

Rules

• Reusable guidelines shaping agent behavior
• Two tiers: Global rules + Project rules (AGENTS.md / WARP.md)
• Precedence: Subdirectory > Root > Global
• Cross-compatible: Recognizes CLAUDE.md, .cursorrules, GEMINI.md, .clinerules, .windsurfrules, .github/copilot-instructions.md

Agent Profiles & Permissions

• Tiered autonomy: Let agent decide / Always prompt / Always allow / Never
• Named profiles (e.g., "YOLO mode" for personal, "Prod mode" for restricted)
• Switchable per context

Model Choice

• OpenAI: GPT-5.2, GPT-5.1, GPT-5 variants
• Anthropic: Claude Opus, Sonnet, Haiku
• Google: Gemini 3 Pro, 2.5 Pro
• Fireworks AI: GLM 4.6
• 3 Auto modes (cost, speed, quality)
• Fallback system for provider outages
• BYOK: Bring your own API keys (OpenAI, Anthropic, Google)

MCP (Model Context Protocol)

• CLI servers (Warp manages startup) or HTTP/SSE servers (remote endpoints)
• Auth: env vars, OAuth browser flow, custom headers
• Pre-built: GitHub, Sentry, Grafana, Linear, Chroma, Figma, Slack, Atlassian, Notion
• Team sharing with auto env-var scrubbing

Planning

• /plan slash command or natural language
• Structured plans with version history
• Execute full plan or specific sections
• Auto-save to Warp Drive, exportable as Markdown

Computer Use (Experimental)

• GUI interaction in isolated cloud sandboxes
• Screenshots, clicks, typing, keyboard shortcuts
• Uses Claude Opus 4.6
• Primary use case: UI testing loop

Codebase Context

• Auto-indexes Git repos on open
• Respects .gitignore, .warpindexingignore, .cursorignore
• 5,000+ files per codebase (higher on paid tiers)
• Embeddings index stays local (never stored on Warp servers)
• Does NOT work in SSH/WSL sessions

---

Integration Mapping: BlueFly Agent Platform ↔ Warp/Oz

Direct Correspondence

What Oz Adds (Gaps in Current Platform)

1. Slack/Linear Triggers — @Oz in Slack triggers cloud agent. Current path is @bluefly-platform in GitLab only. Oz extends to chat-based triggers.
2. Parallel Cloud Agent Spawning — Programmatic N agents via CLI/API/SDK. BuildKit swarm runs locally; Oz runs in cloud containers.
3. Session Sharing — Auto-generated shareable links with full audit trail. agent-tracer handles observability but lacks live interactive sharing.
4. Self-Hosted Workers — Docker workers on Oracle Cloud VM or NAS. Keeps execution on-prem while Oz handles orchestration.
5. Computer Use — GUI interaction for UI testing of Drupal modules in sandboxed environments.
6. GitHub Actions Integration — Trigger agents from CI/CD (gitlab_components could integrate).

What BlueFly Has That's Superior

---

Architecture Integration

                    HUMAN DEVELOPMENT LAYER
                    ┌─────────────────────────────┐
                    │  Warp Terminal (M4/M3)       │
                    │  ├─ Local Agents (interactive)│
                    │  ├─ MCP Servers (portable)    │
                    │  ├─ AGENTS.md / CLAUDE.md     │
                    │  └─ Codebase Context (local)  │
                    └──────────┬──────────────────┘
                               │
              ┌────────────────┼────────────────┐
              ▼                ▼                ▼
    ┌─────────────┐  ┌──────────────┐  ┌──────────────┐
    │ Oz Cloud    │  │ GitLab CI/CD │  │ GitLab Duo   │
    │ (triggers)  │  │ (pipelines)  │  │ (@bluefly)   │
    │ Slack/Linear│  │ gitlab_comps │  │ gitlab_ossa  │
    │ Cron/API    │  │              │  │              │
    └──────┬──────┘  └──────┬───────┘  └──────┬───────┘
           │                │                 │
           └────────────────┼─────────────────┘
                            ▼
              ┌─────────────────────────────┐
              │  OSSA Agent Platform         │
              │  ├─ agent-mesh (coordination)│
              │  ├─ agent-router (LLM)       │
              │  ├─ agent-protocol (MCP)     │
              │  ├─ compliance-engine (Cedar) │
              │  └─ agent-brain (memory)     │
              └──────────┬──────────────────┘
                         ▼
              ┌─────────────────────────────┐
              │  Execution Environments      │
              │  ├─ Oracle Cloud (K8s/kagent) │
              │  ├─ Oz Self-Hosted Workers   │
              │  ├─ GitLab Workspaces        │
              │  └─ Vast.ai (GPU)            │
              └─────────────────────────────┘

---

Implementation Roadmap

Phase 1: Developer Experience (Immediate — No Cost)

Goal: Replace default terminal with Warp on M4/M3 workstations.

• Install Warp on M4 (primary) and M3 (secondary)
• Configure BYOK with existing ~/.tokens/anthropic and ~/.tokens/openai
• Verify AGENTS.md and CLAUDE.md are auto-discovered by Warp rules
• Port existing .claude/skills/ to .agents/skills/ format (Warp reads both)
• Configure existing MCP servers in Warp settings
• Test Warp Codebase Context indexing across key repos (agent-buildkit, platform-agents, etc.)
• Set up Agent Profiles: "Dev" (permissive), "Prod" (restricted), "Drupal" (PHP-aware)
• Evaluate Warp Drive for sharing workflows/prompts across M4/M3

Cost: $0 (Free tier) or $20/mo (Build for 1,500 credits + BYOK)

Phase 2: Cloud Agent Triggers (Short-term — 2-4 weeks)

Goal: Extend agent triggers beyond GitLab to Slack and scheduled tasks.

• Set up Oz Slack integration for on-demand agent requests in team channels
• Create Oz Environments for key repos (agent-buildkit, platform-agents, compliance-engine)
• Map OSSA stateless workers to Oz scheduled agents:
  • documentation-aggregator → daily wiki sync cron
  • vulnerability-scanner → nightly security scan cron
  • cost-intelligence-monitor → 8-hour cost analysis cron
• Test Oz CLI integration: oz run --prompt "..." --env production
• Evaluate self-hosted workers on Oracle Cloud VM (Enterprise plan required)

Cost: Build plan ($20/mo) + Oz compute credits

Phase 3: Orchestration Bridge (Medium-term — 1-2 months)

Goal: Bridge Oz triggers into the OSSA agent platform.

• Build buildkit oz:trigger command wrapping Oz CLI
• Route Oz cloud agent results through agent-mesh for OSSA compliance validation
• Feed Oz session data into agent-tracer for unified observability
• Add Oz API/SDK integration to workflow-engine for external trigger support
• Create ai_agents_warp Drupal module for Oz session management
• Map Warp Agent Profiles to OSSA access tiers:
  • Warp "Dev" → OSSA tier_3_full_access
  • Warp "Prod" → OSSA tier_1_read
  • Warp "Review" → OSSA tier_2_write_limited

Cost: Enterprise plan (custom) if self-hosting needed

Phase 4: Full Platform Integration (Long-term)

Goal: Oz as an additional execution environment alongside Oracle K8s and GitLab Workspaces.

• Register Oz cloud agents in platform-agents registry
• Use Oz Computer Use for automated Drupal UI testing
• Implement Oz API as trigger source in agent-mesh gateway
• Create gitlab_components CI template for Oz agent dispatch
• Unified dashboard: agent-tracer + Oz session sharing

---

Pricing

1 credit = 1 prompt submission. Cloud agents consume credits for AI + compute.

Reload Credits: ~40-50% cheaper than old overages, roll over monthly (12-month validity), $10-$100 increments.

Recommendation: Start with Build ($20/mo) + BYOK. Existing Anthropic/OpenAI keys mean you only pay Warp for orchestration, not model costs.

---

Comparison: Warp/Oz vs Claude Code

Bottom Line: They complement each other. Warp is the terminal + orchestration surface. Claude Code is the most capable individual coding agent. Run Claude Code inside Warp for best of both worlds.

---

Key Risks & Considerations

• Cloud agents are still in beta
• Self-hosting requires Enterprise plan (custom pricing — could be expensive)
• Alpine Docker images not supported (must use glibc-based)
• Codebase context doesn't work in SSH/WSL
• Computer Use is experimental and sandboxed only
• Credit-based pricing requires usage monitoring
• Oz is GitHub-centric (not GitLab) — integration may need adapter work
• No native GitLab CI/CD trigger (GitHub Actions only currently)

---

References

• Warp Documentation
• Oz Blog Announcement
• Warp Pricing
• Agent Platform Docs
• Agents in Warp
• Agent Capabilities
• Cloud Agents
• MCP Support
• Skills
• Rules
• Warp Code Introduction