This is the full developer documentation for Warp # Warp products and getting started Canonical page: [/](https://docs.warp.dev/) > Warp combines a modern terminal, coding agents, cloud automation, and software factories for teams that build and ship software. Warp is an [open-source](https://github.com/warpdotdev/warp) **Agentic Development Environment** that brings together terminal work, coding agents, and cloud automation. With Warp, you can work in a desktop terminal, use the Warp Agent in a local checkout or from any terminal, automate background work in the cloud, and run repeatable team workflows with Warp Factories. ## Warp [Section titled “Warp”](#warp) With the Warp desktop terminal, you can run commands, edit code, and work with agents in a local checkout. * [Modern terminal editing](/terminal/editor/) - Edit commands, navigate blocks, manage tabs, and customize your terminal. * [Code](/code/overview/) - Review agent changes and edit files alongside your terminal. * [Agents](/agents/) - Start and steer coding agents in the Warp app. ## Warp Agent [Section titled “Warp Agent”](#warp-agent) The Warp Agent helps you investigate issues, edit code, run commands, and complete multi-step work. Use it in the Warp terminal or from the [Warp Agent CLI](/agents/cli/), which runs the same agent in any terminal. ## Automation Platform [Section titled “”](#varswarp_automation_platform) The Automation Platform runs cloud agents from triggers, schedules, integrations, and APIs. Use it for background work such as issue triage, pull request review, and recurring maintenance. * [Cloud agents](/platform/) - Run background agent work in the cloud. * [The Automation Platform](/platform/overview/) - Configure environments, integrations, orchestration, and shared agent settings. ## Warp Factories [Section titled “Warp Factories”](#warp-factories) Warp Factories is available in Early Access. A factory turns incoming engineering work into a repeatable, multi-stage workflow with specialized agents, review points, and measurable outcomes. * [Warp Factories overview](/factories/) - Learn how a factory receives, routes, and tracks work. * [Factory quickstart](/factories/quickstart/) - Create a factory and send it its first work item. ## How the products work together [Section titled “How the products work together”](#how-the-products-work-together) Start and steer interactive work in the Warp terminal with the Warp Agent. For work that starts from a schedule, integration, or API, the Automation Platform runs agents in the cloud. Warp Factories builds on the Automation Platform to turn incoming team work into a repeatable workflow with specialized agents and review stages. ## Related pages [Section titled “Related pages”](#related-pages) * [Install Warp](/quickstart/) - Set up Warp and start coding. * [Start an agent conversation](/agents/) - Work with the Warp Agent in a local checkout. * [Run cloud agents](/platform/quickstart/) - Set up background automation. * [Set up a factory](/factories/quickstart/) - Route engineering work through Warp Factories. * [Privacy and security](/support-and-community/privacy-and-security/privacy/) - Review Warp’s data handling, privacy, and security practices. # Page not found Canonical page: [/404/](https://docs.warp.dev/404/) > The page you are looking for does not exist or has moved. The page you are looking for does not exist or has been moved. Use the search or navigation to find what you need. [Go to the docs home](/) # Agents overview Canonical page: [/agents/](https://docs.warp.dev/agents/) > The Warp Agent runs commands in a real terminal, carries your context across every surface, and works interactively or in the background. The **Warp Agent** is Warp’s built-in coding agent. It works through multi-step tasks on its own, running commands in a real terminal and using the output to decide what to do next. You stay in the loop, approving actions and reviewing diffs before anything lands. This page covers where to run the agent, the third-party CLI agents Warp supports, and the [Automation Platform](/platform/overview/), which runs and coordinates agents at scale. *** ## Where to use the Warp Agent [Section titled “Where to use the Warp Agent”](#where-to-use-the-warp-agent) You reach the same agent three ways. Which one you pick depends on where you’re working, not on what the agent can do. * **In the Warp app** - The full experience, with code review, agent management, and the terminal beside your conversation. * [**In any terminal, with the Warp Agent CLI**](/agents/cli/) - Run the `warp` command to start a conversation in any terminal emulator, over SSH, or on a machine where the Warp app isn’t installed. * [**In the cloud, as a cloud agent**](/platform/) - Run the agent in the background from a trigger, a schedule, or an integration, without keeping a session open. Cloud agents run on the [Automation Platform](/platform/overview/), Warp’s platform for environments, triggers, orchestration, and observability. *** ## What makes the Warp Agent different [Section titled “What makes the Warp Agent different”](#what-makes-the-warp-agent-different) * **It works in a real terminal** - The agent runs shell commands, reads live output, and drives interactive programs like REPLs, database shells, and full-screen apps. See [Full terminal use](/agents/capabilities/full-terminal-use/). * **Your context follows it everywhere** - [Rules](/agents/capabilities/rules/), [Skills](/agents/capabilities/skills/), [MCP servers](/agents/capabilities/mcp/), and [Codebase Context](/agents/capabilities/codebase-context/) apply the same way in the app, the CLI, and the cloud. * **Interactive or delegated, and you can switch mid-task** - Steer a conversation while it runs, or [hand it off](/platform/handoff/) to a cloud agent and pick it back up locally when it’s done. * **You approve before anything lands** - The agent asks before it runs commands, edits files, or calls MCP servers. Set how much it does on its own with [Agent Profiles and permissions](/agents/capabilities/agent-profiles-permissions/), and review generated changes in [interactive code review](/agents/local-agents/interactive-code-review/). * **Many agents at once** - Run several conversations in parallel and track them in the [Agent Management Panel](/platform/managing-cloud-agents/), or use [orchestration](/platform/orchestration/) to have a parent agent spawn and coordinate children.  **Try this prompt** — [*open in Warp*](https://app.warp.dev/drive/prompt/Clone-and-install-Warps-themes-repository-PkK9Zw16SCD3JKzOUoGuj4) ```text Detect my current operating system. Based on that, navigate to the appropriate Warp themes directory (e.g. ~/.warp/ on macOS). Then, clone the official Warp themes repository using SSH (git@github.com:warpdotdev/themes.git) into that directory, following the structure and instructions provided in the repo's README. If SSH does not work, try HTTPS (https://github.com/warpdotdev/themes.git) or via the GitHub CLI (gh repo clone warpdotdev/themes). ``` *** ## Third-party CLI agents [Section titled “Third-party CLI agents”](#third-party-cli-agents) Separately from the Warp Agent, Warp gives third-party CLI coding agents first-class support. Run Claude Code, Codex, OpenCode, and others inside Warp and get rich input, agent notifications, inline code review, and remote session control. → [Learn about third-party CLI agents](/agents/cli-agents/overview/) *** ## The platform behind the agent [Section titled “The platform behind the agent”](#the-platform-behind-the-agent) The [**Automation Platform**](/platform/overview/) is Warp’s programmable system for running and coordinating agents at scale. It provides the environments, triggers, integrations, orchestration, and observability that cloud agents run on, along with a CLI, API, and SDK for driving agents programmatically. To automate an entire workflow rather than a single task, use [Warp Factories](/factories/). Built on the Automation Platform, a factory runs a team of cloud agents that triage, spec, implement, review, and verify work. The Automation Platform tab covers the platform in full. *** ## Privacy and security [Section titled “Privacy and security”](#privacy-and-security) Warp is **SOC 2 compliant** and has **Zero Data Retention** policies with all contracted LLM providers. No customer AI data is retained, stored, or used for training. You can disable Warp’s AI features entirely in **Settings** > **Agents** > **Warp Agent**. → [Read more about data privacy](https://www.warp.dev/privacy) *** ## Where to go next [Section titled “Where to go next”](#where-to-go-next) * [**Interacting with agents**](/agents/local-agents/interacting-with-agents/) - Conversations, context, code review, and voice in the Warp app. * [**Agent capabilities**](/agents/capabilities/) - Planning, skills, rules, MCP servers, task lists, and model choice. * [**Warp Agent CLI quickstart**](/agents/cli/quickstart/) - Install the CLI and run your first conversation. * [**Cloud agents quickstart**](/platform/quickstart/) - Run your first agent in the cloud, or put one on a [schedule](/platform/triggers/scheduled-agents/). For a comparison of triggers across schedules, Slack, Linear, GitHub Actions, the CLI, and the API, see [Run unattended agents](/guides/agent-workflows/how-to-run-unattended-agents/). * [**Agent FAQs**](/agents/getting-started/faqs/) - Models, privacy, credits, and limits. *** ## Open source [Section titled “Open source”](#open-source) Warp’s client is open source under [AGPL v3](https://github.com/warpdotdev/warp/blob/master/LICENSE-AGPL), so the editor and terminal that host your agents are fully auditable. See [Contributing to Warp](/support-and-community/community/contributing/). # Agent Memory (Research Preview) Canonical page: [/agents/agent-memory/](https://docs.warp.dev/agents/agent-memory/) > Agent Memory gives agents in Warp persistent memory across supported harnesses, including the Warp Agent, Claude Code, and Codex. Caution Agent Memory is in **research preview** and is enabled per team for design partners. [Join the waitlist](https://www.warp.dev/oz/agent-memory#waitlist) to request access for your team. Agent Memory is a persistent memory system that lives on Warp and is shared across every supported [agent harness](/platform/harnesses/), including the built-in Warp Agent, Claude Code, Codex, and others as they’re added. Agents read from and write to this memory system as they run, so durable facts, decisions, and outcomes from one conversation are available to the next — regardless of which harness, machine, or teammate triggers the work. Memory creation and retrieval are asynchronous and run in the background, so they don’t consume tokens or add latency to the active task. Watch this short preview to see Agent Memory in context.  [Join the Agent Memory waitlist](https://www.warp.dev/oz/agent-memory#waitlist). ## Key features [Section titled “Key features”](#key-features) * **Cross-harness memory** - One memory system is shared across the Warp Agent, Claude Code, Codex, and other harnesses as they’re added. Third-party harnesses are covered when they run as cloud agents. * **Both local and cloud agents** - Supports interactive local agents in Warp and background cloud agents. * **Asynchronous by design** - Memory creation runs after a conversation ends. Retrieval runs in the background during a run. Neither consumes tokens or adds latency to the active task. * **Automatic memory creation from conversations** - When a conversation ends, Warp extracts durable facts, learnings, and outcomes and writes them as memories. New knowledge merges with existing memories or supersedes them on conflict. * **Shareable stores** - Memory is organized into stores. A store can be attached to one or more agents, so the same knowledge is available wherever those agents run. To share knowledge across a team, attach a store to an agent the whole team uses. * **Auto-memory for new agents** - New agents get a dedicated, agent-owned memory store by default, so they start building long-term memory from their first run. You can turn this off when you create the agent. * **Per-agent access and instructions** - Attach stores to specific agents with read-only or read-write access. Per-store instructions tell each agent how and when to use the store. * **Traceability** - Each memory records where it came from, so teams can trace a memory back to its source. * **Auditability** - Every change to a memory is recorded so teams can inspect how a memory has changed over time. ## Where Agent Memory runs [Section titled “Where Agent Memory runs”](#where-agent-memory-runs) Agent Memory is part of Warp. Storage, memory creation, and retrieval all run on Warp alongside your agents. The same memory is accessible from any agent you run in Warp: * The local Warp Agent. * [Cloud agents](/platform/) triggered from the CLI, web app, [schedules](/platform/triggers/scheduled-agents/), or [integrations](/platform/integrations/). * Third-party harnesses running as cloud agents: Claude Code, Codex, and others as they’re added. (Running third-party harnesses locally isn’t supported during the research preview.) Memory stays bound to its owner (a user, an agent, or a team), independent of which harness reads or writes. ## Memory stores [Section titled “Memory stores”](#memory-stores) A memory store is a collection of memories. Stores are used by attaching them to agents: a store can be attached to a single agent or to several agents that need the same knowledge. To make knowledge available across a team, attach a store to an agent the whole team uses; there’s no separate step for sharing a store with individual teammates. Stores differ by who owns them: * **Personal stores** - Owned by a user. Hold memories about preferences, working notes, and individual patterns. * **Agent stores** - Owned by an agent. A new agent gets one by default as its auto-memory store (see below). * **Team stores** - Owned by a team. Hold shared knowledge like deployment runbooks, code review conventions, or on-call procedures. Attach a team store to any agent the team uses so everyone’s work draws on the same knowledge. Teams can use multiple stores to keep contexts separate, and attach the same store to several agents when needed. For example, a code review agent can use a dedicated store of review patterns, while a repo-specific store of architectural decisions is attached to both the code review agent and a Sentry triage agent so both reason about the same codebase. ### Auto-memory for new agents [Section titled “Auto-memory for new agents”](#auto-memory-for-new-agents) When you create an agent in the Oz web app, **Auto-memory** is on by default. With it enabled, Warp creates a dedicated memory store owned by that agent and uses it as the agent’s default long-term memory: the agent reads relevant memories before it acts and writes durable facts, decisions, and preferences for future runs. Each agent has a single auto-memory store. Auto-memory is different from automatic memory creation from conversations, described below: auto-memory is the store an agent gets by default, while automatic memory creation from conversations is how memories are written to a store after a conversation ends. You can turn Auto-memory off when you create the agent, and you can attach existing team stores at the same time, each with its own access level and instructions. ## Automatic memory creation from conversations [Section titled “Automatic memory creation from conversations”](#automatic-memory-creation-from-conversations) When a conversation finishes, Warp extracts durable facts, learnings, and outcomes from the transcript and writes them as memories. Memory creation runs in the background after the conversation ends, so it doesn’t consume tokens or add latency during that run. * **Memories evolve over time** - Agents update and supersede their own memories as new information arrives, including to resolve contradictions with prior memories. You can also explicitly ask an agent to remember something during a conversation. Warp saves that memory to the appropriate store. ## How agents use memory [Section titled “How agents use memory”](#how-agents-use-memory) When an agent starts a task, Warp searches the stores the agent can access for relevant memories and injects them as context. The search runs in the background, so the agent only sees the memories returned. Agents can also retrieve additional memories on demand mid-conversation when they determine it’s relevant, similar to how they consult [Rules](/agents/capabilities/rules/) or [Codebase Context](/agents/capabilities/codebase-context/). You don’t need to write retrieval queries or pre-load memory. ## Attaching memory to your agents [Section titled “Attaching memory to your agents”](#attaching-memory-to-your-agents) Attach stores to agents with read-only or read-write access. Each attachment includes per-store instructions that tell the agent how and when to use the store. For example, use instructions like “Reference this store for team naming conventions” or “Write a new memory after each successful deployment.” Instructions are required on every attachment so the agent knows the purpose of each store. ## Coming soon [Section titled “Coming soon”](#coming-soon) These capabilities aren’t part of the research preview yet, but they’re on the way: * **Programmatic API access** - Read and manage memories and stores through the [Warp Platform API](/factories/api-and-sdk/), in addition to managing them in the Oz web app. * **Self-hosting support** - Run Agent Memory on a [self-hosted Automation Platform](/factories/self-hosting/) instance to meet security, privacy, and compliance requirements. ## Join the waitlist [Section titled “Join the waitlist”](#join-the-waitlist) Agent Memory is rolling out to design partner teams during research preview. [Join the waitlist](https://www.warp.dev/oz/agent-memory#waitlist) to request access. ## Related pages [Section titled “Related pages”](#related-pages) * [Harnesses in the Automation Platform](/platform/harnesses/) - Run Warp Agent, Claude Code, or Codex as cloud agents with shared platform features. * [Codebase Context](/agents/capabilities/codebase-context/) - Let agents understand your codebase through semantic indexing. * [Rules](/agents/capabilities/rules/) - Define global and project-level guidelines that shape agent behavior. * [Skills](/agents/capabilities/skills/) - Reusable, scoped instructions that teach agents how to perform specific tasks. * [Agent profiles and permissions](/agents/capabilities/agent-profiles-permissions/) - Control what permissions and autonomy agents have. # Capabilities overview Canonical page: [/agents/capabilities/](https://docs.warp.dev/agents/capabilities/) > Core capabilities and configuration options that shape how agents behave, what context they have access to, and how they execute tasks. Agent capabilities are the core building blocks that define how agents operate, including the context sources agents can access, the rules that guide their behavior, the tools they can use, and the models they run on. Configure these capabilities to match your workflows and preferences. ## Capabilities in this section [Section titled “Capabilities in this section”](#capabilities-in-this-section) * [Slash Commands](/agents/capabilities/slash-commands/) - Quick actions and saved prompts accessible by typing `/` in Agent Mode. * [Skills](/agents/capabilities/skills/) - Reusable, scoped instructions that teach agents how to perform specific tasks in your codebase. * [Planning](/agents/capabilities/planning/) - Turn agent requests into organized, editable plans that execute step-by-step with full visibility. * [Task Lists](/agents/capabilities/task-lists/) - Track complex workflows with automatic task lists that update progress in real time. * [Rules](/agents/capabilities/rules/) - Define global and project-level guidelines that shape agent behavior and responses. * [Full Terminal Use](/agents/capabilities/full-terminal-use/) - Let the agent drive interactive terminal apps, seeing live output and running commands. * [Computer Use](/agents/capabilities/computer-use/) - Let agents interact with desktop environments by taking screenshots, clicking, typing, and controlling the GUI. * [MCP](/agents/capabilities/mcp/) - Connect external data sources and tools to agents via the Model Context Protocol. * [Codebase Context](/agents/capabilities/codebase-context/) - Let agents understand your codebase through semantic indexing of your Git-tracked files. * [Agent Profiles & Permissions](/agents/capabilities/agent-profiles-permissions/) - Control what permissions and autonomy agents have to run commands and apply changes. * [Web Search](/agents/capabilities/web-search/) - Allow agents to search the web for up-to-date information. ## Related [Section titled “Related”](#related) * [Inference & providers](/agents/inference/model-choice/) - Pick the model that powers your agents, bring your own API key, or connect a custom inference endpoint. * [Agents overview](/agents/) - What the Warp Agent does, how to control it, and where to run it. # Agent Notifications Canonical page: [/agents/capabilities/agent-notifications/](https://docs.warp.dev/agents/capabilities/agent-notifications/) > Warp surfaces notifications from coding agents, both in-app and via desktop alerts, so you know exactly when an agent needs your attention. Warp delivers notifications from any supported coding agent so you always know when an agent finishes a task, encounters an error, or needs your input. Notifications work whether you’re in a different tab or a different app.  ## Notification types [Section titled “Notification types”](#notification-types) Warp categorizes agent notifications by what happened: * **Complete** - the agent finished its task successfully. You can review the output and continue working. * **Request** - the agent is blocked and needs your input. This includes command approval, permission requests, and idle prompts where the agent is waiting for you. * **Error** - the agent encountered an error that requires your attention. ## In-app notifications [Section titled “In-app notifications”](#in-app-notifications) When you’re working in Warp but not looking at the agent’s tab, Warp provides several visual signals. ### Toast notifications [Section titled “Toast notifications”](#toast-notifications) Floating toast notifications appear in the corner of the Warp window when an agent in another tab needs attention. Toasts auto-dismiss after a few seconds. Hover over a toast to pause the timer, or click it to jump directly to the agent’s session. Up to two toasts are visible at a time. If additional notifications arrive, the oldest toast is replaced.  Agent task completion notification. ### Notification mailbox [Section titled “Notification mailbox”](#notification-mailbox) The notification mailbox is a sidebar panel that collects all agent notifications in one place. Open it from the bell icon in the top-right corner of Warp.  Agent notification mailbox. The mailbox includes: * **Filter tabs** - switch between **All tabs**, **Unread**, and **Errors** to find what needs attention. If there are no unreads or errors, those filters don’t appear. * **Mark all as read** - clear all unread indicators at once * **Click to navigate** - click any notification to jump directly to that agent’s tab **Keyboard shortcuts:** * `↑` / `↓` - select previous / next notification * `Enter` - open the selected notification’s session * `Shift+Tab` - cycle through filter tabs * `Esc` - close the mailbox ### Tab status indicators [Section titled “Tab status indicators”](#tab-status-indicators) Each tab displays an icon reflecting its agent’s current state — working, blocked, completed, or errored. Tabs with unread notifications show an attention badge so you can spot which sessions need action, even with many tabs open. Notifications are automatically marked as read when you navigate to the agent’s tab. ## Desktop notifications [Section titled “Desktop notifications”](#desktop-notifications) When Warp is in the background or minimized, agent notifications are delivered as native system-level desktop alerts. This ensures you’re aware of agent activity even while working in other apps. Note Desktop notifications require system permissions. If you’re not receiving them, check your OS notification settings for Warp. See [Desktop Notifications](/terminal/more-features/notifications/) for setup and troubleshooting. ## Supported agents [Section titled “Supported agents”](#supported-agents) Agent notifications currently work with: * **Warp Agent** - supported out of the box. No setup required. * **Claude Code** - full support via notification plugin. * **Codex** - full support via native Codex configuration. * **OpenCode** - full support via notification plugin. ## Setting up notifications [Section titled “Setting up notifications”](#setting-up-notifications) For the **Warp Agent**, notifications work out of the box — no setup needed. For **third-party CLI agents**, each agent requires a one-time setup. The process varies by agent: * **Claude Code** - one-click auto-install via a chip in Warp, or manual plugin commands. See [Claude Code setup](/agents/cli-agents/claude-code/#setting-up-notifications). * **Codex** - add `notification_condition = "always"` under `[tui]` in `~/.codex/config.toml`, then restart Codex. See [Codex setup](/agents/cli-agents/codex/#setting-up-notifications). * **OpenCode** - add `"@warp-dot-dev/opencode-warp"` to the `plugin` array in your OpenCode config. See [OpenCode setup](/agents/cli-agents/opencode/#setting-up-notifications).  Notification plugin install chip. If auto-install doesn’t work or you’re running an agent over SSH, Warp displays an installation-instructions chip in the terminal with setup steps you can follow directly. ## Notifications in orchestrated runs [Section titled “Notifications in orchestrated runs”](#notifications-in-orchestrated-runs) In a [multi-agent orchestration](/platform/orchestration/), the parent agent and each child agent are separate conversations. Today, in-app notifications fire on the parent’s conversation only: child agent conversations are excluded from the toast stream and the notification mailbox so the mailbox doesn’t get cluttered with per-child status churn. That means: * **Toasts and the mailbox** - watch the parent’s conversation for `Complete`, `Request`, and `Error` notifications. * **Per-child state** - use the orchestration pill bar above the agent view header (in the Warp app) or the parent’s **Sub-agents** tab on the [Runs page](https://oz.warp.dev/runs) (in the Oz web app) to see each child’s live status. Both surfaces update as children transition through `INPROGRESS`, `SUCCEEDED`, `BLOCKED`, `FAILED`, `ERROR`, and `CANCELLED`. * **Blocked children** - if a child blocks on user input (for example, a command approval request), open that child from the pill bar to resolve the block. The parent’s transcript also reflects the child’s `BLOCKED` state so the parent can wait, send a follow-up, or cancel the child. ## Related pages [Section titled “Related pages”](#related-pages) * [Desktop Notifications](/terminal/more-features/notifications/) - configure system-level notification permissions and troubleshoot delivery * [Managing Agents](/platform/managing-cloud-agents/) - monitor all agent conversations, filter by status, and inspect sessions * [Multi-agent orchestration](/platform/orchestration/) - parent/child model, run state transitions, and the orchestration pill bar * [Third-party CLI agents](/agents/cli-agents/overview/) - overview of supported CLI agents and Warp features * [Claude Code](/agents/cli-agents/claude-code/) - setup and notification plugin installation * [Codex](/agents/cli-agents/codex/) - setup and notification configuration * [OpenCode](/agents/cli-agents/opencode/) - setup and notification plugin installation # Profiles & Permissions Canonical page: [/agents/capabilities/agent-profiles-permissions/](https://docs.warp.dev/agents/capabilities/agent-profiles-permissions/) > Agent Profiles let you customize how your Agent behaves, from its models and autonomy to the tools and permissions it can use. Agent Profiles let you configure how agents behave in different situations, including autonomy level, base model, tool access, and command permissions. Create multiple profiles for different workflows, control which commands run automatically, and set MCP server access rules per profile. ## Agent Profiles [Section titled “Agent Profiles”](#agent-profiles) Agent Profiles let you configure how your Agent behaves in different situations. Each profile defines the Agent’s autonomy, base models, and tool access. You can create multiple profiles and edit them directly in **Settings** > **Agents** > **Profiles**. * **Default profile**: Every user starts with a default profile, you can edit it at any time, and new profiles will copy its settings as a starting point. * **Other profiles**: Set up different profiles for different workflows (e.g., “Safe & cautious”, “YOLO mode”, etc.). Manage them in the Profiles settings menu.  Agent Profile settings. **In each Agent Profile, you can configure:** * The name of the profile * **Base model**: The core engine for your Agent. It handles most interactions and invokes other models when needed (e.g. for code generation). This model is also used for [Planning](/agents/capabilities/planning/) by default, though you can configure a separate planning model. * Agent autonomy and permissions  Editing an Agent Profile. ## Agent Permissions [Section titled “Agent Permissions”](#agent-permissions) Agent Permissions let you define how your Agent in a specific Profile operates — control its autonomy, choose what tools or MCP servers it can access, and set when it should act independently or ask for approval. Caution **Still getting approval prompts?** If the Agent keeps asking for permission to run certain commands (like `curl`, `rm`, or `wget`) even though you’ve set permissions to “Always allow,” check your **Command denylist** in **Settings** > **Agents** > **Profiles**. The denylist takes precedence over your other permission settings. Remove commands from the denylist to allow them to auto-execute, or use [Run until completion](#run-until-completion) to bypass the denylist for the current task. You can control how much autonomy the Agent has when performing different types of actions under **Settings** > **Agents** > **Profiles** > **Permissions**. Agent permission types: * Apply code diffs * Read files * Create plans * Execute commands * Interact with running commands (via [Full Terminal Use](/agents/capabilities/full-terminal-use/)) * Ask clarifying questions (via [Agent questions](/agents/local-agents/interacting-with-agents/agent-questions/))  **Each permission has different levels of autonomy:** | Autonomy level | Description | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Agent Decides | Agent will act autonomously when it’s confident, but prompt for approval when uncertain. This option balances speed with control, allowing the Agent to go ahead with common workflows while keeping you in the loop for more complex or risky steps. | | Always ask | Agent will request explicit user approval before taking any action. Choose this for sensitive actions. | | Always allow | Agent will perform the action without ever requesting explicit confirmation. Use this for tasks you fully trust the Agent to handle on its own. | | Never | Agent will not ever take the action (i.e. Create plans). | Note For **Apply code diffs**, `Agent decides` currently behaves the same as `Always ask` — the Agent always prompts you to review diffs before applying them. Only `Always allow` skips the review prompt. When all Agent permissions are set to **Always allow**, the Agent gains full autonomy (“YOLO mode”); however, any denylist rules will still override these settings. ### Ask questions [Section titled “Ask questions”](#ask-questions) The **Ask questions** permission controls whether the Agent can pause a conversation to ask you clarifying questions before continuing. The available settings are: * **Never ask** - The Agent does not pause for clarifying questions and continues with its best judgment. * **Ask unless auto-approve** - The Agent can ask during normal conversations, but questions are skipped while auto-approve is on. * **Always ask** - The Agent can pause for your answer even when auto-approve is on. For the full user flow, see [Agent questions](/agents/local-agents/interacting-with-agents/agent-questions/). ### Command allowlist [Section titled “Command allowlist”](#command-allowlist) The Agent lets you define an allowlist of commands that run automatically without confirmation. It’s empty by default, but users often add read-only commands such as: * `which .*` - Find executable locations * `ls(\s.*)?` - List directory contents * `grep(\s.*)?` - Search file contents * `find .*` - Search for files * `echo(\s.*)?` - Print text output You can add your own regular expressions to this list in **Settings** > **Agents** > **Profiles** > **Command allowlist**. Commands in the allowlist will always auto-execute, even if they are not read-only operations.  Command allowlist and denylists as part of an Agent Profile. ### Command denylist [Section titled “Command denylist”](#command-denylist) For safety, the Agent always prompts for confirmation before executing potentially risky commands. The default denylist includes several examples, such as: * `wget(\s.*)?` - Network downloads * `curl(\s.*)?` - Network requests * `rm(\s.*)?` - File deletion * `eval(\s.*)?` - Shell code execution The denylist takes precedence over both the allowlist and `Agent decides`: if a command matches the denylist, the Agent asks for permission even when that action type is set to **Always allow**. Add your own regular expressions to this list in **Settings** > **Agents** > **Profiles** > **Command denylist**. The one exception is [Run until completion](#run-until-completion), which bypasses your denylist by default. ### MCP permissions [Section titled “MCP permissions”](#mcp-permissions) MCP servers let you extend the Agent with custom tools and data sources using standardized, plugin-like modules. In this settings menu, you can configure which MCP servers the Agent is allowed to call: * Use the MCP allowlist to give the Agent permission to call specific servers without asking. * Use the MCP denylist to require approval before calling certain servers, even if they’re also in the allowlist. * Or set the Agent to “decide” — it will act autonomously when confident, and ask for confirmation when uncertain.  MCP server interaction settings in an Agent Profile. Note To learn how to build and configure your own MCP server, check out the [MCP feature docs](/agents/capabilities/mcp/). ## Run until completion [Section titled “Run until completion”](#run-until-completion) During an Agent interaction, you can give the Agent full autonomy for the current task. When auto-approve is on, every suggested command runs immediately until the task finishes, or you stop it with `Ctrl+C`. * macOS Auto-approve all Agent actions with: `⌘+Shift+I` * Windows Auto-approve all Agent actions with: `Ctrl+Shift+I` * Linux Auto-approve all Agent actions with: `Ctrl+Shift+I`  Auto-approve and take-over controls. Caution *Run until completion* is the purest form of “YOLO” mode: the Agent proceeds without asking for confirmation, and by default it also runs commands that match your command denylist. To keep your denylist in force during *Run until completion*, turn off **Allow auto-approve to bypass command denylist** in **Settings** > **Agents** > **Warp Agent** > **Input**. Denylist rules your team enforces through the [Admin Panel](/enterprise/team-management/admin-panel/) always require approval and are never bypassed. *** ## Next steps [Section titled “Next steps”](#next-steps) Once you’ve configured how your agent operates, try giving it a larger task to plan and execute. * **[Planning](/agents/capabilities/planning/)** - Break down complex tasks into structured, executable plans that the agent runs step by step. * **[Code diffs](/agents/local-agents/code-diffs/)** - Review, refine, and apply code changes the agent generates. * **[Interactive Code Review](/agents/local-agents/interactive-code-review/)** - Leave inline comments on agent-generated diffs and have the agent address your feedback. # Codebase Context Canonical page: [/agents/capabilities/codebase-context/](https://docs.warp.dev/agents/capabilities/codebase-context/) > Warp indexes your Git-tracked codebase to help Agents understand your code and generate accurate, context-aware responses. No code is stored on Warp servers. Codebase Context helps Agents understand your project by indexing your local codebase. This allows Agents to generate more accurate completions, suggest context-aware edits, and answer questions using real knowledge of your code. ## Get started [Section titled “Get started”](#get-started) Index a project and see the difference in agent responses in a few minutes. Note **Don’t have a project to try?** Clone a popular open-source repo to test out codebase indexing: ```bash git clone https://github.com/vercel/next.js.git && cd next.js ``` 1. **Open a project folder in Warp.** Navigate to a Git repository using `cd` or open a folder from the file tree. Warp automatically detects the Git repo and begins indexing. 2. **Verify indexing status.** In Warp, go to **Settings** > **Code** > **Indexing and projects** and check the status under “Initialized / indexed folders.” Once the status shows **Synced**, your codebase is ready. 3. **Ask the Agent a question about your code.** Start an Agent conversation (`⌘+Enter` on macOS, `Ctrl+Shift+Enter` on Windows/Linux) and try a prompt like: * “Explain the architecture of this project” * “What are the main entry points?” * “Walk me through the most important modules” 4. **See the difference.** The Agent grounds its responses in actual files, functions, and line numbers from your codebase, producing more accurate and context-aware answers. *** ## Indexing your codebase [Section titled “Indexing your codebase”](#indexing-your-codebase) When you open a directory in Warp, we check if it is part of a Git repository. If it is, Warp begins indexing the source code to provide rich context for Agents. Warp also detects [Git worktree](/code/git-worktrees/) checkouts — each worktree is indexed as its own repository, so Agents always have accurate context for the branch you’re working on. Note Code indexed with Codebase Context is never stored on our servers. Codebase Context works with both local agent sessions and [cloud agent runs](/platform/). Without Codebase Context enabled, agents will still be able use terminal commands (i.e. `grep`, `sed`) to navigate your code. Note Codebase Context works in SSH sessions when [Warp’s SSH extension](/terminal/warpify/ssh/) is installed on the remote host — the remote repository is indexed directly on the remote machine. WSL sessions are not yet supported ([GitHub #6744](https://github.com/warpdotdev/Warp/issues/6744)).  Codebase indexing settings. **Codebase indexing intervals and triggers:** * Initially when you have Codebase Context enabled. * Warp automatically triggers a codebase index periodically. * Whenever a new Agent conversation begins. * When you click on the sync 🔄 button in **Settings** > **Code** > **Indexing and projects**. **This embeddings index helps Agents:** * Understand your project structure and reference relevant code * Generate completions that match your style and patterns * Suggest edits in the correct locations based on real context For large projects, indexing may take a few minutes. Agents will not use Codebase Context until indexing is complete, but **agentic coding features remain fully available in the meantime**. Note You can view and manage your indexed codebases in **Settings** > **Code** > **Indexing and projects** under “Initialized / indexed folders”. You can also choose whether to automatically index new folders as you navigate them.  ### Codebase indexing states [Section titled “Codebase indexing states”](#codebase-indexing-states) When viewing indexed codebases in Warp under **Settings** > **Code** > **Indexing and projects**, you may see different status indicators: * **Synced** — Indexing is complete and the codebase is ready to be used as context. * **Discovering files** – Warp is currently scanning and indexing files in the codebase. * **Failed** – Indexing failed. Common reasons include unreadable `.git` directories or corrupted repositories. Try re-cloning the repo and syncing again. * **Codebase too large** – The number of files in the codebase exceeds your current plan’s limit. You can either reduce the number of files being indexed using `.warpindexingignore`, or [contact sales](https://www.warp.dev/contact-sales) for support with larger codebases.  Codebase indexing status overview. ### When does codebase syncing happen? [Section titled “When does codebase syncing happen?”](#when-does-codebase-syncing-happen) Warp automatically triggers a codebase sync initially and periodically, when you click on the sync 🔄 button in **Settings** > **Code** > **Indexing and projects**, or when you start a new Agent conversation. However, if many files have changed or the network is slow, the sync may not complete before the Agent tries to access context. Note In large projects (e.g. after a branch switch), there may be a short delay where the Agent references stale or outdated files. ### File and codebase limits [Section titled “File and codebase limits”](#file-and-codebase-limits) The number of codebases you can index and the maximum number of files per repository vary by plan. The Free plan supports indexing **up to 5,000 files per repository**. Higher tiers support larger repositories and additional codebases. For full details, visit our [pricing page](https://www.warp.dev/pricing). ### Ignore files [Section titled “Ignore files”](#ignore-files) For large codebases, Warp supports several ignore files to give you control over what gets indexed. This allows each developer to focus context on the parts of the codebase most relevant to their work. Warp respects the following ignore files: * `.gitignore` * `.warpindexingignore` * `.cursorignore` * `.cursorindexingignore` * `.codeiumignore` Use these files to skip indexing of folders, generated files, or any content you don’t want agents to reference. This can improve performance and result quality. Note Files excluded by ignore rules **do not** count toward your codebase’s file limit. ## Codebase Context in cloud agent runs [Section titled “Codebase Context in cloud agent runs”](#codebase-context-in-cloud-agent-runs) Codebase Context is available in all [cloud agent runs](/platform/viewing-cloud-agent-runs/) — including runs triggered from the CLI, API/SDK, integrations (Slack, Linear, GitHub Actions), and schedules — as long as Codebase Context is enabled for your account. **No additional configuration is needed.** If Codebase Context is enabled, cloud agents use it automatically. ## Multi-repo context [Section titled “Multi-repo context”](#multi-repo-context) Warp supports referencing context across multiple indexed repositories. Note that you don’t need to be inside a specific repo for agents to use its context. **This is especially useful when:** * Implementing a feature across multiple repos, such as full-stack work across client and server * Using one repo as a reference while building in another, for example: “copy the implementation from repo A into my repo B” Agents will only reference other repositories if they are already indexed. During cross-repo tasks, Warp’s Agents have access to the file paths of all indexed repos. It is more likely to use cross-repo context when you mention the exact name of the repo in your prompt. ## Demo: Explain my codebase with Warp [Section titled “Demo: Explain my codebase with Warp”](#demo-explain-my-codebase-with-warp) Here’s an example from [Warp Guides](/guides/), where Zach demonstrates how Warp uses Codebase Context to search for and use the relevant files as context:  *** ## Next steps [Section titled “Next steps”](#next-steps) With your codebase indexed, you can browse your project directly in Warp and start letting agents take action on your code. * **[File Tree](/code/code-editor/file-tree/)** - Browse your project structure in Warp’s sidebar and open files directly. * **[Code editor](/code/code-editor/)** - Edit files with syntax highlighting, LSP support, and find-and-replace without leaving Warp. * **[Agent profiles and permissions](/agents/capabilities/agent-profiles-permissions/)** - Configure how much autonomy the agent has when working with your code. # Computer Use for agents Canonical page: [/agents/capabilities/computer-use/](https://docs.warp.dev/agents/capabilities/computer-use/) > Let agents interact with desktop GUIs in sandboxed cloud environments for automated UI testing and validation. Computer Use enables agents to interact with desktop environments. The agent can see what’s displayed on screen, click and drag, type text, use keyboard shortcuts, and perform other GUI interactions—all within a secure, isolated sandbox. A key use case is **testing UI changes** with a self-contained feedback loop, where the agent can verify that your code changes produce the expected visual and behavioral results without requiring manual testing. ## Capabilities [Section titled “Capabilities”](#capabilities) With Computer Use, agents can: * **Take screenshots** - Capture and analyze the current display * **Record video** - Capture sessions as annotated video recordings; see [Testing and recordings](/agents/capabilities/computer-use/testing-and-recordings/) * **Interact with applications** - Click buttons, fill forms, navigate interfaces * **Type and control keyboard** - Enter text and use keyboard shortcuts * **Automate testing workflows** - Test UI changes end-to-end without manual intervention * **Work with browser-based interfaces** - Test web apps and navigate the web Computer Use is only available in Warp’s sandboxed cloud environments, not in local interactive terminal sessions. ## In this section [Section titled “In this section”](#in-this-section) * [Browser use](/agents/capabilities/computer-use/browser-use/) - Drive the bundled Chromium browser, visually or with scripted Playwright commands. * [Testing and recordings](/agents/capabilities/computer-use/testing-and-recordings/) - Validate changes end-to-end and capture annotated video recordings as proof. * [Screenshots and videos in pull requests](/agents/capabilities/computer-use/artifacts-in-prs/) - Attach captured screenshots and recordings to pull request descriptions automatically. *** ## Enabling Computer Use [Section titled “Enabling Computer Use”](#enabling-computer-use) Computer Use is **enabled by default** for cloud agent runs on Warp’s built-in harness: when a run’s configuration doesn’t specify a Computer Use setting, the agent runs with Computer Use available. Runs on [third-party harnesses](/platform/harnesses/) (Claude Code and Codex) default to Computer Use disabled because third-party harnesses don’t integrate with Warp’s Computer Use tooling. You can control Computer Use per run or per configuration through several entry points: ### Warp app settings [Section titled “Warp app settings”](#warp-app-settings) Runs started from the Warp app don’t use the server default: they always follow the app’s **Computer use in Cloud Agents** setting ([`cloud_agent_computer_use_enabled`](/terminal/settings/all-settings/)), which is off by default. To control Computer Use for [Cloud Agents](/platform/) started from the Warp app, navigate to **Settings** > **Agents** > **Warp Agent** > **Experimental** > **Computer use in Cloud Agents**. ### CLI [Section titled “CLI”](#cli) When running cloud agents with the [Oz CLI](/agents/cli/oz-cli/), use flags to control Computer Use per run: ```bash oz agent run-cloud --computer-use --prompt "" oz agent run-cloud --no-computer-use --prompt "" ``` ### API [Section titled “API”](#api) When creating a cloud agent run with the [Warp Platform API](/factories/api-and-sdk/), the optional `config.computer_use_enabled` field controls Computer Use. When omitted, it defaults to `true` for runs on Warp’s built-in harness and `false` for runs on third-party harnesses. Set it to `false` to disable Computer Use for the run: ```json { "prompt": "Build a button component that matches this design, then test it in the browser", "config": { "computer_use_enabled": false, "environment_id": "optional-environment-id" } } ``` For full API documentation, see the [Warp Platform API](/factories/api-and-sdk/) reference. ### Web app [Section titled “Web app”](#web-app) In the [Oz web app](https://oz.warp.dev), you can enable or disable Computer Use for: * **New agent runs** - Configure Computer Use when starting a new agent run from the web app * **Scheduled agent runs** - Enable Computer Use for [scheduled agents](/platform/triggers/scheduled-agents/) managed from the web app * **Integrations** - Configure Computer Use for Slack, Linear, and other [integration-triggered agents](/platform/integrations/) *** ## How Computer Use works [Section titled “How Computer Use works”](#how-computer-use-works) ### Setup and requirements [Section titled “Setup and requirements”](#setup-and-requirements) Computer Use runs in a containerized sandbox, allowing headless cloud environments to render and interact with graphical applications. The sandbox is fully isolated—it does not have access to your local machine, credentials, or sensitive data outside the sandbox environment. Your cloud environment must include any desktop applications you want the agent to control in your [environment configuration](/platform/environments/). Browser-based tasks need no extra setup: every Computer Use environment includes a bundled Chromium browser. Learn more in [Browser use](/agents/capabilities/computer-use/browser-use/). ### Model selection [Section titled “Model selection”](#model-selection) Computer Use currently supports Anthropic Claude models. Warp uses an auto model selector to choose the best-suited model for each Computer Use task. *** ## Recording sessions [Section titled “Recording sessions”](#recording-sessions) Agents can record their Computer Use sessions as annotated video artifacts — capturing clicks, key presses, and cursor movement alongside the interaction, with idle time trimmed out. Recordings are captured entirely inside the sandbox and never include your local desktop or credentials. For the recording pipeline, what the finished video contains, and where to find recordings, see [Testing and recordings](/agents/capabilities/computer-use/testing-and-recordings/). For how recordings and screenshots land on pull requests, see [Screenshots and videos in pull requests](/agents/capabilities/computer-use/artifacts-in-prs/). *** ## Security considerations [Section titled “Security considerations”](#security-considerations) Computer Use comes with unique security considerations. These risks are heightened when interacting with the internet. To minimize risks when using Computer Use: * **Avoid sensitive data** - Do not pass API keys, authentication tokens, or personal information to agents using Computer Use * **Limit internet access** - If your environment has internet access, consider restricting to an allowlist of known-safe domains * **Require human confirmation** - For tasks with real-world consequences (e.g., financial transactions, accepting legal terms), ask a human to confirm before the agent proceeds * **Review agent actions** - Regularly review what agents are doing on your behalf, especially when testing new workflows *** ## Example workflows [Section titled “Example workflows”](#example-workflows) ### Testing UI changes [Section titled “Testing UI changes”](#testing-ui-changes) Verify that code changes produce the expected visual results and behavior: * **Build from mockups** - Receive a Figma design or mockup image, build the UI, and test it matches * **Visual regression testing** - After code changes, verify UI renders correctly * **Form and interaction testing** - Test form submissions, validation, error handling * **Responsive design validation** - Test layout on different screen sizes For complete end-to-end examples with demo recordings — validating UI changes, QA of critical flows, and bug reproduction — see [Testing and recordings](/agents/capabilities/computer-use/testing-and-recordings/). ### Browsing and web interaction [Section titled “Browsing and web interaction”](#browsing-and-web-interaction) Computer Use can also help with general web tasks: browsing websites, filling out and submitting forms, and navigating multi-step workflows in web applications. See [Browser use](/agents/capabilities/computer-use/browser-use/) for how agents drive the browser. *** ## Related capabilities [Section titled “Related capabilities”](#related-capabilities) * [Images as Context](/agents/local-agents/agent-context/images-as-context/) - Pass design mockups and screenshots as context * [Full Terminal Use](/agents/capabilities/full-terminal-use/) - Let agents drive interactive terminal apps, see live output, and run commands * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Open the cloud run transcript and artifacts after a Computer Use session finishes # Screenshots and videos in pull requests Canonical page: [/agents/capabilities/computer-use/artifacts-in-prs/](https://docs.warp.dev/agents/capabilities/computer-use/artifacts-in-prs/) > Cloud agents automatically attach Computer Use screenshots and video recordings to pull request descriptions, giving reviewers visual proof without extra steps. When a cloud agent run opens or updates a pull request, the screenshots and video recordings it captured with [Computer Use](/agents/capabilities/computer-use/) are attached to the PR description automatically. Reviewers get visual proof of the change — a rendered UI state, a recorded flow, a bug reproduction — without leaving the pull request. ## What gets attached [Section titled “What gets attached”](#what-gets-attached) * **Screenshots** - UI states the agent captures during its Computer Use session. Up to 10 screenshots are attached per pull request. * **Video recordings** - Session recordings the agent produces. See [Testing and recordings](/agents/capabilities/computer-use/testing-and-recordings/) for how recordings are captured and processed. Attachment is automatic: once a screenshot or recording artifact is associated with the run, the agent includes it the next time it creates or updates a pull request. You can encourage captures in your prompt — for example, “take screenshots of the before and after states” or “record the flow and attach it to the PR.” ## Attachment modes [Section titled “Attachment modes”](#attachment-modes) A team-level setting controls how artifacts are attached: * **Link only (default)** - Screenshots and recordings are attached as links to the run’s page in the Oz web app. Artifacts stay private: opening a link requires access to the run. * **Embed** - Screenshots render inline as images in the PR description, and recordings are attached as direct download links. To make this work, the attached artifacts are published at stable, publicly accessible URLs. * **Disabled** - No screenshots or recordings are attached to pull requests. Caution In **Embed** mode, attached screenshots and recordings become publicly downloadable by anyone with the URL — including anyone who can read the PR description. Use **Link only** if your Computer Use sessions may capture content that shouldn’t leave your team. ### Changing the attachment mode [Section titled “Changing the attachment mode”](#changing-the-attachment-mode) Team admins control the attachment mode from the [Admin Panel](https://app.warp.dev/admin/): 1. In the Admin Panel sidebar, select your team under **Team admin**. 2. Click the **Platform** tab. 3. Under **Pull request artifact attachments**, choose **Disabled**, **Link only**, or **Embed**.  The Pull request artifact attachments setting in the Admin Panel. ## Where else artifacts appear [Section titled “Where else artifacts appear”](#where-else-artifacts-appear) Pull requests aren’t the only place captures end up: * **In the conversation** - Screenshots and recordings appear as blocks in the agent’s conversation as they’re captured. * **On the run page** - Open the run in the [Oz web app](/platform/oz-web-app/#runs) to view, play, or download all artifacts the run produced. ## Related pages [Section titled “Related pages”](#related-pages) * [Computer Use](/agents/capabilities/computer-use/) - Control Computer Use and understand security considerations. * [Testing and recordings](/agents/capabilities/computer-use/testing-and-recordings/) - How the recording pipeline works and what finished videos contain. * [Admin Panel for teams](/enterprise/team-management/admin-panel/) - The full reference for team settings, including the Platform section. * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Open and inspect cloud agent run transcripts. * [Privacy](/support-and-community/privacy-and-security/privacy/) - Warp’s data handling policies, including how run artifacts are stored. # Browser use for agents Canonical page: [/agents/capabilities/computer-use/browser-use/](https://docs.warp.dev/agents/capabilities/computer-use/browser-use/) > Computer Use environments include bundled Chromium and the Playwright CLI, so agents can test web apps and browse without extra setup. Agents with [Computer Use](/agents/capabilities/computer-use/) enabled can drive a real browser inside their sandboxed cloud environment — opening web apps, exercising flows, filling forms, and verifying what renders on screen. Every Computer Use environment includes a browser out of the box, so browser-based tasks work without any changes to your [environment configuration](/platform/environments/). ## The bundled browser [Section titled “The bundled browser”](#the-bundled-browser) Computer Use environments ship with a bundled Chromium browser that runs on any environment base image — you don’t need to install Chrome, Firefox, or any browser dependencies yourself. * **Available as `chromium`** - The browser is on the agent’s `PATH` as `chromium`, and the `CHROMIUM_BIN` and `BROWSER` environment variables point to it. * **Your own browser wins** - If your environment’s base image already provides a browser, the agent uses that instead of the bundled one. ## Two ways to drive the browser [Section titled “Two ways to drive the browser”](#two-ways-to-drive-the-browser) Agents can interact with the browser in two complementary ways, and choose the right one for each task: * **Visual interaction** - The agent takes screenshots, then clicks, types, and scrolls like a person would. This is the right mode for verifying what a user actually sees: layout, styling, visual regressions, and rendering issues. * **Scripted control with Playwright** - Computer Use environments also bundle the Playwright CLI (`playwright-cli`), which lets the agent drive the browser through shell commands — navigating to URLs, clicking elements, filling forms, and reading page content — without taking a screenshot for every step. Scripted control is faster and more token-efficient for functional flows, like stepping through a multi-page form or asserting that an element exists. You don’t need to tell the agent which mode to use, but you can steer it in your prompt — for example, “verify the layout visually” or “use Playwright to step through the signup flow.” The bundled Playwright CLI drives the bundled Chromium rather than downloading its own browser build, so it works on base images that don’t provide Playwright’s system dependencies. ### Attaching to a running browser [Section titled “Attaching to a running browser”](#attaching-to-a-running-browser) For advanced workflows, the agent can attach the Playwright CLI to a browser it launched manually with a Chrome DevTools Protocol (CDP) endpoint: ```bash chromium --remote-debugging-port=9222 playwright-cli attach --cdp=http://localhost:9222 ``` This is useful when a task needs to set up specific browser state (for example, launching with custom flags) before scripted control takes over. Caution Browsing the open internet is where Computer Use risks are highest. Prefer non-root containers, which let Chromium run its own process sandbox properly, and consider restricting your environment’s internet access to an allowlist of known-safe domains. See the [security considerations for Computer Use](/agents/capabilities/computer-use/#security-considerations). ## Example workflows [Section titled “Example workflows”](#example-workflows) * **Test a web app end-to-end** - “Start the dev server, then walk through the checkout flow in the browser and verify each step works.” * **Verify a UI change visually** - “Open the settings page and confirm the new toggle renders correctly in both light and dark mode.” * **Automate a web task** - “Fill out the staging signup form with test data and confirm the verification email screen appears.” ## Related pages [Section titled “Related pages”](#related-pages) * [Computer Use](/agents/capabilities/computer-use/) - Control Computer Use and understand how the sandbox works. * [Testing and recordings](/agents/capabilities/computer-use/testing-and-recordings/) - Record browser sessions as annotated videos for review. * [Environments](/platform/environments/) - Configure the cloud environment your agents run in. # Testing with Computer Use and video recordings Canonical page: [/agents/capabilities/computer-use/testing-and-recordings/](https://docs.warp.dev/agents/capabilities/computer-use/testing-and-recordings/) > Use Computer Use to test desktop UIs in a sandbox and capture annotated recordings for UI validation, end-to-end QA, and bug reproduction. Agents don’t just write code; with [Computer Use](/agents/capabilities/computer-use/) enabled they can drive a real desktop GUI in an isolated sandbox, record everything they do, and hand you a trimmed, annotated video as concrete proof of the result. This page explains when to use Computer Use with recordings, how the recording pipeline works, where your recordings end up, what the finished video contains, and how to handle common recording failures. Here’s Warp engineer Varoon Kodithala to walk you through it. [Testing with Computer Use and video recordings walkthrough](https://www.loom.com/embed/fb3190a2e4c442aba76e5145da019b20) ## When to use it [Section titled “When to use it”](#when-to-use-it) Computer Use with recordings fits a wide range of tasks. Three common examples: * **UI change evidence** - After a code change lands, ask an agent to boot the app, exercise the affected surface, and record the session. You get a video showing the change works without running the app yourself. * **End-to-end QA of existing flows** - Run an agent through a critical workflow (for example, Warp’s onboarding flow or a multi-step form) and capture the full interaction as a single clip for review or a regression archive. * **Reproducing a bug** - Ask an agent to reproduce the exact steps from a bug report and record them. The resulting video is the definitive reproduction artifact: shareable, time-stamped, and independent of local environment differences. You don’t need to ask the agent to record explicitly. Prompts like “test this change”, “verify the fix works”, or “produce evidence” naturally lead an agent with Computer Use enabled to start and stop a recording as part of its workflow. ## How it works [Section titled “How it works”](#how-it-works) 1. **Confirm Computer Use is enabled.** Computer Use is enabled by default for cloud agent runs on Warp’s built-in harness, so no setup is needed unless it was turned off for your run. See the [Computer Use](/agents/capabilities/computer-use/#enabling-computer-use) page for how to control it via the Warp app, the Oz CLI, or the Automation Platform API. 2. **Agent starts recording.** Once Computer Use is active, the agent begins a screen capture inside the sandbox. The recording is gated by your session’s Computer Use approval. If you’ve already approved Computer Use for the run, recording starts automatically without a separate prompt. 3. **Agent exercises the UI.** The agent takes screenshots, clicks, types, scrolls, and drives the interface. Each successful interaction is tracked: when it started, when it finished, what actions it contained, and where the cursor moved. 4. **Agent stops and processes.** When the task is complete (or when the recording’s configured time or size limit is reached), the agent stops capture. Before upload, the recording is post-processed: idle and thinking gaps are cut, leaving only the windows where real interaction happened, and action overlays are burned in so the video is annotated. 5. **Artifact is published.** The processed video is uploaded as a run artifact, ready to view wherever the run’s artifacts appear. ## Where to find recordings [Section titled “Where to find recordings”](#where-to-find-recordings) ### In Warp [Section titled “In Warp”](#in-warp) After the agent finishes its Computer Use session, any video recording appears as a block in the conversation. Clicking the block opens the full conversation view alongside the recording artifact. If the recording was produced by a cloud agent run, you can also access it by opening that run’s transcript as a [cloud-synced conversation](/platform/viewing-cloud-agent-runs/). ### In the web app [Section titled “In the web app”](#in-the-web-app) Cloud agent runs are listed on the [Runs page of the Oz web app](/platform/oz-web-app/#runs). Open a run to see its artifacts section, which lists any video recordings produced during that run. You can play the video directly from the run page or download it. ### On pull requests [Section titled “On pull requests”](#on-pull-requests) Recordings are also attached to the PR description when the agent opens or updates a pull request — see [Screenshots and videos in pull requests](/agents/capabilities/computer-use/artifacts-in-prs/). ## What’s in a recording [Section titled “What’s in a recording”](#whats-in-a-recording) The finished video is not raw screen capture. After the agent stops recording, Warp post-processes the video before uploading it: * **Smart cut of idle and thinking time** - Gaps where the agent is planning, waiting on a network call, or idle between actions are removed. What remains are only the windows where real interaction happened, played back at normal speed. This makes recordings significantly shorter than the raw capture duration. * **Action overlays** - Each interaction is burned into the video as overlay pills. Keyboard shortcuts (such as `Ctrl+C`, `Return`, or `Escape`) appear as labels on the frame where they were pressed, so non-visible keys like modifier chords show up clearly. Text typing is labeled “typing…” to avoid leaking sensitive input. Scroll events show a directional label. * **Click ripples and drag trails** - Pointer events (mouse clicks, drags, and moves) are captured with their coordinates and burned into the video as click ripples and movement trails, so cursor activity is visible even when the cursor itself is small on screen. * **Sandbox-only capture** - The recording is taken from inside the isolated sandbox environment. It never captures your local desktop, terminal, credentials, or anything outside the sandbox. Note Post-processing is best-effort: if the cut or overlay burn-in step fails for any reason, the original capture is uploaded without annotations. You still get a video, just without the smart cut or overlay pills. ## Example recordings [Section titled “Example recordings”](#example-recordings) ### UI change evidence [Section titled “UI change evidence”](#ui-change-evidence) An agent validates a visual change, records the before-and-after behavior, and attaches the recording to the pull request for the reviewer. Example prompt: ```text Add a feature to tab groups where each new tab group is assigned a default color that differs from colors already in use. Disable it by default and expose it as a Setting users can toggle on. Once implemented, record a demo that first shows new tab groups getting no color while the setting is off, then enables the setting and shows new tab groups receiving sequential palette colors that cycle back to the start once the palette is exhausted. ``` The finished recording is attached to the pull request, giving a reviewer proof that both states behave correctly without building the change themselves. [](/assets/agent-platform/tab-group-demo.mp4) ### End-to-end QA of an existing flow [Section titled “End-to-end QA of an existing flow”](#end-to-end-qa-of-an-existing-flow) An agent walks through a critical user journey, such as the “New run” creation flow in the Oz web app, capturing the complete interaction. Example prompt: ```text Build the Oz web app and walk through the entire "New run" creation flow end to end. Exercise every entrypoint into the flow: the primary New run button, the Command Palette, and any contextual entrypoints. Then step through each stage from opening the New run surface to submitting a run. ``` This gives you a reproducible, time-stamped clip of the flow that can be archived, diffed across releases, or shared with the team as a baseline. [](/assets/agent-platform/new-run-demo.mp4) ### Reproducing a bug [Section titled “Reproducing a bug”](#reproducing-a-bug) An agent follows the exact steps from a bug report and records them, producing a shareable reproduction artifact. This is a core part of Warp’s open-source workflow: when a user files a bug against [warpdotdev/warp](https://github.com/warpdotdev/warp), we spin off a cloud agent to reproduce and verify it before reviewing any contribution that claims to fix it. Example prompt: ```text Reproduce warpdotdev/warp#13480 ("ctrl+c does not set focus on prompt"): build warp-oss, select a command block, then press Ctrl+C. The block should be deselected and focus should return to the prompt. Record the session so it can be attached to the issue as reproduction proof. ``` In [warpdotdev/warp#13480](https://github.com/warpdotdev/warp/issues/13480), pressing Ctrl+C while a block is selected fails to return focus to the prompt: the block stays selected and its focus annotations linger. The agent reproduces the bug by driving a sandboxed Warp build and pressing Ctrl+C on a selected block on camera. Bug reproductions are one of the strongest use cases because the video is unambiguous: the recording either shows the bug or it doesn’t. [](/assets/agent-platform/ctrl-c-bug.mp4) ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### Recording was cut short [Section titled “Recording was cut short”](#recording-was-cut-short) Each recording has a maximum duration of **10 minutes** and a maximum file size of **1 GiB**. When either limit is hit, the capture is stopped and finalized automatically. If the conversation is cancelled while a recording is active, the recording is discarded rather than uploaded. ### Retry guidance [Section titled “Retry guidance”](#retry-guidance) Most recording failures are transient. If a recording fails or produces an unexpected result: 1. Check the agent’s output for the specific error message. 2. Retry the run; recording substrate errors typically clear on the next attempt. 3. If the failure repeats consistently across multiple runs, file an issue on the [open-source Warp client repository](https://github.com/warpdotdev/warp/issues) with the error message. ## Related [Section titled “Related”](#related) * [Computer Use](/agents/capabilities/computer-use/) - enable Computer Use, understand security considerations, and configure models for Computer Use sessions. * [Screenshots and videos in pull requests](/agents/capabilities/computer-use/artifacts-in-prs/) - how captured artifacts are attached to PR descriptions and the team setting that controls it. * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - open and inspect cloud agent run transcripts in Warp or the browser. * [Security considerations](/agents/capabilities/computer-use/#security-considerations) - understand the sandboxed environment and data isolation model. * [Privacy](/support-and-community/privacy-and-security/privacy/) - Warp’s data handling policies, including how run artifacts are stored. # Full Terminal Use Canonical page: [/agents/capabilities/full-terminal-use/](https://docs.warp.dev/agents/capabilities/full-terminal-use/) > Full Terminal Use means agents can interact with active terminal apps to monitor live output and run commands. Full Terminal Use lets the Warp Agent operate directly inside interactive terminal applications like database shells, debuggers, text editors, and long-running servers. The agent can see the live terminal buffer, write commands, respond to prompts, and hand control back to you at any time. The agent can see the live terminal buffer (terminal state), write to the PTY to run commands, respond to prompts, and continue working inside the running process while you stay in control.  ## Overview [Section titled “Overview”](#overview) With Full Terminal Use, the Warp Agent can attach to interactive tools like `psql`, `vim`, `python`, `gdb`, `top`, or your dev server, read the terminal output as it changes, and interact with the application as if you were typing. You can either ask the agent to start an interactive program, or you can start it yourself and then tag the agent in once the tool is already running. In both cases, the agent sees the same terminal buffer (and PTY session) you do and can act on it. ## How Full Terminal Use works [Section titled “How Full Terminal Use works”](#how-full-terminal-use-works) #### Start an interactive command [Section titled “Start an interactive command”](#start-an-interactive-command) You can either ask the agent to run an interactive command, or start one manually and then tag the agent in: * **Ask the agent to start an interactive tool** * Example: * “Open a Postgres shell and help me inspect the orders table.” * “Start the dev server and debug this 500 error.” * **Or start the command yourself, then tag the agent in** * Example: * If you’ve already launched an interactive tool (for example `psql` or `npm run dev`), you can bring the agent into the running session using the **Use Agent** button in the terminal footer or via `Cmd+I`.  Option to tag the agent into a running command. * Once the agent is tagged in, you can follow up with natural-language requests such as: “Watch this process and help debug the error on the /session endpoint.” * Warp then attaches the agent to the active PTY so it can see the current terminal buffer and propose actions inside the session. [Tagging in the agent.](https://www.loom.com/embed/bcedc521071a4b6a9bbcf74b5156f903)  Running a build command.  Tagging in the Agent to monitor the dev server. Warp attaches the agent to the running command so it can see and control the terminal buffer. #### Agents propose actions inside the session [Section titled “Agents propose actions inside the session”](#agents-propose-actions-inside-the-session) Once attached, you can continue using natural language and the agent turns your requests into concrete terminal actions. For example, in a Postgres shell: * You: “Show me all the tables and describe the orders table.” * Agent: proposes running commands like: `\dt` —> `\d+ orders` In the UI, you’ll see a request to: * Run a specific command * Optionally enable auto-approval for similar commands in this session #### Switching control between user and the agent [Section titled “Switching control between user and the agent”](#switching-control-between-user-and-the-agent) You can swap control at any time. **Take over** * Use the Takeover control to stop the agent from typing or performing any actions. * The shell stays open, and you can type directly into the same session.  Option to take over from agent in the footer. **Hand back control** * When you’re ready for the agent to continue, click the control again. * The agent resumes where you left off, with full access to the current terminal state.  Option to hand-off to the agent in the conversation footer. This makes it easy to: * Let the agent do mechanical work (paging output, trying variants of a command) * Step in for delicate or security-sensitive actions * Then let the agent continue once the critical step is done #### Prompts queue while the agent drives a command it started [Section titled “Prompts queue while the agent drives a command it started”](#prompts-queue-while-the-agent-drives-a-command-it-started) When the agent starts a long-running command itself, prompts you submit while it drives that command are queued by default instead of steering the agent mid-command. They appear in the queued prompts panel with a *(queued until the command finishes)* suffix, and Warp sends them to the agent automatically when the command finishes. This applies only to commands the agent started; if you start a command and tag the agent in, your prompts keep steering the agent immediately. To steer the agent immediately during an agent-started command, toggle auto-queue off for the remainder of the command, or change the **Default long-running command submission mode** setting in the Warp app under **Settings** > **Agents** > **Warp Agent** > **Input**. For the full behavior, including the setting’s options and when it applies, see [Queueing during long-running commands](/agents/local-agents/interacting-with-agents/prompt-queueing/#queueing-during-long-running-commands). #### Long-running commands in terminal vs agent view [Section titled “Long-running commands in terminal vs agent view”](#long-running-commands-in-terminal-vs-agent-view) The behavior differs based on where you start the long-running command: * From terminal view 1. Run an interactive command (e.g., `python`, `psql`) 2. Press `⌘+Enter` (macOS) or `Ctrl+Shift+Enter` (Windows/Linux), or use `⌘+I` (macOS) / `Ctrl+I` (Windows/Linux), to tag in the agent 3. The input switches to Agent Mode with full controls 4. When you exit, an agent conversation block appears in your terminal block list 5. Click the block to reopen the full conversation with your LRC interaction context * From agent view 1. The agent runs an interactive command as part of your conversation 2. Use `⌘+Enter` (macOS) or `Ctrl+Shift+Enter` (Windows/Linux) to tag in if the agent isn’t already interacting 3. The UI stays the same since you’re already in agent view 4. When you exit, the interaction remains part of your conversation. No separate block is created in the terminal block list 5. Commands run in agent view are automatically included as context Note You can also use `⌘+I` (macOS) or `Ctrl+I` (Windows/Linux) to toggle agent control in either view. #### Showing and hiding agent responses [Section titled “Showing and hiding agent responses”](#showing-and-hiding-agent-responses) Warp gives you control over how much agent output appears in Full Terminal Use. **Toggle visibility** Use the `Hide responses` or `Show responses` button or `⌘+G` in the interactive command footer to switch between showing all agent output or hiding it from the terminal view. Note that this only affects the agent’s messages and proposals; your terminal state and command output remain unchanged. **Behavior when hidden** * When agent responses are hidden, your own agent requests automatically dismiss after **4 seconds** to keep the terminal clear. * You can also manually dismiss any user query at any time by hovering over it and clicking the X. [Hiding and showing agent responses in Full Terminal Use demo](https://www.loom.com/embed/c639fb4ab33343a39037b2083c66858a) *** ### Configuring agent permissions and autonomy [Section titled “Configuring agent permissions and autonomy”](#configuring-agent-permissions-and-autonomy) You control how much autonomy the agent has when interacting with the terminal. #### Session-level approvals [Section titled “Session-level approvals”](#session-level-approvals) Each time the agent wants to take an action inside an interactive shell, you’ll see the agent’s reasoning, a brief explanation, and the proposed command. From there you can: * Allow the command once (for example by approving it or pressing `Enter`). * Turn on auto-approval for similar commands in this session (for example with `⌘+Shift+I`). * Refine the request with `Ctrl+C`, which clears the proposed action and lets you follow up with a different query. * Take over manually with `⌘+I`, which stops the agent from issuing any further PTY writes until you hand control back.  Allow, Refine, or Take over an agent response.  This lets you tighten or loosen control for the current task: * For exploratory work, use **Always allow** to reduce friction. * For production systems or sensitive operations, use **Allow once** and review each step. #### Global permission settings [Section titled “Global permission settings”](#global-permission-settings) You can configure global defaults from your [Agent Profiles & Permissions](/agents/capabilities/agent-profiles-permissions/) settings: * **Ask on first write**: The first write to a shell process requires approval. After that, all subsequent writes for that specific process/command will be approved. * **Always ask**: Every write to the shell process from the agent requires your explicit approval. * **Always allow**: The agent can write to the shell process without prompting you each time. These settings apply to every session that uses Full Terminal Use. You can still override them on a per-session basis when prompted. For example, you can enable **auto-approval** for similar commands in the current session using the fast-forward control, or switch to a **different AI profile** with its own permission settings for that conversation. Note **Note**: All [Secret Redaction](/support-and-community/privacy-and-security/secret-redaction/) features still apply during Full Terminal Use, so sensitive values in your environment or output remain protected. ### Credits usage [Section titled “Credits usage”](#credits-usage) All AI interactions from Full Terminal Use consume [credits](/support-and-community/plans-and-billing/credits/), including understanding your natural language requests. Credits are consumed in a similar way as other Warp actions that use the same model and a similar context size. **Interactive sessions can consume more credits if:** * The agent runs many commands in an interactive shell on your behalf. * There is a significant amount of terminal output to read and summarize. **To manage credit usage:** * Use tighter scopes: * “Describe just the orders table.” instead of “Explain the entire database.” * Pause autonomy for high-volume tasks with copious terminal output: * Take over manual control when running large batches or long logs. * Use stricter permissions: * Set global permissions to “Ask on first write” or “Always ask”, then approve only what you need. Note To learn more about what goes into a credit and how to get more value from AI usage in Warp, see: [*Getting the most out of credits in Warp*](https://www.warp.dev/blog/warp-ai-requests). ## Example workflows [Section titled “Example workflows”](#example-workflows) Here’s a demo from one of our engineers, Maggie, that walks through a couple of Full Terminal Use examples. [Full Terminal Use example workflows demo](https://www.loom.com/embed/d47ee09153df417983df65a339a9d6f2) Below are some common interactive tools where Full Terminal Use is particularly useful: database shells (Postgres, MySQL, SQLite), debuggers such as gdb, language-specific REPLs like python or node, text editors and file explorers, and long-running dev servers or monitoring tools such as top and htop. | Tool | Example tasks | Agents can… | | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Database shells (REPLs)** e.g. `psql`, `mysql`, `sqlite`, etc. | * “List all tables and describe the users and orders tables.” * “Create a new table to store archived user sessions.” * “Show me all rows in orders from the last 30 days, grouped by status.” * “Generate and run a query that finds the top 10 customers by revenue.” | - Navigate `\d`, `\dt`, `DESCRIBE`, etc. - Write and execute SQL queries - Summarize results in plain language | | **Text editors** e.g. `vim`, `nano`, etc. | * “Open this file in vim and add a Markdown header and a boilerplate section.” * “Insert a docstring above this function explaining what it does.” * “Generate a CSS utility class block and insert it in this file.” | - Navigate within the editor using keystrokes - Insert, edit, and delete text - Save and quit when done | | **Python REPLs** e.g. `python`, `ipython` | * “Start a Python REPL and define a function that calculates a moving average.” * “Write a unit test for this function and run it.” * “Plot x from 0 to 10 and y = sin(x).” | - Import modules - Define functions and classes - Run tests and small scripts - Print or summarize results back to you | | **Debuggers** e.g. `gdb`, `lldb`, language-specific debuggers | * “Start gdb for this binary and set a breakpoint on `handle_request`.” * “Run until the breakpoint, then show the stack and local variables.” * “Inspect this pointer and tell me if it looks invalid.” | - Issue debugger commands (break, run, next, continue, bt, etc.) - Walk through execution step by step - Summarize relevant state so you don’t have to remember every command | | **Long-running servers and services** e.g. `npm run dev`, `uvicorn`, Rails servers, etc | * “Run the dev server and debug the internal server error on /session.” * “Send a sample request to this endpoint and explain the failure.” * “Kill the server once you identify the error and propose a code diff.” | - Watch server logs in real time - Notice new errors as they appear - Stop the server when appropriate - Propose code changes (for example, via a diff) based on what it observes | | **Version control workflows** e.g. `git rebase -i`, complex git commands | * “Interactively rebase master onto `feature-branch` to squash these commits into one.” * “Resolve these merge conflicts and ensure tests pass.” | - Navigate interactive rebase prompts - Edit commit messages - Apply conflict resolutions you approve | | **Cloud provider CLIs** e.g. `gcloud`, `aws`, `az`, etc. | * “Use gcloud to create a new Kubernetes cluster with these settings.” * “Provision a new RDS instance for staging and show me the connection details.” | - Walk through multi-step CLI workflows - Handle prompts and confirmations - Summarize the resulting resources | # Model Context Protocol (MCP) Canonical page: [/agents/capabilities/mcp/](https://docs.warp.dev/agents/capabilities/mcp/) > Configure MCP servers in the Warp app to extend local agents with custom tools and data sources through a standardized interface. MCP servers extend Warp’s [local agents](/agents/local-agents/interacting-with-agents/) in a modular, flexible way by exposing custom tools or data sources through a standardized interface — essentially acting as plugins for Warp. Warp supports a variety of connection protocols, including Streamable HTTP and SSE, along with custom headers and environment variables. MCP is an open source protocol. Check out the official [MCP documentation](https://modelcontextprotocol.io/introduction) for more detailed information on how this protocol is engineered. Note This page covers MCP servers for local agents in the Warp app. For help choosing between local, cloud, and shared MCP workflows, see [Connect developer tools to agents with MCP workflows](/guides/external-tools/using-mcp-servers-with-warp/). If you’re using cloud agents, see [MCP Servers for cloud agents](/platform/mcp/). ### How to access MCP Server settings [Section titled “How to access MCP Server settings”](#how-to-access-mcp-server-settings) You can navigate to the MCP servers page in any of the following ways: * From the [Settings Page](warp://settings/mcp): **Settings** > **Agents** > **MCP servers** * From [Warp Drive](/knowledge-and-collaboration/warp-drive/): under **Personal** > **MCP Servers** * From the [Command Palette](/terminal/command-palette/): search for `Open MCP Servers` * From the Warp app: **Settings** > **Agents** > **Warp Agent** > **Manage MCP servers** This will show a list of all configured MCP servers, including which are currently running. If you close Warp with an MCP server running, it will run again on next start of Warp. MCP servers that are stopped will remain so on next launch of Warp.  MCP servers page. ### Adding an MCP Server [Section titled “Adding an MCP Server”](#adding-an-mcp-server) To add a new MCP server, you can click the **+ Add** button. Configurations from most MCP clients can be directly copied and pasted. MCP server types you can add: * CLI Server (Command) Provide a startup command. Warp will launch this command when starting up and shut it down on exit.  Adding a CLI MCP Server (Command). Note Always set `working_directory` explicitly when your MCP server command or args include relative paths. This ensures consistent and predictable behavior across machines and sessions. **CLI Server (Command) MCP Configuration Properties** | Property | Type | Required | Description | | ------------------- | --------- | -------- | ----------------------------------------------------------------------------------- | | `command` | string | Yes | The executable to launch (e.g., `npx`). | | `args` | string\[] | Yes | Array of command-line arguments passed to `command` (e.g., module name, paths). | | `env` | object | No | Key-value object of environment variables (e.g., API Tokens). | | `working_directory` | string | No | Working directory path where the command is run, used for resolving relative paths. | * Streamable HTTP or SSE Server (URL) Provide a URL where Warp can reach an already-running MCP server that supports Server-Sent Events.  Adding an SSE MCP Server (URL). **Streamable HTTP or SSE Server (URL) MCP Configuration Properties** | Property | Type | Required | Description | | --------- | ------ | -------- | ----------------------------------------------------------------- | | `url` | string | Yes | The HTTP endpoint URL to connect to via Server-Sent Events (SSE). | | `headers` | object | No | Key-value object of header variables (e.g., Authorization). | ### Adding multiple MCP servers [Section titled “Adding multiple MCP servers”](#adding-multiple-mcp-servers) Warp supports configuring **multiple MCP servers** using a JSON snippet. Each entry under `mcpServers` is keyed by a unique name (`filesystem`, `github`, `notes`, etc.). All servers defined in the example are added automatically — no manual setup required. To add multiple MCP servers, you can click the **+ Add** button then paste in a JSON snippet like the example below: ```json { "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"] }, "notes": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-notes", "--notes-dir", "/Users/you/Documents/notes"] }, "externalDocs": { "url": "http://localhost:4000/mcp/stream", "headers": { "my-header": "my-header-value" } } } } ``` ### File-based MCP servers [Section titled “File-based MCP servers”](#file-based-mcp-servers) Compared to manually adding a server in the Warp settings, file-based servers are defined in config files that Warp detects and can spawn automatically. They offer a few additional benefits: * **Configurable directly with an agent** - Use the [bundled skill](#using-agent-add-mcp) `/agent-add-mcp` so the Warp Agent can add or update an MCP server without leaving the conversation. * **Inherited across providers and repos** - Warp reads `.warp/.mcp.json` files and also picks up config from third-party agent providers (Claude Code, Codex, and others). The same server definition follows you across tools and repos. #### Supported providers [Section titled “Supported providers”](#supported-providers) Warp reads MCP server definitions from the following providers: | Provider | Global config | Project-scoped config | Auto-spawn | | ------------ | ---------------------- | ------------------------------------ | --------------- | | Warp | `~/.warp/.mcp.json` | `.warp/.mcp.json` at project root | On by default | | Claude Code | `~/.claude.json` | `.mcp.json` at project root | Requires toggle | | Codex | `~/.codex/config.toml` | `.codex/config.toml` at project root | Requires toggle | | Other agents | `~/.agents/.mcp.json` | `.agents/.mcp.json` at project root | Requires toggle | Global Warp servers auto-spawn by default. Global servers from all other providers auto-spawn only when **Auto-spawn servers from third-party agents** is enabled. Project-scoped servers from any provider require explicit approval. For provider-specific setup, see the [Claude Code MCP docs](https://code.claude.com/docs/en/mcp#user-scope) and [Codex MCP docs](https://developers.openai.com/codex/mcp/#connect-codex-to-an-mcp-server). #### Auto-spawn behavior [Section titled “Auto-spawn behavior”](#auto-spawn-behavior) Global Warp servers auto-spawn by default. Third-party agent servers require you to enable auto-spawn first. To auto-spawn global servers from third-party agents: 1. In the Warp app, go to **Settings** > **Agents** > **MCP servers**. 2. Toggle **Auto-spawn servers from third-party agents** on.  File-based MCP server settings. Project-scoped servers from any provider must be toggled on individually from the MCP servers page. These are session-scoped — after restarting Warp, toggle them on again if you still trust the repo. #### Using `/agent-add-mcp` [Section titled “Using /agent-add-mcp”](#using-agent-add-mcp) The built-in `/agent-add-mcp` skill lets the Warp Agent create or update file-based MCP server definitions. Choose whether to save globally or in the current project — the skill writes the server definition to the matching file: * **Global:** `~/.warp/.mcp.json` * **Project-scoped:** `{repo_root}/.warp/.mcp.json` [](/assets/agent-platform/file-based-mcp-demo.mp4) The demo shows how to use `/agent-add-mcp` to add an MCP server, choose where Warp saves the file-based configuration, and review the generated `.warp/.mcp.json` file before using the server. #### Security mitigations [Section titled “Security mitigations”](#security-mitigations) MCP config files can start local commands and send data to external tools. Warp adds approval gates around file-based MCP servers to reduce the risk of untrusted config changes: * **Config edits require approval** - Warp prevents edits to MCP config files unless you explicitly approve the change. This keeps an agent or automation from silently adding a server that can run commands or access data. * **Project-scoped servers never auto-spawn** - Warp detects project-scoped MCP config files in cloned repos, but requires you to start each server manually. This prevents a cloned repo from automatically starting an MCP server that runs arbitrary local commands. Note File-based servers that require OAuth show an authentication modal on their first spawn. Credentials are saved for future spawns, the same as manually configured MCP servers. ### Managing MCP servers [Section titled “Managing MCP servers”](#managing-mcp-servers) After MCP servers are registered in Warp, you can **Start** or **Stop** them from the MCP servers page. Each running server will have a list of available tools and resources. You can rename and edit a server’s name, as well as delete the server. If you are a part of a Team, you can also share an MCP server with your teammates. ### Sharing MCP servers [Section titled “Sharing MCP servers”](#sharing-mcp-servers) MCP servers can be shared with your teammates by clicking the share icon. When sharing, sensitive values in the `env` configuration will be automatically scrubbed and replaced with variables.  Sharing an MCP Server. Your teammates can find shared MCP servers under the `Shared` section of their MCP settings. When your teammates install your server configuration, they will be prompted to enter any scrubbed `env` values. Warp also provides out-of-the-box MCP servers that can be installed by anyone. These can be found under the `Shared` section of your MCP settings. ### Authentication in MCP servers [Section titled “Authentication in MCP servers”](#authentication-in-mcp-servers) Most MCP servers require authentication to connect to external services. Warp supports the following methods: * **Environment variables**: pass an API key or access token via the server’s environment variables. * **OAuth login (one-click installation)**: simplifies configuration by handling authentication through your browser. Warp stores credentials securely on your device and reuses them for future sessions. Re-authentication is required when opening Warp on a new machine. * Starting a server without existing credentials automatically opens a browser-based authentication flow. * Credentials can be revoked at any time from the MCP Servers pane in Warp. * **Custom Headers**: pass an Authentication Bearer token via the headers variable. ### Debugging MCP [Section titled “Debugging MCP”](#debugging-mcp) If you’re having trouble with an MCP server, you can check the logs for any errors or messages to help you diagnose the problem by clicking the **View Logs** button on a server from the MCP servers page. Caution If you choose to share your MCP server logs with anybody, **make sure to remove any sensitive information before sharing**, as they may contain API keys. Many SSE based MCP servers will state that your URL should be treated like a password, and can be used with no additional authentication. Note Tip: We’ve noticed that some models often work better with MCP servers than others. If you’re having trouble calling or using an MCP server, try using a different model. #### Debugging MCP authentication issues [Section titled “Debugging MCP authentication issues”](#debugging-mcp-authentication-issues) In some cases you may need to reset the auth token for some MCP servers. To do this, delete the local MCP auth files by running the following: `rm -rf ~/.mcp-auth` Caution Note this will delete all your MCP auth tokens stored locally so you will need to login and re-authenticate. If the above doesn’t help and you need to reset or change authentication, you may need to switch to a CLI-based MCP server configuration and provide the token via environment variables. See the Sentry tab under [MCP server configuration examples](/agents/capabilities/mcp/#mcp-server-configuration-examples). ### Where MCP logs are stored [Section titled “Where MCP logs are stored”](#where-mcp-logs-are-stored) Warp saves the MCP logs locally on your computer. You can open the files directly and inspect the full contents in the following location: * macOS ```bash cd "$HOME/Library/Group Containers/2BBY89MBSN.dev.warp/Library/Application Support/dev.warp.Warp-Stable/mcp" ``` * Windows ```powershell Set-Location $env:LOCALAPPDATA\warp\Warp\data\logs\mcp ``` * Linux ```bash cd "${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal/mcp" ``` ## MCP server configuration examples [Section titled “MCP server configuration examples”](#mcp-server-configuration-examples) Below are examples for popular Model Context Protocol (MCP) servers. * **CLI Server (Command)** — local `npx` or `docker` command based MCP servers. * **Streamable HTTP or SSE Server (URL)** — remote or locally hosted MCP endpoints. ### **Engineering & Ops** [Section titled “Engineering & Ops”](#engineering--ops) * GitHub [GitHub MCP Docs](https://github.com/github/github-mcp-server) **GitHub CLI Server (Command)** ```json { "GitHub": { "command": "docker", "args": ["run","-i","--rm","-e","GITHUB_PERSONAL_ACCESS_TOKEN","ghcr.io/github/github-mcp-server"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "" } } } ``` **GitHub SSE Server (URL)** ```json { "GitHub": { "url": "https://api.githubcopilot.com/mcp/" } } ``` * Sentry [Sentry MCP Docs](https://docs.sentry.io/product/sentry-mcp/) **Sentry CLI Server (Command)** ```json { "Sentry": { "command": "npx", "args": ["-y","mcp-remote@latest","https://mcp.sentry.dev/mcp"] } } ``` **Sentry Streamable HTTP Server (URL)** ```json { "Sentry": { "url": "https://mcp.sentry.dev/mcp" } } ``` * Grafana [Grafana MCP Docs](https://github.com/grafana/mcp-grafana) **Grafana CLI Server (Command)** ```json { "Grafana": { "command": "docker", "args": ["run","--rm","-i","-e","GRAFANA_URL","-e","GRAFANA_API_KEY","mcp/grafana","-t","stdio","-debug"], "env": { "GRAFANA_URL": "http://localhost:3000", "GRAFANA_API_KEY": "" } } } ``` **Grafana SSE Server (URL)** ```json { "Grafana": { "url": "https://your-mcp-host.com/api/mcp/grafana/sse" } } ``` * Linear [Linear MCP Docs](https://linear.app/docs/mcp) **Linear CLI Server (Command)** ```json { "Linear": { "command": "npx", "args": ["-y","mcp-remote","https://mcp.linear.app/mcp"] } } ``` **Linear Streamable HTTP Server (URL)** ```json { "Linear": { "url": "https://mcp.linear.app/mcp" } } ``` * Chroma **Chroma Package Search CLI Server (Command)** 1. Visit Chroma’s [Package Search](http://trychroma.com/package-search) page. 2. Click “Get API Key” to create or log into your Chroma account and issue an API key for Package Search. 3. After issuing your API key, click the “Other” tab and copy your API key. 4. Add the following to your Warp MCP config. Make sure to click “Start” on the server after adding. More info in [Chroma’s Package Search MCP Docs](https://docs.trychroma.com/cloud/package-search/mcp) ```json { "package-search": { "command": "npx", "args": ["mcp-remote", "https://mcp.trychroma.com/package-search/v1", "--header", "x-chroma-token: ${X_CHROMA_TOKEN}"], "env": { "X_CHROMA_TOKEN": "" } } } ``` ### **Design & Collaboration** [Section titled “Design & Collaboration”](#design--collaboration) * Figma **Figma Remote MCP Server (Recommended)** The official Figma remote MCP server supports OAuth for simple, one-click setup. 1. In Warp, go to **Warp Drive** > **MCP Servers** > **+ Add** and paste the configuration below. 2. Warp will open a browser window to authenticate with Figma. 3. After approving access, credentials are stored securely on your device. Note Note: A Figma account with [Dev Mode](https://www.figma.com/dev-mode/) enabled is required. ```json { "Figma": { "url": "https://mcp.figma.com/mcp" } } ``` **Figma Local MCP Server** 1. Enable the Official Figma MCP Server. [Figma MCP Docs](https://help.figma.com/hc/en-us/articles/32132100833559-Guide-to-the-Figma-MCP-server) 2. Open the [Figma desktop app](https://www.figma.com/downloads/) and make sure you’ve [updated to the latest version](https://help.figma.com/hc/en-us/articles/5601429983767-Guide-to-the-Figma-desktop-app#h_01HE5QD60DG6FEEDTZVJYM82QW). 3. Create or open a Figma Design file. 4. In the upper-left corner, open the Figma menu. 5. Under **Preferences**, select **Enable local MCP Server**. 6. Enter the following configuration into **Warp** > **Warp Drive** > **MCP Servers** > **+ Add**. ```json { "Figma (Local)": { "url": "http://127.0.0.1:3845/mcp" } } ``` * Slack [Slack MCP Docs](https://github.com/korotovsky/slack-mcp-server/) **Slack CLI Server (Command)** Enter the following configuration into **Warp** > **Warp Drive** > **MCP Servers** > **+ Add**. ```json { "Slack": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-slack"], "env": { "SLACK_BOT_TOKEN": "xoxb-", "SLACK_APP_TOKEN": "xapp-", "SLACK_TEAM_ID": "T", "SLACK_CHANNEL_IDS": ", ", "MCP_MODE": "stdio" } } } ``` **Slack SSE Server (URL)** Enter the following configuration into **Warp** > **Warp Drive** > **MCP Servers** > **+ Add**. ```json { "Slack": { "url": "https://your-mcp-host.com/api/mcp/slack/sse" } } ``` * Atlassian [Atlassian MCP Docs](https://support.atlassian.com/rovo/docs/setting-up-ides/) **Atlassian CLI Server (Command)** Enter the following configuration into **Warp** > **Warp Drive** > **MCP Servers** > **+ Add**. ```json { "Atlassian": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/sse"] } } ``` * Notion [Notion MCP Docs](https://developers.notion.com/docs/mcp) **Notion CLI Server (Command)** Enter the following configuration into **Warp** > **Warp Drive** > **MCP Servers** > **+ Add**. ```json { "Notion": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"] } } ``` **Notion SSE Server (URL)** Enter the following configuration into **Warp** > **Warp Drive** > **MCP Servers** > **+ Add**. ```json { "Notion": { "url": "https://mcp.notion.com/sse" } } ``` ### MCP server demos [Section titled “MCP server demos”](#mcp-server-demos) [Warp Guides](/guides/) hosts a collection of demos and walkthroughs showing how MCP servers can extend your workflows. Each example highlights practical use cases you can try today: * [**GitHub**](/guides/external-tools/github-mcp-summarizing-open-prs-and-creating-gh-issues/) — access repositories, issues, and pull requests through MCP. * [**Sentry**](/guides/external-tools/sentry-mcp-fix-sentry-error-in-empower-website/) — surface error monitoring and alerts as agent-usable data. * [**Linear**](/guides/external-tools/linear-mcp-retrieve-issue-data/) — integrate project management tasks and tickets. * [**Puppeteer**](/guides/external-tools/puppeteer-mcp-scraping-amazon-web-reviews/) — run automated browser workflows via MCP. * [**Context7**](/guides/external-tools/context7-mcp-update-astro-project-with-best-practices/) — experiment with external data integrations. # Agent planning and execution Canonical page: [/agents/capabilities/planning/](https://docs.warp.dev/agents/capabilities/planning/) > Turn requests into structured, editable plans that agents execute step-by-step with version control. Warp has native planning functionality that helps you break down complex engineering tasks into structured, executable steps. Planning is tightly integrated with Warp’s coding agent and provides a persistent plan editor, version history, selective execution, and deep links into your workspace.  *** ### Creating a plan [Section titled “Creating a plan”](#creating-a-plan) You can generate a plan using the `/plan` [slash command](/agents/capabilities/slash-commands/) or by asking the agent in natural language.  Creating a plan with the /plan command. The agent then creates a structured plan inside Warp’s native rich text editor, which is designed for long, multi-step workflows. The editor includes clean formatting, inline code blocks, and clickable file paths so you can open referenced files immediately in Warp (see below) or in your external editor. ### Reviewing and editing [Section titled “Reviewing and editing”](#reviewing-and-editing) Once a plan is generated, you can review it, reorganize steps, or refine details. You can edit the document manually or ask the agent to revise sections for you.  Plan editor in Warp. Any update made by the agent **creates a new version**. Version history lets you compare past iterations and restore an older version if you want to revert your approach, preserving a clear decision trail as the plan evolves.  Access previous versions of your plan. ### Executing a plan [Section titled “Executing a plan”](#executing-a-plan) When you’re ready to start implementing, prompt the agent to run the plan. You can ask it to execute the full set of steps or only a specific section, such as “Implement phase 1 of the plan.”  Referencing a plan using @. The agent applies changes incrementally and updates files as it proceeds. This makes it easy to validate early steps before moving forward, adjust the plan mid-run, or try alternative paths without committing to the full workflow. If you revise the plan while the agent is running, you can notify it directly; the agent will adjust its execution based on your updates.  Prompt to update the agent’s plan during execution. ### Monitoring progress [Section titled “Monitoring progress”](#monitoring-progress) While the agent is running, you can reopen the plan at any time by selecting **View plan** in the input. You can also follow each change in real time through the [Code Review](/code/code-review/) panel and add comments or guidance using [Interactive Code Review](/agents/local-agents/interactive-code-review/).  Monitoring progress with the task list and plan view. This gives you clear oversight, helps confirm expected behavior, and lets you intervene quickly if something needs correction. ### Saving and sharing [Section titled “Saving and sharing”](#saving-and-sharing) Warp automatically saves all plans in the *Plans* folder in [Warp Drive](/knowledge-and-collaboration/warp-drive/). You’ll see a confirmation when your plan is synced.  Plans are automatically synced to Warp Drive. You can export any plan as Markdown, check it into your repository, or share a link—useful for GitHub PRs, design reviews, or async collaboration.  Different ways to share a plan. Because plans persist in Warp Drive, you can return to them later, reuse them for new work, or treat them as documentation for ongoing projects. This is also naturally passed to the agent as context.  Plans are accessible directly from the Warp Drive side panel. You can configure whether your plans will be automatically added and synced to Warp Drive in your [Agent Profiles & Permissions](/agents/capabilities/agent-profiles-permissions/) under **Settings** > **Agents** > **Profiles**.  ### Using plans across conversations [Section titled “Using plans across conversations”](#using-plans-across-conversations) Plans are reusable across tasks and sessions. You can reference them in future prompts, continue where you left off, or build follow-up plans that rely on earlier work. The **@plans** command helps you quickly search for and reopen previously saved plans, making planning a consistent part of your development workflow rather than a one-off step. See [attaching context with @ references](/agents/local-agents/agent-context/using-to-add-context/) for more ways to add files, folders, diffs, and saved objects to an agent conversation.  *** ## Next steps [Section titled “Next steps”](#next-steps) As the agent executes your plan, you’ll review code changes and may want to scale work to the cloud. * **[Interactive Code Review](/agents/local-agents/interactive-code-review/)** - Leave inline comments on agent-generated diffs and have the agent revise in one pass. * **[Cloud Agents quickstart](/platform/quickstart/)** - Run agents in the cloud for longer tasks, background automation, or parallel work across repos. # Rules for agents Canonical page: [/agents/capabilities/rules/](https://docs.warp.dev/agents/capabilities/rules/) > Create reusable Global or Project Rules to ensure agents follow your coding standards, project conventions, and personal preferences. Warp’s **Rules** feature lets you create reusable guidelines that inform how agents respond to your prompts. Rules help tailor responses to match your coding standards, project conventions, and personal preferences, making agent interactions smarter and more consistent. Warp supports two types of rules: **Global Rules** and **Project Rules**.  ## Global Rules [Section titled “Global Rules”](#global-rules) Global Rules apply across all projects and contexts. They’re ideal for: * Coding standards and best practices * Workspace-wide guidelines * Tool configurations or preferences you want applied everywhere Warp may also suggest Global Rules based on your usage patterns to make future interactions smarter and more consistent. ## Project Rules [Section titled “Project Rules”](#project-rules) Project Rules live in your codebase and apply automatically when working within that project. They’re stored in an `AGENTS.md` file (or `WARP.md` for backwards compatibility) and can be: * Placed in the root of your repository * Added in subdirectories for more targeted guidance Note Warp uses `AGENTS.md` as the default project rules file. Existing `WARP.md` files are still fully supported—if you have `WARP.md`, it will continue to work as expected. You can also rename `WARP.md` to `AGENTS.md` at any time without additional changes. If both `WARP.md` and `AGENTS.md` exist in the same directory, `WARP.md` takes priority. Caution The filename must be in **all caps** for Warp to recognize it (e.g., `AGENTS.md`, not `agents.md` or `Agents.md`). We recommend creating `AGENTS.md` for new projects. **When you’re in a directory:** * Warp automatically applies the `AGENTS.md` (or `WARP.md`) in the root and in the current directory. * If you edit files in another subdirectory, Warp makes a best-effort attempt to include that subdirectory’s rules file as well. Example project structure: * project/ * api/ * AGENTS.md API-specific rules * ui/ * AGENTS.md UI-specific rules * AGENTS.md Project-wide rules How Warp applies these Project Rules: * **If the current directory is `ui/`** * Automatically applied: `project/AGENTS.md` and `project/ui/AGENTS.md` * Best effort: `project/api/AGENTS.md` if editing files there * **If the current directory is `api/`** * Automatically applied: `project/AGENTS.md` and `project/api/AGENTS.md` * Best effort: `project/ui/AGENTS.md` if editing files there ### Rules precedence [Section titled “Rules precedence”](#rules-precedence) When multiple rules apply, Warp follows this order of precedence: 1. Rules in the current subdirectory’s project rules file 2. Rules in the root directory’s project rules file 3. Global Rules This ensures the most specific, project-relevant rules take priority over broader ones. *** ## How to access Rules [Section titled “How to access Rules”](#how-to-access-rules) * From [Warp Drive](/knowledge-and-collaboration/warp-drive/): **Personal** > **Rules** * From the [Command Palette](/terminal/command-palette/): search for “Open AI Rules” * From the Settings panel: **Settings** > **Agents** > **Knowledge** > **Manage Rules** * Here, you can manage both Global as well as Project Rules. * From the Warp menu bar: **AI** > **Open Rules** * From the Slash Commands menu: `/open-project-rules` to open Project Rules directly in Warp’s code editor  Project Rules UI open in a Rules pane. ## How to create, edit, or delete Rules [Section titled “How to create, edit, or delete Rules”](#how-to-create-edit-or-delete-rules) #### Global Rules [Section titled “Global Rules”](#global-rules-1) * **From Warp Drive Rules pane:** **Personal** > **Rules** > **Global**\ Add, edit, or delete any number of rules. Each rule can include: * Name (optional) * Description (what the rule does and when to apply it) * **From the Slash Commands menu:** Use `/add-rule` to create a new Global Rule (automatically opens the Warp Drive Rules pane). [Rules Demo (legacy) with just Global Rules. Project rules can also be found there.](https://www.loom.com/embed/3a49462c01e149cf9c040130cebe1184) #### Project Rules [Section titled “Project Rules”](#project-rules-1) * **When in a directory, set up Project Rules with a slash command:** Use `/init` to: * Begin indexing your codebase or display indexing status * Generate an `AGENTS.md` file with initial context, or * Link an existing Rules file to `AGENTS.md` * Warp currently supports linking the following external Rules files: `CLAUDE.md`, `.cursorrules`, `AGENT.md`, `GEMINI.md`, `.clinerules`, `.windsurfrules`, `.github/copilot-instructions.md` To view all Project Rules and open them in Warp, access it via the Warp Drive Rules pane: **Personal** > **Rules** > **Project-based** ### Rules as Agent context [Section titled “Rules as Agent context”](#rules-as-agent-context) When relevant, Agents automatically pull in applicable rules to guide their responses. Rules used in an interaction will appear in the conversation under **References** or marked as derived from a specific rule.  An agent response showing which rules were applied.  Rules listed as references in an agent conversation. ### Rules privacy [Section titled “Rules privacy”](#rules-privacy) See our [Privacy page](/support-and-community/privacy-and-security/privacy/) for more information on how we handle data with Rules. # Skills for agents Canonical page: [/agents/capabilities/skills/](https://docs.warp.dev/agents/capabilities/skills/) > Create reusable instruction sets that teach agents specific tasks and share expertise across your team. Skills allow you to create reusable, shareable instructions that agents can invoke when performing tasks. Instead of repeating detailed prompts, you can encapsulate common workflows, coding patterns, or domain expertise into skill files that agents automatically discover and use. ## Key features [Section titled “Key features”](#key-features) * **Reusable instructions** - Define a task once and let Agents use it whenever relevant * **Project and global scopes** - Create skills specific to a project or available across all projects * **Automatic discovery** - Agents are aware of all available skills and invoke them when appropriate * **Simple markdown format** - Skills are just markdown files with a small amount of metadata * **Supporting files** - Include scripts, templates, or other resources alongside your skill instructions * **Slash command invocation** - Invoke any skill directly with `/{skill-name}` * **Parameterized skills** - Use argument placeholders to create dynamic, reusable skill templates ## How Skills work [Section titled “How Skills work”](#how-skills-work) When you start an [Agent conversation](/agents/local-agents/interacting-with-agents/), the Agent receives a list of all available skills with their names and descriptions. When the Agent determines that a skill would help accomplish your task, it loads the skill’s full instructions and follows them to complete the task. Caution Skill discovery is based on your current working directory. For Git repositories, Warp includes all skills from your current directory up through the repository root. If you’re working in project A, you won’t have access to skills from project B. Note Skills complement Rules, which provide persistent guidelines that Agents always follow. Use Rules for constraints and preferences; use Skills for specific task workflows. ### Skill name conflicts [Section titled “Skill name conflicts”](#skill-name-conflicts) If you have skills with the same name in multiple directories, Warp handles the conflict differently depending on how the skill is invoked: * **Natural language** - The Agent receives a list of all in-scope skills including their names, descriptions, and file paths. The Agent can see all available options and chooses the appropriate skill based on its path. * **Slash commands** - When multiple skills share the same name, Warp displays all matching skills in the menu. You select which one to use based on the description. * **Background resolution** - When Warp resolves skill names automatically (without direct user selection), it prioritizes home directory (global) skills first, then skills from higher directories (closer to the repository root). ### Example interactions [Section titled “Example interactions”](#example-interactions) You can invoke skills in two ways: **Using natural language** - Describe what you want to accomplish: * “Use the deploy skill to push to staging” * “Check the docs for broken links” (invokes a link-checking skill) * “Create a DOCX file with my project’s README content” * “Draft documentation for the new API endpoint based on this PR” **Using slash commands** - Invoke a skill directly with `/{skill-name}`: * `/deploy` - Invokes the deploy skill * `/add-feature-flag` - Invokes the add-feature-flag skill The Agent recognizes when your request matches a skill’s purpose, loads the skill instructions, and follows them to complete the task. ### Identify skill sources in conversation data [Section titled “Identify skill sources in conversation data”](#identify-skill-sources-in-conversation-data) The [Conversation API](/api) returns skill loads as `read_skill` actions. The action’s `input` identifies the skill source: | Input field | Skill source | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | `bundled_skill_id` | A Warp-provided bundled reference when this field is present. | | `skill_path` | The path used to resolve the skill. It can refer to a file-based skill or a path-referenced bundled skill, including one from a remote host. | To measure usage of skills your team owns, exclude `read_skill` actions whose `input` contains `bundled_skill_id`. From the remaining actions, count only `skill_path` values under skill roots your team manages. Don’t classify other path-based entries as customer-owned because Warp-bundled skills can also use `skill_path`. See the [bundled skill ID catalog](/factories/api-and-sdk/#skill-actions-in-conversation-data) for Warp-provided IDs and availability details. ## Skill file format [Section titled “Skill file format”](#skill-file-format) Skills are markdown files with YAML frontmatter. Each skill must have: * **name** - A unique identifier for the skill (typically kebab-case) * **description** - A brief explanation of what the skill does and when to use it ### Basic structure [Section titled “Basic structure”](#basic-structure) ```markdown --- name: your-skill-name description: Brief description of what this skill does and when to use it --- # Your Skill Name ## Instructions Provide clear, step-by-step guidance for the agent. You can use argument placeholders like $ARGUMENTS or $0 in the body (see [Skill arguments](#skill-arguments)). ## Examples Show concrete examples of using this skill. ``` ### Example skill file [Section titled “Example skill file”](#example-skill-file) Here’s a complete example of a skill that helps create feature flags: ```markdown --- name: add-feature-flag description: Add a new feature flag to the codebase with proper configuration and documentation --- # Add Feature Flag ## Instructions 1. Ask the user for the feature flag name and default value 2. Add the flag definition to `config/feature_flags.yaml` 3. Create a helper function in `src/utils/flags.ts` 4. Update the feature flags documentation in `docs/FEATURE_FLAGS.md` ## Configuration Format Feature flags should follow this format in the YAML file: feature_name: default: false description: "What this flag controls" owner: "team-name" ## Examples - "Add a feature flag for the new checkout flow" - "Create a flag to enable dark mode for beta users" ``` ## Skill arguments [Section titled “Skill arguments”](#skill-arguments) Skills can include argument placeholders that are automatically substituted with values you provide when invoking the skill. This lets you create reusable, parameterized skill templates. [Using Skill Arguments in Warp](https://www.loom.com/embed/4cb0a80e567c41788816cd9b5acbc7ed) ### Argument syntax [Section titled “Argument syntax”](#argument-syntax) Three placeholder formats are supported: * **`$ARGUMENTS`** — Replaced with the full raw argument string (everything after the skill name). * **`$ARGUMENTS[N]`** — Replaced with the Nth whitespace-separated argument (0-indexed). For example, `$ARGUMENTS[0]` is the first argument, `$ARGUMENTS[1]` is the second, etc. * **`$N`** — Shorthand for `$ARGUMENTS[N]`. For example, `$0` is equivalent to `$ARGUMENTS[0]`. ### How argument substitution works [Section titled “How argument substitution works”](#how-argument-substitution-works) When you invoke a skill, any text you type after the skill name is treated as the argument string. The argument string is split on whitespace to produce individual indexed arguments. **If the skill contains argument placeholders** (`$ARGUMENTS`, `$ARGUMENTS[N]`, or `$N`), the placeholders are replaced with the corresponding argument values before the skill instructions are sent to the agent. **If the skill does not contain any argument placeholders**, the extra text you provide is passed to the agent as a separate user message alongside the skill instructions. This means you can always add context when invoking a skill, whether or not it uses argument placeholders. Note If a placeholder references an argument index that wasn’t provided (e.g. `$2` when only two arguments were given), the placeholder is left as-is in the skill content. ### Example: Skill with arguments [Section titled “Example: Skill with arguments”](#example-skill-with-arguments) Here’s a skill that uses arguments to explain a topic for a specific audience: ```markdown --- name: explain-topic description: Explain a topic for a specific audience in a given tone --- # Explain Topic Explain $0 for an audience of $1 professionals. Use a $2 tone. Full request: $ARGUMENTS ``` Invoking this skill with: ```plaintext /explain-topic bears engineering fun ``` Produces the following instructions for the agent: ```plaintext Explain bears for an audience of engineering professionals. Use a fun tone. Full request: bears engineering fun ``` ### Example: Skill without arguments [Section titled “Example: Skill without arguments”](#example-skill-without-arguments) If a skill has no argument placeholders: ```markdown --- name: greet description: Greet the user with an Australian-style hello --- # Greet Greet the user warmly in an Australian style. ``` Invoking with extra text: ```plaintext /greet say it in French ``` The skill instructions are sent first, then “say it in French” is passed as a follow-up user message. The agent sees both and can combine them — in this case, greeting in French with an Australian flair. ## Skill locations [Section titled “Skill locations”](#skill-locations) Skills can be stored at two levels: project-level (accessible only within that project) and user-level (accessible from any project). ### Project skills [Section titled “Project skills”](#project-skills) Project skills live in your repository and are available when you’re working in that project. We recommend storing them at your project root, but skills in subdirectories are also discovered when you’re working within that subdirectory. This is useful for monorepos with separate `./frontend` and `./backend` directories. Store them in any of these directories: * **`.agents/skills/`** (recommended) * **`.warp/skills/`** * **`.claude/skills/`** * **`.codex/skills/`** * **`.cursor/skills/`** * **`.gemini/skills/`** * **`.copilot/skills/`** * **`.factory/skills/`** * **`.github/skills/`** * **`.opencode/skills/`** Each skill must be in its own subdirectory with a `SKILL.md` file. Any supporting files (scripts, templates, configs) should be referenced in `SKILL.md` so the Agent knows they exist: * your-project/ * .agents/ * skills/ * add-feature-flag/ * SKILL.md * run-migrations/ * SKILL.md * .claude/ * skills/ * review-code/ * SKILL.md * .github/ * skills/ * create-release/ * SKILL.md Note Warp scans all supported skill directory names in your project root, allowing you to maintain skills compatible with multiple AI coding tools in the same repository. ### Root directory skills (global) [Section titled “Root directory skills (global)”](#root-directory-skills-global) Root directory skills are stored in your home directory and are available across all projects on your machine. These are useful for personal workflows, coding patterns, or procedures you use regardless of the specific project. Store global skills in any of these directories in your home folder: * **`~/.agents/skills/`** (recommended) * **`~/.warp/skills/`** * **`~/.claude/skills/`** * **`~/.codex/skills/`** * **`~/.cursor/skills/`** * **`~/.gemini/skills/`** * **`~/.copilot/skills/`** * **`~/.factory/skills/`** * **`~/.github/skills/`** * **`~/.opencode/skills/`** The directory structure is the same as project skills: * `~/.agents/` * skills/ * git-workflow/ * SKILL.md * code-review/ * SKILL.md ### Project vs Root directory skills [Section titled “Project vs Root directory skills”](#project-vs-root-directory-skills) Understanding when to use each level: **Project skills** are best for: * Project-specific workflows (deployment, testing, migrations) * Team-shared procedures and standards * Repository-specific automation and tooling * Domain-specific patterns for that codebase **Root directory skills** are best for: * Personal coding preferences and patterns * General-purpose workflows used across all projects * Cross-project automation (git workflows, documentation templates) * Professional standards you apply everywhere ### Extra directories for cloud runs [Section titled “Extra directories for cloud runs”](#extra-directories-for-cloud-runs) [Cloud agents](/platform/) discover skills from the repositories in their [environment](/platform/environments/). To index skills that live outside those repositories — for example, skills baked into a custom Docker image — set the `WARP_SKILL_DIRS` environment variable. See [extra skill directories in cloud runs](/platform/skills-as-agents/#extra-skill-directories-in-cloud-runs). ## Creating skills [Section titled “Creating skills”](#creating-skills) ### Step 1: Choose a location [Section titled “Step 1: Choose a location”](#step-1-choose-a-location) Decide whether your skill should be: * **Project-specific** - Place it in one of your project’s skill directories (`.agents/skills/`, `.warp/skills/`, `.claude/skills/`, etc.) * **Global** - Place it in one of your home directory’s skill folders (`~/.agents/skills/`, `~/.warp/skills/`, `~/.claude/skills/`, etc.) ### Step 2: Create the directory structure [Section titled “Step 2: Create the directory structure”](#step-2-create-the-directory-structure) Create a subdirectory for your skill with a descriptive name: ```bash mkdir -p .agents/skills/my-new-skill ``` ### Step 3: Write the skill file [Section titled “Step 3: Write the skill file”](#step-3-write-the-skill-file) Create `SKILL.md` in your skill directory: ```bash touch .agents/skills/my-new-skill/SKILL.md ``` ### Step 4: Add content [Section titled “Step 4: Add content”](#step-4-add-content) Write your skill with clear instructions: ```markdown --- name: my-new-skill description: One-line description of what this skill does --- # My New Skill ## When to use Explain the scenarios where this skill is helpful. ## Instructions 1. First step the Agent should take 2. Second step with specific details 3. Continue with clear, actionable steps ## Important notes - Any constraints or requirements - Common pitfalls to avoid ``` ## Skills with supporting files [Section titled “Skills with supporting files”](#skills-with-supporting-files) Skills can include supporting files like scripts, templates, or configuration files. Place these files in the same directory as your `SKILL.md`: * .agents/skills/ * check-broken-links/ * SKILL.md * `check_links.py` Supporting script * config.yaml Configuration file In your skill instructions, reference these files using relative paths. For example, in your `SKILL.md`: ```plaintext ## Running the check From the project root: python3 .agents/skills/check-broken-links/check_links.py --internal-only ``` This pattern is useful for: * **Automation scripts** - Python, shell, or Node scripts that perform complex tasks * **Templates** - Boilerplate files the Agent can copy and customize * **Configuration** - Default settings or schemas the skill references ## Managing skills [Section titled “Managing skills”](#managing-skills) ### Viewing available skills [Section titled “Viewing available skills”](#viewing-available-skills) Ask the Agent what skills are available: ```plaintext What skills do I have? ``` The Agent lists all discovered skills with their names and descriptions. This includes skills from all supported directories in both your current project and your home directory. ### Editing skills [Section titled “Editing skills”](#editing-skills) Use the [`/open-skill`](/agents/capabilities/slash-commands/) slash command to modify existing skills: ```plaintext /open-skill ``` This opens an interactive menu where you can: * Browse project and root directory skills * See which directory each skill is located in * Open the skill file in your editor ### Best practices [Section titled “Best practices”](#best-practices) * **Write clear descriptions** - The description is how Agents decide whether to use your skill * **Be specific in instructions** - Include exact file paths, command syntax, and expected formats * **Include examples** - Show concrete use cases to help Agents understand intent * **Keep skills focused** - Each skill should do one thing well * **Use consistent naming** - Follow a naming convention like `verb-noun` (e.g., `add-feature-flag`, `run-migrations`) * **Version control your skills** - Commit project skills to your repo so the whole team benefits ## Pre-built skills [Section titled “Pre-built skills”](#pre-built-skills) Warp maintains a public collection of ready-to-use skills in the [warpdotdev/oz-skills](https://github.com/warpdotdev/oz-skills) repository. You can browse these skills for inspiration, copy them directly into your project’s `.agents/skills/` directory, or adapt them to fit your team’s workflows. These same skills also appear as suggested agents in the [Oz web app](/platform/oz-web-app/), where you can run them directly in the cloud. ## Suggested skills from Agent Memory [Section titled “Suggested skills from Agent Memory”](#suggested-skills-from-agent-memory) Promoting recurring patterns from [Agent Memory](/agents/agent-memory/) into reviewable skill drafts is in design as part of the research preview. See the Agent Memory page for a current status. ## Invoking skills with a prompt [Section titled “Invoking skills with a prompt”](#invoking-skills-with-a-prompt) You can pass additional context or instructions to a skill when invoking it with a slash command. **Using slash commands with a prompt:** * `/deploy push the latest changes to staging` — Invokes the deploy skill with additional instructions to target staging * `/code-review focus on error handling and edge cases` — Invokes the code-review skill with guidance on what to prioritize This is useful when you want to reuse a skill’s workflow but tailor the execution to a specific situation without modifying the skill itself. ## Running agents from skills [Section titled “Running agents from skills”](#running-agents-from-skills) Skills can be used with both local and [cloud agents](/platform/) to create reusable, automated workflows. When running an agent via the CLI, web app, or API, you can specify a skill to provide the base instructions for the agent. For a complete guide to running skill-based agents—including CLI usage, the Oz web app, scheduling, skill discovery, and API integration—see [Skills as Agents](/platform/skills-as-agents/). ## Related features [Section titled “Related features”](#related-features) * [**Rules**](/agents/capabilities/rules/) - Set persistent guidelines and constraints for Agent behavior * [**MCP Servers**](/agents/capabilities/mcp/) - Expose external data sources and tools to Agents * [**Cloud Agents**](/platform/) - Run Agents in the cloud on schedules or triggers * [**Agent Profiles**](/agents/capabilities/agent-profiles-permissions/) - Control Agent permissions and autonomy *** ## Next steps [Section titled “Next steps”](#next-steps) Skills become even more powerful when you automate and share them. * **[Scheduled Agents quickstart](/platform/triggers/scheduled-agents-quickstart/)** - Run a skill on a recurring cron schedule for tasks like weekly dependency checks or daily code cleanup. * **[Integrations quickstart](/platform/integrations/quickstart/)** - Trigger skills from Slack or Linear so your team can invoke agent workflows from the tools they already use. # Slash Commands Canonical page: [/agents/capabilities/slash-commands/](https://docs.warp.dev/agents/capabilities/slash-commands/) > Use Slash Commands in terminal mode or Agent Mode to quickly run built-in actions or saved prompts without leaving the input field. Slash Commands are quick actions and saved prompts you can invoke by typing `/` in terminal mode or Agent Mode. They provide instant access to built-in actions like starting conversations, creating environments, switching models, opening static flows, and running saved prompts from Warp Drive.  Slash Commands menu. As you type, the menu filters results in real time, making it easy to find and run the command or prompt you need. ## Static slash commands [Section titled “Static slash commands”](#static-slash-commands) Warp currently supports the following built-in Slash Commands: | Slash Command | Description | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/add-mcp` | Add a new [MCP server](/agents/capabilities/mcp/). | | `/add-prompt` | Add a new [Agent Prompt](/knowledge-and-collaboration/warp-drive/prompts/) in Warp Drive. | | `/add-rule` | Add a new [Global Rule](/agents/capabilities/rules/) for the Agent. | | `/agent` | Start a new [agent conversation](/agents/local-agents/interacting-with-agents/). Optionally include a prompt to send immediately. | | `/changelog` | Open the latest Warp [changelog](/changelog/). | | `/cloud-agent` | Start a new [cloud agent conversation](/platform/). `*` | | `/compact` | Free up context by summarizing conversation history. | | `/compact-and` | Compact the current conversation and then send a follow-up prompt. | | `/continue-locally` | Fork the current cloud agent conversation into a local Warp session. See [Handoff between local and cloud agents](/platform/handoff/). Available while a cloud agent conversation is active. | | `/conversations` | Open [conversation history](/agents/local-agents/interacting-with-agents/). | | `/copy-debugging-id` | Copy debugging information for the current conversation to your clipboard, so you can include it when [reporting an issue](/support-and-community/troubleshooting-and-support/sending-us-feedback/). Available while a conversation is active. | | `/cost` | Toggle credit usage details in the current conversation. | | `/create-environment` | Create a [Warp Environment](/platform/environments/) (Docker image + repos) via guided setup. `*` | | `/create-new-project` | Have the Agent walk you through creating a new coding project. `*` | | `/environment` | Switch the [environment](/platform/environments/) for the current cloud agent conversation. | | `/export-to-clipboard` | Export the current conversation to clipboard in markdown format. | | `/export-to-file` | Export the current conversation to a markdown file. | | `/feedback` | Open the static feedback experience. See [Using `/feedback` in Warp](/support-and-community/troubleshooting-and-support/sending-us-feedback/#using-feedback-in-warp) for details. | | `/fork` | [Forks the current conversation](/agents/local-agents/interacting-with-agents/conversation-forking/) into a new thread with the full context and history of the original. You can optionally include a prompt that will be sent immediately in the forked conversation. | | `/fork-and-compact` | [Forks the current conversation](/agents/local-agents/interacting-with-agents/conversation-forking/) and automatically compacts the forked version. Useful when you want a fresh, summarized starting point that preserves relevant context while trimming the rest. | | `/fork-from` | Open a searchable menu to [fork the conversation](/agents/local-agents/interacting-with-agents/conversation-forking/) from a specific query. Select a query to create a fork that includes everything up to that point. | | `/handoff` | Hand the current local conversation off to a cloud agent, carrying its history and a snapshot of your uncommitted changes. See [Handoff from local to cloud](/platform/handoff/local-to-cloud/). You can optionally include a follow-up prompt. `*` | | `/harness` | Switch the [harness](/platform/harnesses/) for the current cloud agent conversation. | | `/host` | Switch the execution host for the current cloud agent conversation. | | `/index` | Index the current codebase using [Codebase Context](/agents/capabilities/codebase-context/). | | `/init` | Index the current codebase and generate an [AGENTS.md file](/agents/capabilities/rules/). `*` | | `/model` | Switch the base agent model for the current conversation. | | `/new` | Start a new [agent conversation](/agents/local-agents/interacting-with-agents/) (alias for `/agent`). | | `/open-code-review` | Open the [code review](/code/code-review/) pane. | | `/open-file` | Open a file for editing in Warp’s [code editor](/code/code-editor/). | | `/open-mcp-servers` | View the status of your [MCP servers](/agents/capabilities/mcp/). | | `/open-project-rules` | Open the [Project Rules](/agents/capabilities/rules/#project-rules) file (`AGENTS`). | | `/open-repo` | Switch to another indexed repository. | | `/open-rules` | View all of your global and project [rules](/agents/capabilities/rules/). | | `/open-settings-file` | Open the Warp [settings file](/terminal/settings/) (`settings.toml`) in Warp’s code editor. | | `/open-skill` | Open an interactive menu to browse and edit project or global [skills](/agents/capabilities/skills/). | | `/orchestrate` | Break a task into subtasks and run them in parallel with multiple agents. See [Multi-agent orchestration](/platform/orchestration/). `*` | | `/plan` | Prompt the Agent to research and create a [plan](/agents/capabilities/planning/) for a task. When the work benefits from parallel agents, the plan can include [multi-agent orchestration](/platform/orchestration/). | | `/profile` | Switch the active [execution profile](/agents/capabilities/agent-profiles-permissions/). | | `/prompts` | Search saved [prompts](/knowledge-and-collaboration/warp-drive/prompts/). | | `/queue` | Queue a prompt to send after the agent finishes responding. See [Prompt Queueing](/agents/local-agents/interacting-with-agents/prompt-queueing/). | | `/remote-control` | Publish the current third-party CLI agent session to the cloud so you can monitor and steer it from another device. See [Remote Control](/agents/cli-agents/remote-control/). | | `/rename-conversation` | Rename the current conversation. | | `/rename-tab` | Rename the current tab. Include the new tab name as an argument (for example, `/rename-tab deploy`). | | `/rewind` | Rewind to a previous point in the conversation. | | `/set-tab-color` | Set the color of the current tab. Takes a required color argument: `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, or `none` to clear it. See [Tab colors](/terminal/windows/tabs/#tab-colors). | | `/skills` | Invoke a [skill](/agents/capabilities/skills/) from a searchable menu. | | `/usage` | Open [billing and usage](/support-and-community/plans-and-billing/) settings. | Caution Slash commands marked with a `*` consume credits to complete the task. #### Using Agent Prompts via Slash Commands [Section titled “Using Agent Prompts via Slash Commands”](#using-agent-prompts-via-slash-commands) In addition to static commands, the menu also shows [Agent Prompts](/knowledge-and-collaboration/warp-drive/prompts/) saved in your [Warp Drive](/knowledge-and-collaboration/warp-drive/). * These prompts can be custom ones you’ve created or ones shared with you. * As you type after `/`, prompts are filtered dynamically, so you can quickly run them without leaving the input field.  Slash Commands menu with filtered Agent Prompts. ### Tips [Section titled “Tips”](#tips) * **Context-aware:** Many Slash Commands use your current working directory or file selection as context. * **Quick access:** Use `/` from terminal mode or Agent Mode to avoid navigating through menus. ### Example of using a Slash Command [Section titled “Example of using a Slash Command”](#example-of-using-a-slash-command) Below is an example interaction when `/init` is run:  The /init setup flow, step 1 of 2.  The /init setup flow, step 2 of 2. # Agent Task Lists Canonical page: [/agents/capabilities/task-lists/](https://docs.warp.dev/agents/capabilities/task-lists/) > Track and manage complex Agent workflows with automatic task lists that break requests into clear, actionable steps and update progress in real time. Task Lists let the Warp Agent automatically break down complex requests into clear, trackable steps. When a request requires multiple actions, the agent creates a structured list, executes each step in order, and tracks progress in real time. No configuration is needed—the agent detects and creates task lists automatically.  An example of a Task List in progress. ### How task lists work [Section titled “How task lists work”](#how-task-lists-work) 1. **Automatic task creation** — For complex requests, the Agent generates a structured list of tasks to complete. 2. **Step-by-step execution** — The Agent works through each task in sequence, updating statuses in real time. 3. **Summary** — Once all tasks are complete, the Agent provides a concise summary of what was done, including outputs, results, and relevant context. If any tasks were skipped or couldn’t be completed, it explains why. After each step is completed, there is also a completion marker in the Agent conversation.  Task completion markers in a conversation. ### Task statuses [Section titled “Task statuses”](#task-statuses) Each task in the list has a visual indicator so you can quickly see its progress. | Status | Icon | Meaning | | ------------ | ----------------- | ----------------------------------------------- | | Current task | ● (filled circle) | The Agent is actively working on this task. | | Completed | ✔︎ | The Agent has finished this task successfully. | | Not started | ○ (empty circle) | The task is in the queue but work hasn’t begun. | | Cancelled | ■ (filled square) | The task was stopped before completion. |  ### Task list access [Section titled “Task list access”](#task-list-access) During any Agent conversation, a task list chip appears at the bottom-right of the screen (when input is pinned to the bottom; otherwise, it may appear along the right side). * Click the chip to open the current task list. * You can collapse or expand the view at any time without interrupting the Agent.  Task List chip in an agent conversation. # Agent web search Canonical page: [/agents/capabilities/web-search/](https://docs.warp.dev/agents/capabilities/web-search/) > Warp’s web search lets agents pull in real-time information, documentation, and cited sources whenever it improves an answer. Warp includes native web search for models that support first-party search tools. When enabled, agents can look up information in real time, consult documentation, retrieve current version numbers, and cite the sources used to generate responses. [Web search in Warp](https://www.loom.com/embed/06a4ba98f2e0446d80cb37aa4c23848c) This page covers how web search works, supported models, what you can expect inside Warp, configuration options, and how this differs from attaching URLs directly to a prompt. *** ### When the Agent uses web search [Section titled “When the Agent uses web search”](#when-the-agent-uses-web-search) Models initiate a web search when it improves the quality or accuracy of an answer. **Common scenarios include:** * Retrieving official documentation or API references * Getting the latest version of a library or tool * Checking error messages, GitHub issues, or Stack Overflow discussions * Looking up ongoing incidents or recent changes * Answering questions where recency matters (e.g., “best approach in 2025 to…”) Web searches are automatically triggered when the model considers them useful. You don’t need special syntax. ### How web search works in Warp [Section titled “How web search works in Warp”](#how-web-search-works-in-warp) **When a search occurs:** 1. Warp shows a “Searching the web…” indicator inside the conversation. 2. You can expand the search result to view: * The query issued * The pages retrieved 3. **The model reads results and produces a grounded response.** * Claude models cite sources in the references footer. * OpenAI models use inline citations and also show references in the footer. ### Supported and unsupported models [Section titled “Supported and unsupported models”](#supported-and-unsupported-models) Web search is available only for models that offer a native web search integration, that works in tandem with other custom tools. **Models that support web search** * Anthropic: `Claude Opus 5.5`, `Claude 4.6 Series`, `Claude 4.5 Series`, `Claude 4 Series` * OpenAI: * `GPT-6 Astra`, `GPT-6.1 Sol`, `GPT-6 Sol`, `GPT-6 Luna` * `GPT-5.4`, `GPT-5.3 Codex`, `GPT-5.2 Codex`, `GPT-5.2` Warp uses each vendor’s official tool: * [Claude web search tool documentation](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool) * [OpenAI web search tool documentation](https://developers.openai.com/api/docs/guides/tools-web-search) Note **Note**: We plan to add native web search for additional models as soon as their APIs fully support it. We’ll continue updating the list of search-capable models as vendors roll out broader tooling. We’re also exploring custom web search tools that’ll work across all models. ### Viewing search results [Section titled “Viewing search results”](#viewing-search-results) You can inspect the web search UI at any time: * Expand the **Web Search** section in the agent response * You can see: * The list of pages fetched * The text used to answer your question * Citations and reference metadata  This makes it easy to verify accuracy, audit reasoning, and validate sources. ### Enabling or disabling web search [Section titled “Enabling or disabling web search”](#enabling-or-disabling-web-search) Web search is controlled per [Profiles & Permissions](/agents/capabilities/agent-profiles-permissions/). To configure: 1. In the Warp app, navigate to **Settings** > **Agents** > **Profiles**. 2. Next to the agent profile, click **Edit**. 3. Scroll to **Call web tools** and toggle the setting on or off.  Disabling this prevents the agent from performing searches, even if a model would normally use them. ### Credit usage [Section titled “Credit usage”](#credit-usage) Web search incurs two types of credit usage: 1. A small fixed cost per search invocation 2. Additional cost proportional to retrieved content, since retrieved text is passed to the model You’ll see these contributions itemized in the conversation’s credit usage footer, alongside model calls, planning calls, and other tool usage. # Warp Agent CLI overview Canonical page: [/agents/cli/](https://docs.warp.dev/agents/cli/) > Run the Warp Agent in any terminal with the Warp Agent CLI. Prompt the agent, run shell commands, and hand work off to cloud agents. The Warp Agent CLI brings the Warp Agent from the Warp app to the terminal you already use. Run the `warp` command to start an agent conversation. You can prompt the agent in natural language, review and approve its actions, and run shell commands in the same input, without changing your terminal setup. ## What is the Warp Agent CLI? [Section titled “What is the Warp Agent CLI?”](#what-is-the-warp-agent-cli) The Warp Agent CLI is a standalone terminal program that runs [the Warp Agent](/platform/harnesses/warp-agent/), the same agent that powers the Warp app. It renders conversations as a scrolling transcript in your terminal, with streaming responses, code diffs, tool calls, and permission requests you approve inline. The CLI is also a native terminal multiplexer. It creates and maintains its own pseudoterminal (PTY), which lets you and the agent execute commands and interact with running processes through the same terminal, including prompts and full-screen terminal apps. Because it’s a regular command-line program, it works in any terminal emulator, including over SSH. To get a working setup in a few minutes, follow the [quickstart](/agents/cli/quickstart/). ## Key features [Section titled “Key features”](#key-features) * **[Agent conversations](/agents/cli/agent-conversations/)** - Follow the agent’s work in a scrollable transcript with streamed responses, Markdown formatting, file-edit diffs, tool calls, plans, and task lists. * **[Shell commands](/agents/cli/input-and-shell-commands/#shell-mode)** - Run shell commands from the same input you use to prompt the agent, including long-running and interactive ones. * **[Permissions and profiles](/agents/cli/permissions-and-profiles/)** - Approve commands and file edits from inline request cards, or configure execution profiles and auto-approve. * **[Persistent conversations](/agents/cli/agent-conversations/#managing-conversations)** - Conversations save to your Warp account, so you can exit and resume later or switch between them. * **[Cloud handoff and orchestration](/agents/cli/cloud-and-orchestration/)** - Hand off a conversation to a cloud agent, continue cloud runs in the CLI, and coordinate multiple agents. * **[Project context](/agents/cli/configuration/#project-context-and-rules)** - The agent automatically picks up your project’s rules (like `AGENTS.md`), skills, and MCP servers. * **[Model choice](/agents/cli/models-and-usage/)** - Pick a model per conversation, bring your own provider API keys, and track credit usage. * **[Customization](/agents/cli/configuration/)** - Configure themes, the statusline, and the start screen through a local settings file. ## How it relates to the Warp app and cloud agents [Section titled “How it relates to the Warp app and cloud agents”](#how-it-relates-to-the-warp-app-and-cloud-agents) * **The Warp app** - The CLI runs the same [Warp Agent](/platform/harnesses/warp-agent/) harness as the Warp app, so your account, plan, model access, rules, and skills work the same in both. The CLI doesn’t require the Warp app to be installed. * **Automation Platform** - The Automation Platform is Warp’s programmable platform for running and coordinating agents at scale. The CLI connects to the same platform. Conversations sync to your Warp account, and you can hand work off to [cloud agents](/agents/cli/cloud-and-orchestration/) or continue a cloud run from your terminal. ## Checking your account, plan, and billing [Section titled “Checking your account, plan, and billing”](#checking-your-account-plan-and-billing) The CLI has slash commands for the account details you’d otherwise look up in the Warp app or the Oz web app. * **Session and account status** - Run `/status` to open a read-only panel with the installed version, the current conversation’s name and ID, the working directory, and the organization and email you’re signed in as. Press `Esc` to close it. Include these details when you report a problem. * **Upgrade your plan** - Run `/upgrade` to open Warp’s upgrade page in your browser. * **Manage team billing** - Run `/manage-billing` to open your team’s billing page in your browser. The command is listed only when you administer billing for your team. For how usage is metered as you work, see [models and usage](/agents/cli/models-and-usage/#usage-and-cost). ## Coming from the Warp app [Section titled “Coming from the Warp app”](#coming-from-the-warp-app) If you already use the Warp app, most of your setup carries over. Rules and skills are discovered from the same shared paths, and your saved Warp Drive prompts are available after you log in (other Warp Drive object types aren’t available in the CLI). To copy compatible settings and global MCP server configurations, run the bundled `/tui-migrate-setup` skill and follow the agent’s instructions. Credentials are never copied, so MCP servers that require authentication must be reauthenticated in the CLI. ## Next steps [Section titled “Next steps”](#next-steps) * [Quickstart](/agents/cli/quickstart/) - Install the CLI, log in, run your first prompt, and see the supported platforms. * [Agent conversations](/agents/cli/agent-conversations/) - Learn how the transcript, diffs, and approvals work. * [Input and shell commands](/agents/cli/input-and-shell-commands/) - Compose prompts and run shell commands from the same input. * [Configuration](/agents/cli/configuration/) - Customize the CLI with the settings file. * [Reference](/agents/cli/reference/) - Flags, slash commands, and keyboard shortcuts. # Claude Code in Warp Canonical page: [/agents/cli-agents/claude-code/](https://docs.warp.dev/agents/cli-agents/claude-code/) > Set up Claude Code in Warp with full notification support, rich input, code review, and more. Claude Code is Anthropic’s agentic coding tool that operates directly in your terminal. It understands your codebase, executes commands, edits files, and manages Git workflows — all through natural language. For full documentation, see the [official Claude Code docs](https://code.claude.com/docs). Warp auto-detects Claude Code when you run it, giving you access to rich input controls, code review, agent notifications, and other integrated features. For a product overview, see [Claude Code in Warp](https://www.warp.dev/agents/claude-code). For installation, authentication, project configuration, and productivity tips, see the [How to set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) guide. Note Claude Code is also available as a harness in the Automation Platform for cloud orchestration. See [Claude Code with the Automation Platform](/platform/harnesses/claude-code/). ## Setting up notifications [Section titled “Setting up notifications”](#setting-up-notifications) Warp supports agent notifications for Claude Code through a plugin. Once installed, Warp surfaces in-app and desktop alerts when Claude Code needs your input — such as command approval, code review, or error intervention. ### Auto-install [Section titled “Auto-install”](#auto-install) Each time you run Claude Code in Warp without the notification plugin installed, a notification chip appears offering one-click installation. Click the chip to install the plugin automatically. After installation, Warp immediately starts receiving notifications from Claude Code. ### Manual install [Section titled “Manual install”](#manual-install) Note The notification plugin requires `jq`. Install it with your package manager (e.g., `brew install jq` on macOS) if it’s not already available. If the auto-install chip doesn’t appear or fails to install the plugin, install it manually. From inside Claude Code, run: ```bash /plugin marketplace add warpdotdev/claude-code-warp /plugin install warp@claude-code-warp ``` Or from your terminal (outside of Claude Code): ```bash claude plugin marketplace add warpdotdev/claude-code-warp claude plugin install warp@claude-code-warp ``` After installing, restart Claude Code or run `/reload-plugins` to activate the plugin. Note If installation fails or you have an outdated version of the plugin, remove it first with `claude plugin marketplace remove claude-code-warp`, then re-run the install commands above. ### Installation instructions banner [Section titled “Installation instructions banner”](#installation-instructions-banner) If the auto-install chip doesn’t work, or if you’re running Claude Code over SSH or on a remote machine, Warp displays an installation instructions banner directly in the terminal. The banner shows step-by-step commands that you can run in place — no need to switch between tabs or copy-paste from external documentation. For plugin source and updates, see the [claude-code-warp GitHub repository](https://github.com/warpdotdev/claude-code-warp). ## Supported Warp features [Section titled “Supported Warp features”](#supported-warp-features) Claude Code supports Warp’s full set of agent integration features: * **Agent notifications** - Receive in-app and desktop alerts when Claude Code needs your attention. The notification UI displays your current git branch alongside agent status. * **Rich input editor** - Press `Ctrl-G` to open an expanded input editor for composing longer prompts. * **Code review** - Send inline review comments directly to the agent from Warp’s code review panel. * **Attach code as context** - Select code and send it to the agent as context. * **Vertical tabs with agent metadata** - Monitor Claude Code sessions with status indicators in Warp’s tab bar. * **Tab Configs** - Save and restore Claude Code session configurations. * **[Remote Control](/agents/cli-agents/remote-control/)** - Publish your Claude Code session so you can monitor and steer it from another device. ## Related pages [Section titled “Related pages”](#related-pages) * [How to set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) — step-by-step setup guide * [Claude Code in Warp](https://www.warp.dev/agents/claude-code) — product overview * [Third-party CLI agents overview](/agents/cli-agents/overview/) — supported CLI agent integrations * [Remote Control](/agents/cli-agents/remote-control/) — publish a Claude Code session to monitor and steer it remotely * [Claude Code with the Automation Platform](/platform/harnesses/claude-code/) — Claude Code as a cloud harness * [OpenCode](/agents/cli-agents/opencode/) — OpenCode in Warp * [Codex](/agents/cli-agents/codex/) — Codex in Warp # Codex CLI in Warp Canonical page: [/agents/cli-agents/codex/](https://docs.warp.dev/agents/cli-agents/codex/) > Set up Codex in Warp with notification support, rich input, code review, and more. Codex is OpenAI’s open-source coding agent that runs in your terminal. It can write and edit code, execute commands, and navigate your codebase through natural language. For full documentation, see the [Codex GitHub repository](https://github.com/openai/codex). Warp auto-detects Codex when you run it, giving you access to rich input controls, code review, and other integrated features. For a product overview, see [Codex in Warp](https://www.warp.dev/agents/codex). For installation, authentication, project configuration, and productivity tips, see the [How to set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) guide. Note Codex is also available as a harness in the Automation Platform for cloud orchestration. See [Codex with the Automation Platform](/platform/harnesses/codex/). ## Setting up notifications [Section titled “Setting up notifications”](#setting-up-notifications) Warp surfaces Codex activity as in-app and desktop alerts — such as when Codex completes a task, encounters an error, or needs your input. This is powered by the Warp plugin for Codex, published from the [warpdotdev/codex-warp](https://github.com/warpdotdev/codex-warp) plugin marketplace. When Warp detects a Codex session without the plugin, it shows an install chip in the terminal. Click the chip to install the plugin, then restart Codex. Warp shows an update chip the same way when a newer plugin version is required. To install the plugin yourself, add the marketplace and the plugin: ```bash codex plugin marketplace add warpdotdev/codex-warp codex plugin add warp@codex-warp ``` Restart Codex to activate the plugin. To update it later, upgrade the marketplace and reinstall the plugin: ```bash codex plugin marketplace upgrade codex-warp codex plugin add warp@codex-warp ``` Note If you point `codex-warp` at a local (non-Git) marketplace source, Warp leaves that override alone and doesn’t offer plugin updates for it. ## Supported Warp features [Section titled “Supported Warp features”](#supported-warp-features) Codex supports Warp’s full set of agent integration features: * **Agent notifications** - Receive in-app and desktop alerts when Codex needs your attention. Requires the Warp plugin for Codex (see [Setting up notifications](#setting-up-notifications)). * **Rich input editor** - Press `Ctrl-G` to open an expanded input editor for composing longer prompts. * **Code review** - Send inline review comments directly to the agent from Warp’s code review panel. * **Attach code as context** - Select code and send it to the agent as context. * **Vertical tabs with agent metadata** - Monitor Codex sessions with status indicators in Warp’s tab bar. * **Tab Configs** - Save and restore Codex session configurations. * **[Remote Control](/agents/cli-agents/remote-control/)** - Publish your Codex session so you can monitor and steer it from another device. ## Related pages [Section titled “Related pages”](#related-pages) * [How to set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) — step-by-step setup guide * [Codex in Warp](https://www.warp.dev/agents/codex) — product overview * [Third-party CLI agents overview](/agents/cli-agents/overview/) — supported CLI agent integrations * [Codex with the Automation Platform](/platform/harnesses/codex/) — Codex as a cloud harness * [Claude Code](/agents/cli-agents/claude-code/) — Claude Code in Warp * [OpenCode](/agents/cli-agents/opencode/) — OpenCode in Warp # OpenCode in Warp Canonical page: [/agents/cli-agents/opencode/](https://docs.warp.dev/agents/cli-agents/opencode/) > Set up OpenCode in Warp with notification support, rich input, code review, and more. OpenCode is an open-source terminal-based coding agent. It connects to multiple LLM providers and supports tool use, file editing, and command execution from your terminal. For full documentation, see the [OpenCode docs](https://opencode.ai/docs). Warp auto-detects OpenCode when you run it, giving you access to rich input controls, code review, agent notifications, and other integrated features. For a product overview, see [OpenCode in Warp](https://www.warp.dev/agents/opencode). For installation, authentication, project configuration, and productivity tips, see the [How to set up OpenCode](/guides/external-tools/how-to-set-up-opencode/) guide. ## Setting up notifications [Section titled “Setting up notifications”](#setting-up-notifications) Warp supports agent notifications for OpenCode through a plugin. Once installed, Warp surfaces in-app and desktop alerts when OpenCode needs your input. To set up the plugin, add `"@warp-dot-dev/opencode-warp"` to the `plugin` array in your `opencode.jsonc` configuration file (or `opencode.json` if you use plain JSON): ```json { "plugin": ["@warp-dot-dev/opencode-warp"] } ``` If the plugin isn’t installed, Warp displays an installation chip in the terminal when you run OpenCode, with setup steps you can follow directly. For plugin source and updates, see the [opencode-warp GitHub repository](https://github.com/warpdotdev/opencode-warp). ## Supported Warp features [Section titled “Supported Warp features”](#supported-warp-features) OpenCode supports Warp’s full set of agent integration features: * **Agent notifications** - Receive in-app and desktop alerts when OpenCode needs your attention. The notification UI displays your current git branch alongside agent status. * **Rich input editor** - Press `Ctrl-G` to open an expanded input editor for composing longer prompts. * **Code review** - Send inline review comments directly to the agent from Warp’s code review panel. * **Attach code as context** - Select code and send it to the agent as context. * **Vertical tabs with agent metadata** - Monitor OpenCode sessions with status indicators in Warp’s tab bar. * **Tab Configs** - Save and restore OpenCode session configurations. * **[Remote Control](/agents/cli-agents/remote-control/)** - Publish your OpenCode session so you can monitor and steer it from another device. ## Related pages [Section titled “Related pages”](#related-pages) * [How to set up OpenCode](/guides/external-tools/how-to-set-up-opencode/) — step-by-step setup guide * [OpenCode in Warp](https://www.warp.dev/agents/opencode) — product overview * [Third-party CLI agents overview](/agents/cli-agents/overview/) * [Claude Code](/agents/cli-agents/claude-code/) * [Codex](/agents/cli-agents/codex/) # Third-party CLI agents overview Canonical page: [/agents/cli-agents/overview/](https://docs.warp.dev/agents/cli-agents/overview/) > Warp provides first-class support for third-party CLI coding agents with a rich input editor, notifications, code review, and more. Warp auto-detects supported CLI agents and enhances them with IDE-level features — a rich input editor, agent notifications, inline code review, [Remote Control](/agents/cli-agents/remote-control/), and more. Run your preferred coding agent inside Warp and get a better experience out of the box. This feature set is also known as **universal agent support**. Looking for Warp’s own CLI instead? The [Warp Agent CLI](/agents/cli/) runs the Warp Agent itself in any terminal. This page covers running third-party coding agents inside the Warp app. Note Claude Code and Codex are also supported as harnesses in the Automation Platform for [multi-agent orchestration](/platform/orchestration/). See [Harnesses in the Automation Platform](/platform/harnesses/). ## Supported agents [Section titled “Supported agents”](#supported-agents) Warp currently supports the following CLI coding agents: * [**Claude Code**](/agents/cli-agents/claude-code/) — Anthropic’s CLI coding agent * [**OpenAI Codex**](/agents/cli-agents/codex/) — OpenAI’s CLI coding agent * [**OpenCode**](/agents/cli-agents/opencode/) — Open-source CLI coding agent * **Amp** — Sourcegraph’s CLI coding agent * **Auggie** — Augment Code’s CLI coding agent * **Copilot CLI** — GitHub’s CLI coding agent * **Cursor CLI** — Cursor’s CLI coding agent * **Gemini CLI** — Google’s CLI coding agent * **Droid** — Factory’s CLI coding agent * **Pi** — Open-source CLI coding agent * **Goose** — Block’s CLI coding agent * **Antigravity** — the Antigravity CLI coding agent (invoked with `agy`) * **Hermes** — Nous Research’s CLI coding agent * **Mistral Vibe** — Mistral’s CLI coding agent * **Grok Build** — xAI’s CLI coding agent (invoked with `grok`) When you launch a supported agent inside Warp, the **agent toolbelt** appears automatically, giving you quick access to Warp’s enhanced features.  The agent toolbelt for CLI agents. ## Feature support [Section titled “Feature support”](#feature-support) Not every feature is available for every agent. The table below shows current support. | Feature                               | Claude Code | Codex | OpenCode | Amp | Auggie | Copilot CLI | Cursor | Gemini CLI | Droid | Pi | | ------------------------------------- | ----------- | ----- | -------- | --- | ------ | ----------- | ------ | ---------- | ----- | -- | | Rich input editor (`Ctrl-G`) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Agent notifications | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | | Code review comments | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Attach code as context | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Vertical tabs + metadata | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Tab Configs | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Remote Control | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | **Goose**, **Antigravity** (`agy`), **Hermes**, **Mistral Vibe**, and **Grok Build** (`grok`) are also recognized. They get the same enhanced features as the agents above — rich input editor, code review comments, attach code as context, vertical tabs and metadata, Tab Configs, and Remote Control — but don’t support agent notifications yet. Note Agent notifications require a one-time setup. Claude Code and OpenCode use a Warp notification plugin. Codex uses a native config change. See the individual agent pages for setup instructions. Amp, Auggie, Copilot CLI, Cursor, Gemini CLI, Droid, Pi, Goose, Antigravity, Hermes, Mistral Vibe, and Grok Build don’t support notifications yet. ## Customizing the toolbelt [Section titled “Customizing the toolbelt”](#customizing-the-toolbelt) The chips and buttons on the CLI agent toolbelt can be reordered, hidden, or moved between the left and right sides. Your layout is saved and persists across app restarts. In the Warp app, open the **Edit CLI agent toolbelt** modal in one of two ways: * Right-click the input area while a supported CLI coding agent is running and select **Edit CLI agent toolbelt**. * Go to **Settings** > **Agents** > **Third party CLI agents**, then click the **Toolbar layout** preview. ## Getting started [Section titled “Getting started”](#getting-started) Run a supported agent inside Warp — that’s it. Warp detects the agent automatically and activates the agent toolbelt with all available features. For **agent notifications**, each agent requires a one-time setup — either a notification plugin or a config change. See the individual agent pages for instructions. Note If you don’t see the agent toolbelt, make sure you’re on the latest version of Warp. *** ## Related pages [Section titled “Related pages”](#related-pages) * [Remote Control](/agents/cli-agents/remote-control/) — publish a CLI agent session to monitor and steer it from another device * [Cloud handoff and orchestration](/agents/cli/cloud-and-orchestration/) — hand off a Warp Agent CLI conversation to a cloud agent, or run multi-agent orchestration from the terminal * [Agent Notifications](/agents/capabilities/agent-notifications/) * [How to run multiple AI coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) — run CLI agents in parallel with worktrees and cloud fan-out * [Tabs](/terminal/windows/tabs/) * [Tab Configs](/terminal/windows/tab-configs/) # Remote Control Canonical page: [/agents/cli-agents/remote-control/](https://docs.warp.dev/agents/cli-agents/remote-control/) > Publish any third-party agent session to the cloud so you can monitor progress, steer the agent, and check in from your phone or another computer. Remote Control lets you publish a running third-party agent session — such as Claude Code, Codex, or OpenCode — to the cloud with a single click. Once published, you can monitor progress, review output, and steer the agent from your phone, a web browser, or another computer without staying at the original machine. See [Third-party CLI agents](/agents/cli-agents/overview/) for the full list of supported agents. This is especially useful for long-running agent tasks. Start a coding agent, publish the session, and check back whenever you want.  Note Remote Control is built on top of [Agent Session Sharing](/agents/local-agents/session-sharing/). It uses the same underlying infrastructure to publish sessions and generate shareable links. ## Key capabilities [Section titled “Key capabilities”](#key-capabilities) * **One-click publish** - Click the `/remote-control` chip in the agent utility bar to publish instantly. The shareable link is copied to your clipboard automatically. * **Monitor from anywhere** - Check on agent progress from a phone, tablet, or another computer — no install required for web viewers * **Steer remotely** - Send input, approve commands, or redirect the agent without being at your original machine * **Team access** - Share the link with teammates so they can observe or collaborate on the session * **Persistent cloud access** - The session stays in sync while it’s active. New agent output and terminal activity appear for all viewers in real time. Syncing stops when you close or stop publishing the session. ## How it works [Section titled “How it works”](#how-it-works) When you publish a session through Remote Control, Warp uploads the session state to the cloud and generates a shareable link. The link stays live and in sync — any new agent output, tool use, or terminal activity appears for all connected viewers in real time. You control who can view and who can steer the agent. Remote Control differs from standard [Agent Session Sharing](/agents/local-agents/session-sharing/) in its intent: Session Sharing is designed for live collaborative work (pair-programming, interactive debugging), while Remote Control is designed for async monitoring and steering when you’re away from your machine. ## Publishing a session [Section titled “Publishing a session”](#publishing-a-session) 1. Start or resume a third-party agent session in Warp (for example, Claude Code or Codex). 2. Click the **`/remote-control`** chip in the agent utility bar. Warp publishes the session to the cloud and copies the shareable link to your clipboard.  The /remote-control chip in the agent utility bar. 3. A **Sharing link copied** toast notification confirms the link is on your clipboard, and the pane’s status icon changes to a red broadcast indicator to show that publishing is active. 4. Open the link on another device, or share it with a teammate. To stop publishing, click the **Stop sharing** button in the agent utility bar. The status icon returns to its normal state, confirming the session is no longer accessible remotely. ## Accessing a remote session [Section titled “Accessing a remote session”](#accessing-a-remote-session) Published sessions are accessible from: * **Web browser** - Open the shared link in any browser. No app install required. * **Warp desktop app** - Paste the link into Warp on a different machine for the full desktop experience * **Mobile** - Open the link on your phone or tablet browser to check on progress while away from your desk The web experience mirrors the desktop view, showing complete agent activity including thinking steps, tool use, and terminal output. ## Permissions [Section titled “Permissions”](#permissions) When you publish a session, you control access: * **View access** - Anyone with the link can watch the session, see agent output, and review terminal activity * **Edit access** - You can grant viewers permission to send input, approve commands, or redirect the agent Only you (the publisher) can revoke access or stop publishing the session. ## Related pages [Section titled “Related pages”](#related-pages) * [Agent Session Sharing](/agents/local-agents/session-sharing/) * [Third-party CLI agents](/agents/cli-agents/overview/) * [Viewing Cloud Agent Runs](/platform/viewing-cloud-agent-runs/) * [Handoff between local and cloud agents](/platform/handoff/) - Move work off your laptop into a cloud agent run when you need longer-running or unattended execution. * [How to run multiple AI coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) - Run parallel CLI agents locally, then monitor or fan work out further. # Rich input editor Canonical page: [/agents/cli-agents/rich-input/](https://docs.warp.dev/agents/cli-agents/rich-input/) > Warp's rich input editor gives you IDE-style editing, voice input, context attachment, and slash commands for any supported CLI coding agent. Warp’s rich input editor lets you write prompts for any CLI coding agent with the same editing experience you’d expect from an IDE — mouse support, context attachment, voice, and more. Press `Ctrl-G` (configurable) or click the **Rich Input** button in the agent utility bar to open it.  ## Key capabilities [Section titled “Key capabilities”](#key-capabilities) * **IDE-style editing** - Click, select, and navigate your prompt with your mouse. Copy, cut, paste, undo, and word-level navigation all work. Write multi-line prompts with line breaks and soft wrapping. Vim keybindings are also supported. See [Modern text editing](/terminal/editor/) for the full list of shortcuts. * **Rich context with @mentions** - Reference files, folders, and code symbols with `@` mentions. Attach images for visual context. Search for specific symbols directly from the editor. See [Agent Context](/agents/local-agents/agent-context/) for details. * **Voice input** - Dictate prompts instead of typing. See [Voice](/agents/local-agents/interacting-with-agents/voice/) for details. * **Slash commands and skills** - Access saved `/prompts`, `/skills`, and [Warp Drive](/knowledge-and-collaboration/warp-drive/) content with `/`. The editor shows skills specific to the running agent’s provider (e.g., Claude-specific skills when running Claude Code). See [Slash Commands](/agents/capabilities/slash-commands/) for details. * **Agent toolbar** - Browse files, view code changes, and manage the agent session from the toolbar. ## How to open [Section titled “How to open”](#how-to-open) There are two ways to open the rich input editor: 1. **Keyboard shortcut** - Press `Ctrl-G` (configurable) while a supported agent is running in the active pane. 2. **Rich Input button** - Click the **Rich Input** button in the agent utility bar at the bottom of the pane.  The Rich Input button in the agent utility bar. The rich input editor also auto-opens when an agent resumes from a blocked state (for example, after you approve a command). This requires the agent’s plugin to be supported and installed. Toggle **Auto show/hide based on agent status** in [Rich input settings](#rich-input-settings) to control this behavior. When the rich input editor is active, Warp hides the cursor inside the CLI agent and moves focus to the editor input. Submit your prompt from here and it goes directly to the running agent.  The rich input editor. ## Rich input settings [Section titled “Rich input settings”](#rich-input-settings) In the Warp app, go to **Settings** > **Agents** > **Third party CLI agents** to configure the following: * **Auto show/hide based on agent status** - Automatically open the rich input editor when the agent needs input, and hide it when the agent is working. Works with agents that have plugin support and the plugin installed (Claude Code and OpenCode). * **Auto open on session start** - Automatically open the rich input editor when a CLI agent session starts. * **Auto dismiss after submission** - Close the editor after you send a prompt. * **Keyboard shortcut** - The default shortcut is `Ctrl-G`. Customize this in **Settings** > **Keyboard shortcuts**. * **Disable the Rich Input button** - Right-click the agent utility bar and remove the **Rich Input** chip, or disable the footer entirely in **Settings** > **Agents** > **Third party CLI agents**.  Rich input settings in Warp. ## Related pages [Section titled “Related pages”](#related-pages) * [Third-party CLI agents overview](/agents/cli-agents/overview/) * [Remote Control](/agents/cli-agents/remote-control/) * [Voice](/agents/local-agents/interacting-with-agents/voice/) * [Slash Commands](/agents/capabilities/slash-commands/) * [Agent Context](/agents/local-agents/agent-context/) # Agent conversations in the Warp Agent CLI Canonical page: [/agents/cli/agent-conversations/](https://docs.warp.dev/agents/cli/agent-conversations/) > Read, manage, and resume agent conversations in the Warp Agent CLI, including streamed responses, tool calls, file diffs, plans, and task lists. When you send the agent a prompt in the Warp Agent CLI, the conversation appears as a scrollable transcript directly in your terminal. Responses stream in as they’re generated, and everything the agent does renders inline: tool calls, file diffs, questions, task lists, and plans. Conversations persist as you work. You can start a new conversation, browse history, compact context, and [resume after exiting](#resuming-conversations). ## The conversation transcript [Section titled “The conversation transcript”](#the-conversation-transcript) The agent’s response streams into the transcript below your prompt as it’s generated. Press `Ctrl+C` once to stop a response that’s still in progress. Responses render as formatted Markdown, including syntax-highlighted code blocks and tables. Be aware of a few terminal-specific caveats: Mermaid diagrams appear as their source in a code block, images show their alt text instead of rendering inline, and very long code blocks are truncated to keep the transcript responsive. ## Tool calls [Section titled “Tool calls”](#tool-calls) Every tool call the agent makes appears inline in the transcript, in the order it happens. Most render as a one-line status row with a state glyph and a label describing the action, like “reading a file” or “searching your codebase”. Some tool calls render richer, interactive content: * **[Shell commands](/agents/cli/input-and-shell-commands/#shell-mode)** - Commands run in your session, with output streamed into the transcript. * **[File edits](#code-diffs)** - Expandable diffs with per-file headers. * **[Questions](#agent-questions)** - Interactive option prompts. * **[Plans](#planning)** - Inline plan documents. When a tool call needs your approval before it runs, an approval card appears in place of the input. See [permissions in the CLI](/agents/cli/permissions-and-profiles/) to learn how approvals work. ## Code diffs [Section titled “Code diffs”](#code-diffs) When the agent edits files, the edit renders as a diff in the transcript: * **Per-file sections** - Each edited file gets its own header showing the action taken and the lines added or removed. * **Multi-file edits** - Each file’s section nests, indented, under one collapsible summary header (for example, `Edited 3 files`). Diffs are fully expanded while the agent waits for your approval, then collapse to their headers once the edits are applied. Press `E` while the approval card is active to expand or collapse all diffs at once. The CLI renders diffs inline rather than in a separate editor. For how agent-generated changes work in the Warp app, including refining a diff in natural language, see [Agent code diffs and review](/agents/local-agents/code-diffs/). ## Thinking blocks [Section titled “Thinking blocks”](#thinking-blocks) For models that expose their reasoning, the agent’s thinking streams into a collapsible section with the header `Thinking...`, which collapses to a single `Thought for` row once it finishes. ## Agent questions [Section titled “Agent questions”](#agent-questions) When the agent needs a decision from you mid-task, it asks a question with an interactive option list that temporarily replaces the input. Use the arrow keys to navigate between options, or press an option’s number on your keyboard to select it. **Other…** accepts a free-form answer when the listed options don’t fit. Options the agent suggests as the best fit are labeled `(recommended)`. For multi-select questions, chosen options are marked with a check mark so you can select more than one. When the agent asks several questions at once, the card advances through them. To control whether the agent pauses to ask questions, see [Agent questions](/agents/local-agents/interacting-with-agents/agent-questions/). ## Task lists [Section titled “Task lists”](#task-lists) For multi-step work, the agent tracks its progress with a task list rendered directly in the transcript under a `≡ Tasks` header. Each task row starts with a status glyph: * `◌` - Pending * `●` - In progress * `✓` - Completed Canceled tasks appear struck through. As the agent finishes tasks, compact confirmation rows (e.g., `✓ Completed (2/5)`) track progress without repeating the whole list. Task lists in the CLI reflect the same agent behavior as in the Warp app. Learn more about [how task lists work](/agents/capabilities/task-lists/). ## Planning [Section titled “Planning”](#planning) To have the agent first research and produce a plan before making changes, use the `/plan` slash command followed by a description of your task. You can also ask for a plan in natural language. The plan renders inline in the transcript as a formatted document with its own header row showing the plan’s status. An `Updated plan` entry appears when the agent revises it. Press `Ctrl+Shift+P` to expand or collapse the latest plan. Planning in the CLI follows the same workflow as the Warp app. See [Planning](/agents/capabilities/planning/) to learn how to create, review, and execute plans. ## Selecting and copying output [Section titled “Selecting and copying output”](#selecting-and-copying-output) Select text anywhere in the transcript by clicking and dragging with the mouse. Releasing the mouse button copies the selection automatically. To copy an entire conversation as Markdown, use the `/export-to-clipboard` slash command, or use `/export-to-file` to save it to a file. Note In local sessions, the CLI writes directly to your system clipboard. Over SSH, it copies through your terminal using OSC 52 escape sequences (including from inside tmux), so the text lands on your local clipboard. Terminals that disable OSC 52 may ignore the copy. ## Managing conversations [Section titled “Managing conversations”](#managing-conversations) The CLI saves every agent conversation as you work, so closing your terminal won’t lose your progress. ### Conversation persistence [Section titled “Conversation persistence”](#conversation-persistence) The CLI shows one conversation at a time. Opening a past conversation replaces the current transcript, and the previous one remains available in history. You can’t switch conversations while the current conversation is responding or a command is running. Finish or stop it with `Ctrl+C` first. Conversations sync to your Warp account, so the same history is available in the Warp app and on your other devices. See [Cloud-synced conversations](/agents/local-agents/cloud-conversations/) for details about syncing, restoring, and sharing work. ### Starting a new conversation [Section titled “Starting a new conversation”](#starting-a-new-conversation) Use any of these slash commands to clear the transcript and start a fresh conversation: * `/new` * `/agent` * `/clear` Each command accepts an optional prompt. For example, `/new write tests for the parser` starts a new conversation and immediately sends that prompt to the agent. To keep the history but reduce its size instead, use [`/compact`](#compacting-context). For guidance on when to start fresh rather than follow up, see [Interacting with agents](/agents/local-agents/interacting-with-agents/). ### Conversation history [Section titled “Conversation history”](#conversation-history) To browse and reopen past conversations, you can open the conversation menu in two ways: * **`/conversations`** - Run the slash command from the input. * **`←`** - Press the left arrow key when the input is empty and the cursor is at the start. The menu lists your Warp Agent conversations, including conversations started in the Warp app and completed cloud agent runs tied to your account. Start typing to filter the list by title. Caution If the CLI can’t load conversation data from Warp’s servers, the menu shows conversations from your local device only and displays a warning. Conversations from other devices reappear once the connection recovers. To continue a cloud agent run from the CLI, or to hand the current conversation off to a cloud agent, see [cloud handoff and orchestration](/agents/cli/cloud-and-orchestration/). ### Resuming conversations [Section titled “Resuming conversations”](#resuming-conversations) There are two ways to pick a past conversation back up: * **The [conversation menu](#conversation-history)** `(recommended)` - From a running session, press `←` or run `/conversations`, then filter to the conversation you want. * **`warp --resume`** - Reopens a specific conversation from your shell as the CLI starts, without going through the menu. When you exit the CLI with a non-empty conversation, it prints the `--resume` command for that conversation: ```bash To continue this conversation, run: warp --resume YOUR_CONVERSATION_TOKEN ``` `YOUR_CONVERSATION_TOKEN` is a conversation identifier generated by Warp. For the complete list of command-line flags, see the [CLI reference](/agents/cli/reference/). ### Compacting context [Section titled “Compacting context”](#compacting-context) Long conversations eventually fill the model’s [context window](/agents/local-agents/interacting-with-agents/#context-window-management), which can degrade response quality. The `/compact` command frees up context by asking the agent to summarize the conversation history so far and carry only the summary forward. * **`/compact`** - Summarizes the conversation history with default instructions. * **`/compact `** - Adds custom summarization instructions. For example, `/compact keep the API design decisions` tells the agent what to preserve in the summary. After compaction, a collapsed **Conversation summary** block appears in the transcript, and the conversation keeps working normally with the summary standing in for the compacted history. ## Related pages [Section titled “Related pages”](#related-pages) * [Permissions and profiles](/agents/cli/permissions-and-profiles/) - Approve, reject, or auto-approve the agent’s tool calls. * [Input and shell commands](/agents/cli/input-and-shell-commands/) - How commands the agent (or you) run appear in the transcript. * [Cloud handoff and orchestration](/agents/cli/cloud-and-orchestration/) - Hand off conversations to cloud agents and resume cloud runs. * [Warp Agent CLI reference](/agents/cli/reference/) - Command-line flags, slash commands, and keyboard shortcuts. * [Planning](/agents/capabilities/planning/) - The full planning workflow. * [Task lists](/agents/capabilities/task-lists/) - How agents create and update task lists. * [Agent code diffs and review](/agents/local-agents/code-diffs/) - Reviewing and refining agent-generated changes. * [Cloud-synced conversations](/agents/local-agents/cloud-conversations/) - How conversations sync, restore, and share across devices. # Cloud handoff and orchestration in the Warp Agent CLI Canonical page: [/agents/cli/cloud-and-orchestration/](https://docs.warp.dev/agents/cli/cloud-and-orchestration/) > Hand off Warp Agent CLI conversations to cloud agents, resume cloud runs, and run multi-agent orchestration from your terminal. The Warp Agent CLI connects your terminal sessions to the Automation Platform. You can hand off a local conversation to a cloud agent, pick a finished cloud run back up in your terminal, and coordinate multiple agents working in parallel, all without leaving the CLI. ## Hand off to a cloud agent [Section titled “Hand off to a cloud agent”](#hand-off-to-a-cloud-agent) Handoff promotes your Warp Agent CLI conversation into a cloud agent run. Use it when a task outgrows your machine: long-running work you don’t want to keep your laptop awake for, or work you want to check on later from another device. The [Handoff overview](/platform/handoff/) explains the feature across all Warp surfaces. This section covers the CLI flow. The cloud agent receives the same context as a handoff from the Warp app: * **Conversation history** - Warp forks the conversation, so the cloud agent sees the full transcript and your local conversation stays untouched. * **Workspace changes** - Warp snapshots your uncommitted repository changes, including untracked files, and applies them in the cloud run. * **Pending input** - The optional follow-up prompt and any images attached to the input move to the cloud run. See [what carries over](/platform/handoff/#what-carries-over) for the full behavior, and [Handoff from local to cloud](/platform/handoff/local-to-cloud/) for prerequisites. ### Hand off a conversation [Section titled “Hand off a conversation”](#hand-off-a-conversation) 1. In an active conversation, run `/handoff`, or `/handoff ` to give the cloud agent a follow-up prompt. The **Hand off to cloud** card replaces the input area while your transcript stays visible. 2. The card suggests your most recent environment (preferring one that contains the current repository) and preselects your conversation’s current model if it can run in the cloud. If the model is incompatible, it’s flagged so you can choose another before continuing. 3. To open the searchable environment and model selectors, press `Ctrl+E`. 4. From the card summary, press `Enter` to hand off. The card shows progress, then reports that the cloud run was created along with a link to the run. Press `Ctrl+C` at any point before confirming to cancel the handoff. Your prompt and attachments return to the input. From the created card: * **`Enter`** - Opens the cloud run in your browser. * **`C`** - Continues the conversation locally. The card collapses into a transcript banner with the run link, and the input reopens. * **`N`** - Starts a new conversation. Note If you don’t have a cloud environment yet, the card prompts you to create one: `Enter` opens the [Environments page](https://oz.warp.dev/environments) in the Oz web app, and `R` refreshes the list after you create one. Handoff needs the conversation in a state it can fork. You can’t hand off while a command is still running, or while the conversation has child agents that are in progress or blocked. Cancel the command or let the children finish first. Handing off an orchestrator forks only its own conversation. The orchestration and its child agents stay local. ## Resume cloud conversations [Section titled “Resume cloud conversations”](#resume-cloud-conversations) There are two ways to pick up a cloud agent’s work: * **In the browser** - Open the run in the Oz web app to review its transcript and changes, steer it, or continue the conversation there. [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) covers that flow. * **In the CLI** - Pull a finished cloud run into your terminal. It appears in the conversation history alongside local conversations. Press `←` in an empty input, or run `/conversations`, to open the conversation list, then select the cloud run. Your next prompt continues the conversation locally. Resuming in the CLI has two constraints: * **The run must be finished** - Cloud runs that are still in progress or blocked can’t be opened in the CLI. * **Warp Agent runs only** - Conversations that ran with a different harness, such as Claude Code or Codex, can’t be opened in the CLI. You can also open a conversation directly at startup with `warp --resume `. See [managing conversations in the CLI](/agents/cli/agent-conversations/#managing-conversations) to learn more about conversation history and resume details. ## Multi-agent orchestration [Section titled “Multi-agent orchestration”](#multi-agent-orchestration) Orchestration lets one conversation spawn child agents that work in parallel, on your machine or in the cloud. The CLI runs the same parent/child model as the rest of the platform. [Multi-agent orchestration](/platform/orchestration/) covers the model, run states, and common patterns. To start an orchestration, ask the agent to parallelize the work, for example “split this migration across three agents”. You can also shape the configuration in your prompt. For example, ask for a specific model to manage token spend: keep the parent on a premium model while child agents handle research on a cheaper open-source model. When the agent decides to spawn child agents, the CLI shows an approval card titled **Can I start additional agents for this task?** that summarizes the agents it wants to launch and the run-wide configuration. By default, no child agents launch until you approve. The **Run orchestrated agents** permission in your profile controls this: **Always allow** skips the approval card, and **Never** blocks child agents entirely. See [Permissions and profiles](/agents/cli/permissions-and-profiles/). From the approval card: * **`Enter`** - Approves the request and launches the child agents. * **`Ctrl+E`** - Edits the configuration first: where the agents run (on your machine or in the cloud) and which model they use. Cloud agents add pages for the harness, environment, and host, plus an API key page for harnesses that need one. * **`Ctrl+C`** - Rejects the request. After launch, a tab bar labeled **Agents:** appears above the session with one tab for the orchestrator and one tab per child agent. Messages between the parent and child agents appear in each agent’s transcript.  The Agents: tab bar with one child agent running and two finished. * **Local child agents** - Each local child runs on your machine as its own session, starting in the parent’s working directory. Local children always run the Warp Agent. * **Cloud child agents** - Each cloud child runs in a cloud [environment](/platform/environments/), and can run a different harness than the parent, such as Claude Code or Codex, chosen on the approval card’s harness page. A cloud child’s session shows the run’s live status and a link. Press `Enter` or click the link to open the run in the Oz web app. If a cloud child can’t start because GitHub authentication is required, its session shows the authentication link. Authenticate, then ask the agent to run the orchestration again. Caution Cloud child sessions in the CLI only show status. They don’t accept input. To send prompts to a cloud child or respond to its approvals, open the run in the Oz web app. ## Managing child agents [Section titled “Managing child agents”](#managing-child-agents) The **Agents:** tab bar is how you move around an orchestration. * **Focus the tab bar** - Press `Shift+↑` from the input. The bar highlights the active conversation. * **Switch agents** - `Tab` or `→` selects the next agent and `Shift+Tab` or `←` the previous one, wrapping across the orchestrator and all children. Switching keeps the bar focused so you can keep cycling. * **Jump to an end** - `Shift+←` selects the first child and `Shift+→` selects the last one. * **Return to the conversation** - `↓` moves focus back to the current session’s input. `Esc` jumps back to the orchestrator. * **Use the mouse** - Tabs are clickable, and when there are more children than fit, arrows at the ends of the bar page through them without changing your selection. Each agent keeps its own session. Transcript position, input drafts, and running work are all preserved while you view another agent, and child agents keep working in the background. Tabs reorder as statuses change, moving children that need attention, such as blocked ones, toward the front of the bar. A focused local child behaves like a regular conversation. You can send it follow-up prompts and respond to its permission requests. If a child’s tab shows a blocked status, switch to that child to respond to its pending request. ### Kill a child agent [Section titled “Kill a child agent”](#kill-a-child-agent) `Ctrl+C` kills a child agent. It stops the child’s work, cancels the cloud run if the child is a cloud agent, and removes the child’s tab and conversation, returning you to the orchestrator. * **From the tab bar** - With the tab bar focused and a child tab selected, a single `Ctrl+C` kills the selected child. The footer shows `Ctrl+C to kill sub-agent` as a reminder. * **While viewing a child** - Press `Ctrl+C` twice. The first press arms a short confirmation window and the footer shows `ctrl-c again to kill child agent`. A second press within the window kills the child. In the orchestrator’s own session, `Ctrl+C` keeps its usual behavior. ## Related pages [Section titled “Related pages”](#related-pages) * [Handoff overview](/platform/handoff/) - Directions of handoff and what carries over in each. * [Handoff from local to cloud](/platform/handoff/local-to-cloud/) - Prerequisites, the Warp app flow, and troubleshooting. * [Multi-agent orchestration](/platform/orchestration/) - The parent/child model, run states, and orchestration patterns. * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Open, inspect, and continue cloud runs in the Oz web app. * [Agent conversations in the CLI](/agents/cli/agent-conversations/#managing-conversations) - Conversation history, `/conversations`, and `--resume`. * [Environments](/platform/environments/) - Configure the repos, image, and setup commands cloud agents run with. # Customizing the Warp Agent CLI Canonical page: [/agents/cli/configuration/](https://docs.warp.dev/agents/cli/configuration/) > Configure Warp Agent CLI themes, the statusline, and the start screen, and give the agent context from project rules, skills, and MCP servers. The Warp Agent CLI keeps its configuration in a plain TOML settings file on your machine. You can change settings by editing the file directly, by running slash commands like `/theme` and `/statusline`, or by asking the agent to update a setting for you. Beyond the CLI’s own settings, this page also covers the agent’s context, which includes the project rules, skills, and MCP servers the agent picks up as you work. ## The settings file [Section titled “The settings file”](#the-settings-file) The CLI reads its settings from a `settings.toml` file: * **macOS** - `~/.warp_cli/settings.toml` * **Linux** - `~/.config/warp-terminal/cli/settings.toml` (respects `$XDG_CONFIG_HOME`) * **Windows** - `%LOCALAPPDATA%\warp\Warp\config\cli\settings.toml` The file is created the first time you change a setting, and you can also create it yourself. Settings use dotted TOML sections. For example: settings.toml ```toml [appearance] theme = "dark" ``` Note CLI settings are local to your machine and are never synced to the cloud. They are also independent from the Warp app’s settings: the app and the CLI keep separate settings files, so changing one never affects the other. ## Edit settings [Section titled “Edit settings”](#edit-settings) Change settings any of these ways: ### Edit the file directly [Section titled “Edit the file directly”](#edit-the-file-directly) Open the settings file in your editor and change values directly. The CLI watches the file while it’s running and reloads most values as you save, so edits take effect without a restart. Theme edits are the exception: they apply the next time you run `/theme` or restart the CLI. If a value is invalid, the CLI logs the problem and uses the default for that setting instead. If the file can’t be parsed at all, the CLI starts with default settings. ### Use slash commands [Section titled “Use slash commands”](#use-slash-commands) Commands like `/theme` and `/statusline` open interactive panels for specific settings and save your choice to the settings file automatically. See [Themes](#themes) and [Statusline](#statusline). ### Ask the agent [Section titled “Ask the agent”](#ask-the-agent) Describe the change to the agent in your CLI session, in plain language. The CLI ships with a bundled skill and a schema of every available setting, which the agent uses to find the right key, validate the value, and update the settings file for you. Try prompts like: * “Switch my theme to light.” * “Add the time to my [statusline](#statusline).” * “What CLI settings can I change?” The agent’s edits follow the same hot-reload behavior as editing the file directly (see [Edit the file directly](#edit-the-file-directly)). For the full list of built-in skills, see [Bundled skills](#bundled-skills). ## Themes [Section titled “Themes”](#themes) The CLI renders with a light or dark color theme. Set it with the `/theme` slash command: * **`/theme auto`** - Matches the host terminal’s background (default). * **`/theme light`** - Always uses the light theme. * **`/theme dark`** - Always uses the dark theme. Running `/theme` applies the change immediately and persists it across sessions as the `theme` key under `[appearance]` in the settings file. In auto mode, detection runs at startup, so if you switch your terminal’s colors while the CLI is running, restart it or set a theme explicitly. ## Statusline [Section titled “Statusline”](#statusline) The statusline is the row below the CLI’s input box that shows session information at a glance. By default it shows the auto-approve indicator, the active model, the working directory, the Git branch, and the Git diff status inside a repository, plus the Vim mode indicator when Vim mode is on. You can enable any of these items:  The statusline with credit usage, context window usage, and task list chips enabled. * **Auto-approve indicator** - A clickable `▶▶` toggle for auto-approve, highlighted when it’s on. * **Vim mode indicator** - The active Vim mode (such as `NOR` or `INS`), shown only when Vim mode is enabled. * **Model** - The active model. Click it to open the model picker. * **Working directory** - The current working directory. * **Git branch** - The current branch, when the directory is a Git repository. * **Git branch status** - The branch, plus how far it is ahead of or behind its upstream (for example, `master • ↑1`). Enabling this replaces the plain Git branch chip, rather than adding a second one. * **Git diff status** - Files changed, with line additions and deletions. * **GitHub pull request** - The pull request for the current branch. Click it to open the PR on GitHub. * **Credit usage** - Credits used by the current conversation. Click it to switch between credits and provider cost. * **Context window usage** - How much of the model’s context window the conversation has used. * **Agent to-do list** - The agent’s progress through its current task list. You can also add the date, the time (12- or 24-hour), and a voice input control. Items only appear when they have something to show. For example, the Git items appear only inside a repository. In shell mode, the statusline always leads with a shell mode label. ### Customizing the statusline [Section titled “Customizing the statusline”](#customizing-the-statusline) Choose which items appear and in what order: 1. Run `/statusline`. The **Configure statusline** panel opens with every available item. 2. Select an item and press `Enter` to toggle its visibility. 3. Press `←` and `→` to move the highlighted item earlier or later in the row. 4. Press `Esc` to save and close. Press `Ctrl+C` to cancel without saving. Your choices are saved to the settings file, so the layout persists across sessions. To start over, run `/reset-statusline`, which restores the default items and ordering. ## Start screen [Section titled “Start screen”](#start-screen) The start screen appears when you launch the CLI, showing a rotating ASCII object alongside sections for your account, the changelog, project info, and MCP servers. Customize it with the `appearance.zero_state` settings: * **`object`** - The rotating object. Keep the built-in one, or point the setting at your own ASCII art file (a path relative to the CLI settings directory). Changing the setting reloads the object. Edits to the linked file take effect after a restart. * **`rotation_period_seconds`** - Seconds per full rotation, from 1 through 60. * **`show_signed_in_user`, `show_changelog`, `show_project_info`, `show_mcp`, `show_animation`** - Toggle individual start-screen sections. * **`freeze_animation_when_unfocused`** - Stop repainting the animation while your terminal window is unfocused, so an idle start screen doesn’t use CPU in the background. Off by default, and applied as soon as you save the setting. The fastest way to change these is to [ask the agent](#ask-the-agent), for example “use my own ASCII art for the start screen object”. ## Project context and rules [Section titled “Project context and rules”](#project-context-and-rules) The CLI gives its agent the same layered context system as the Warp app, combining your working directory, project rules, skills, and MCP servers, all scoped to the directory you’re working in. The agent works in your session’s current directory. When you `cd`, project rules and skills re-scope to the new directory automatically. Within a project, the CLI picks up the same rule files as the Warp app: * **Project rules** - `AGENTS.md` (or `WARP.md`) files in your repository apply automatically, starting from the repository root and your current directory. See [Rules](/agents/capabilities/rules/) for the file format, nested rules in subdirectories, and precedence. * **Global rules** - A rule file at `~/.agents/AGENTS.md` applies across all projects on your machine. Because rules and skills come from the same shared locations, a repository already configured for agents in the Warp app (or any tool that reads `AGENTS.md`) works in the CLI immediately. ## Skills [Section titled “Skills”](#skills) [Skills](/agents/capabilities/skills/) are reusable instruction sets the agent can invoke to perform specific tasks. The CLI discovers the same skills as the Warp app. Project skills come from your repository’s skill directories (e.g., `.agents/skills/`), and personal skills come from your home directory (e.g., `~/.agents/skills/`), scoped to your current working directory. Run `/skills` to browse every skill in scope. Selecting a skill inserts `/skill-name` into the input so you can add extra instructions before running it. Any text after the skill name is passed along, either as [skill arguments](/agents/capabilities/skills/#skill-arguments) or as additional context for the agent. You can also invoke a skill directly by typing `/` followed by its name, for example `/deploy push the latest changes to staging`. ### Bundled skills [Section titled “Bundled skills”](#bundled-skills) The CLI ships with built-in skills that appear in the skills menu alongside your own: * **`/modify-settings`** - Updates CLI settings using the bundled settings schema to find and edit the right key. See [Ask the agent](#ask-the-agent). * **`/tui-migrate-setup`** - Sets up the CLI from an existing Warp app installation. The agent copies compatible settings and global MCP server definitions from the app, and asks for approval before changing anything. Credentials and OAuth state are never copied, so MCP servers that require authentication prompt you to re-authenticate. Rules and skills don’t need migration: the CLI and the Warp app both discover them from the same file locations (see [Project context and rules](#project-context-and-rules) and [Skills](#skills)). ## MCP servers [Section titled “MCP servers”](#mcp-servers) [MCP servers](/agents/capabilities/mcp/) extend the agent with external tools and data sources. The CLI keeps its own MCP server configuration, separate from the Warp app’s, so each can run its own set of servers. Servers are defined in a JSON config file using the same `mcpServers` format as [file-based MCP servers](/agents/capabilities/mcp/#file-based-mcp-servers) in the Warp app (on macOS, the file is `~/.warp_cli/.mcp.json`). Edit the file to add or remove servers. The CLI picks up changes automatically. Configured servers start automatically once you’re logged in. Note The CLI reads MCP servers from its global config file only. Project-scoped MCP config files in repositories are not detected. To copy global server definitions from the Warp app, use the `/tui-migrate-setup` bundled skill. ### Managing servers with `/mcp` [Section titled “Managing servers with /mcp”](#managing-servers-with-mcp) Type `/mcp` to open the MCP management view. The header shows the path to the config file the CLI is reading. Each configured server is listed with its transport (`stdio` or `HTTP/SSE`) and current status, including the number of tools a running server exposes. Press `Enter` on a server to start, stop, or retry it depending on its state. Failed rows show the error message. Servers awaiting authentication reopen the OAuth page in your browser, and servers with saved credentials show a **Log out** row that clears them. ## Related pages [Section titled “Related pages”](#related-pages) * [Rules](/agents/capabilities/rules/) - Full guide to project and global rules. * [Skills](/agents/capabilities/skills/) - Authoring skills, skill arguments, and skill locations. * [MCP servers](/agents/capabilities/mcp/) - Config format, server examples, and authentication. * [Codebase Context](/agents/capabilities/codebase-context/) - Codebase indexing in the Warp app. * [Warp Agent CLI reference](/agents/cli/reference/) - Command-line flags, slash commands, and keyboard shortcuts. # Input and shell commands in the Warp Agent CLI Canonical page: [/agents/cli/input-and-shell-commands/](https://docs.warp.dev/agents/cli/input-and-shell-commands/) > Compose prompts, edit input, and run shell commands in the Warp Agent CLI, including menus, history, completions, images, voice, and interactive commands. The Warp Agent CLI is a full terminal as well as an agent. Every session runs a real shell, so you can run commands in the same place you prompt the agent. The input is a multiline editor that combines readline-style editing with inline menus for slash commands, history, and completions, plus mouse support, image attachments, and voice input. For the complete list of flags, slash commands, and keyboard shortcuts, see the [Warp Agent CLI reference](/agents/cli/reference/). ## Editing basics [Section titled “Editing basics”](#editing-basics) The input is a multiline editor. * **Insert a newline** - Press `Ctrl+J`, or `Shift+Enter` in terminals that support distinguishing it. `Alt+Enter` also works. * **Edit with readline-style keys** - The editor supports familiar bindings such as `Ctrl+A` and `Ctrl+E` (start and end of line), `Ctrl+W` (delete the previous word), `Ctrl+K` and `Ctrl+U` (delete to the end or start of the line), `Ctrl+Y` (reinsert the last deleted text), and `Ctrl+Z` (undo). * **Use macOS Command shortcuts** - When the Kitty keyboard protocol is enabled in your terminal, the editor supports Command-modified shortcuts such as `⌘+X` to cut and `⌘+Shift+←` or `⌘+Shift+→` to extend the selection. The full editing and selection table is in the [keyboard shortcuts reference](/agents/cli/reference/#keyboard-shortcuts). Note Core `Ctrl` and `Alt` bindings are cross-platform. Shortcuts that use `Alt` require some macOS terminals’ Option-as-Alt (Meta) setting. Command-modified shortcuts require a terminal with the Kitty keyboard protocol enabled. ### Vim mode [Section titled “Vim mode”](#vim-mode) If you prefer modal editing, run `/vim-mode` to toggle Vim keybindings in the input. The setting persists across sessions. Turn on the [statusline](/agents/cli/configuration/#statusline) Vim mode item to see the active mode (such as `NOR` or `INS`) while you type. ## Slash commands [Section titled “Slash commands”](#slash-commands) Type `/` at the start of an empty input to open the slash command menu. Entries for toggles and pickers show their current state, for example `/theme (currently auto: Dark)` or `/auto-approve (currently off)`. When a command takes an argument, the input shows a ghost-text argument hint after the full command name, for example `/theme `. Your [skills](/agents/cli/configuration/#skills) also appear in the slash command menu, so you can invoke a skill by typing `/` followed by its name. The [slash commands reference](/agents/cli/reference/#slash-commands) lists every command. ## Input history [Section titled “Input history”](#input-history) Press `↑` with the cursor on the first row of the input to open the history menu. * **What’s listed** - In Agent Mode, the menu combines your previous prompts and shell commands in one list, with commands marked by a `!` prefix. In [shell mode](#shell-mode), the menu lists commands only. * **Preview** - Moving the selection previews each entry in the input and switches the input to the matching mode: recalled commands run as shell commands, and recalled prompts go to the agent. * **Submit** - `Enter` runs the selection immediately. It doesn’t insert it for editing. * **Dismiss** - `Esc` restores what you had typed. Pressing `↓` past the newest entry does the same. ## Tab completions [Section titled “Tab completions”](#tab-completions) In [shell mode](#shell-mode), press `Tab` to complete the command you’re typing, including file and directory paths. * If exactly one completion matches, the CLI applies it immediately. * If several completions match, the CLI inserts the longest shared prefix and opens a completion menu. Press `Tab` again to cycle through the suggestions. ## Selection and clipboard [Section titled “Selection and clipboard”](#selection-and-clipboard) * **Highlight to copy** - Finishing a mouse selection in the input or the [conversation transcript](/agents/cli/agent-conversations/) automatically copies it. * **Keyboard selection** - Extend the selection with `Shift` plus the arrow keys, or select everything with `Ctrl+Shift+A`. Copy with `Ctrl+Shift+C` and cut with `Ctrl+X`. * **Paste** - Press `Ctrl+V` or `Ctrl+Shift+V` (also `Alt+V` on Windows). Your terminal’s own paste shortcut works as well. * **Click controls** - Interactive elements such as the **Voice** footer entry and the attachment bar controls respond to clicks. Note Copying works over SSH: on remote sessions the CLI writes the clipboard through the OSC 52 escape sequence (including tmux passthrough), so your local clipboard receives the text when your terminal supports OSC 52. ## Attach images [Section titled “Attach images”](#attach-images) Attach images to a prompt so the agent can analyze them: * **Paste an image** - Copy an image to your clipboard and press `Ctrl+V`. * **Paste or drop a file path** - Paste the path to an image file, or drag the file onto your terminal window to insert its path. Absolute paths, paths relative to the working directory, and `~` paths all resolve. Supported formats are PNG, JPEG, GIF, and WebP. Attaching an image locks the input to Agent Mode, since images are sent to the agent rather than the shell. Attached images appear in an attachment bar above the input. Press `Tab` to focus the bar, `Backspace` to remove the selected attachment, and `Esc` to return to the input. ## Voice input [Section titled “Voice input”](#voice-input) Dictate prompts instead of typing them: Caution Voice input isn’t currently included in the official Linux build. Linux support is planned. 1. Start listening with `Ctrl+S`, the `/voice` slash command, or by clicking **Voice** in the footer. The footer shows **Listening** while recording. 2. Press `Enter`, or click the footer entry again, to stop recording. The transcribed text lands in the input so you can review and edit it before submitting. Press `Esc` while transcription is in progress to cancel it. `/voice` clears the input before recording, and `Ctrl+S` keeps what you’ve already typed. Voice input in the CLI uses the same transcription service as the Warp app. See [voice input for agents](/agents/local-agents/interacting-with-agents/voice/) for microphone setup, privacy, and usage limits. ## Keyboard hints and the shortcuts menu [Section titled “Keyboard hints and the shortcuts menu”](#keyboard-hints-and-the-shortcuts-menu) The CLI shows its shortcuts in context, so you rarely need to memorize them: * **Placeholder hints** - An empty input shows the key triggers for the current mode. * **Shortcuts menu** - Type `?` in an empty input to open a shortcuts overview. Its contents adapt to what you’re doing: Agent Mode lists the menu triggers and input history, shell mode shows how to return to Agent Mode, and extra sections appear during multi-agent sessions or agent-controlled terminal use. Press `Esc`, or start typing, to close it. ## Shell mode [Section titled “Shell mode”](#shell-mode) The input is agent-first: by default, pressing `Enter` sends your text to the agent as a prompt. Use shell mode to run a command instead: 1. Press `!` at the start of the input. The prompt marker changes from `>` to `!`, and the statusline below the input shows **Shell mode**. 2. Run a command. The input returns to Agent Mode afterward. To leave shell mode without running a command, press `Esc`, or press `Backspace` at the start of the input. Any text you typed stays in the input. In shell mode, press `Tab` to complete commands and paths. See [Tab completions](#tab-completions). Note Running a shell command cancels the agent’s in-progress response, if there is one. ## Natural language detection [Section titled “Natural language detection”](#natural-language-detection) Out of the box, the CLI never guesses what your input is: everything goes to the agent unless you enter shell mode. To type commands directly without the `!` prefix, turn on natural language detection: * **Toggle detection** - Run `/natural-language-detection` to turn detection on or off. The statusline confirms the change, and the setting persists across sessions. * **Automatic classification** - With detection on, the CLI classifies your input as you type. When the input looks like a shell command (for example, `git status`), the input switches to shell mode, and `Enter` runs it as a command. Everything else is sent to the agent. * **Ambiguous input** - Short or ambiguous input stays in Agent Mode, and a single word switches to shell mode only when it matches a command available in your shell. The prompt marker and statusline always show the current mode before you press `Enter`. If detection classifies input differently than you intended, press `Esc` to switch back to Agent Mode, or press `!` at the start of the input to force shell mode. ## Long-running and interactive commands [Section titled “Long-running and interactive commands”](#long-running-and-interactive-commands) When a command keeps running, such as a dev server, a package install, or an interactive prompt, the CLI hands input over to it: * **Input passthrough** - Keystrokes and pasted text are forwarded to the running process, so password requests, confirmation prompts, and other interactive programs work as they do in a plain terminal. * **Type ahead** - If you start typing your next command before the current one finishes, the typed characters are carried into the input when the command completes, with the cursor at the end. This matches type-ahead behavior in shells like zsh and bash. One command runs in the session at a time. If the terminal is already busy, for example while the agent is running a command of its own, submitting a shell command shows a notice in the statusline and keeps your text in the input. ## Full-screen terminal apps [Section titled “Full-screen terminal apps”](#full-screen-terminal-apps) Commands that switch the terminal to the alternate screen, such as `vim`, `htop`, or `less`, take over the whole CLI view: * The app renders full-screen and receives keyboard, paste, scroll, and mouse input, so editors and other terminal UIs are fully usable inside the CLI. * When the app exits, the transcript returns with your conversation intact. ## Stopping commands and exiting [Section titled “Stopping commands and exiting”](#stopping-commands-and-exiting) `Ctrl+C` performs one contextual action per press: * **While a command is running** - `Ctrl+C` interrupts the running command, as in a plain terminal. It doesn’t exit the CLI. * **While the agent is responding** - `Ctrl+C` cancels the in-progress response. Text in the input is preserved. * **At an idle prompt** - `Ctrl+C` clears the input if it has text. After a press at the prompt, the statusline shows `ctrl-c again to exit` for about one second. Press `Ctrl+C` a second time within that window to exit the CLI. This works even while the agent is responding. While a shell command is running, `Ctrl+C` keeps interrupting the command instead. There are two other ways to exit: * **`Ctrl+D`** - Exits immediately when the input is empty. * **`/exit`** - Exits from the slash command menu. When you exit, the CLI prints a command you can use to pick the conversation back up later. See [Managing conversations](/agents/cli/agent-conversations/#managing-conversations) for resuming and switching conversations. ## Related pages [Section titled “Related pages”](#related-pages) * [Warp Agent CLI reference](/agents/cli/reference/) - Flags, environment variables, slash commands, and keyboard shortcuts. * [Agent conversations in the Warp Agent CLI](/agents/cli/agent-conversations/) - The transcript, tool calls, diffs, and managing conversations. # Models and usage in the Warp Agent CLI Canonical page: [/agents/cli/models-and-usage/](https://docs.warp.dev/agents/cli/models-and-usage/) > Choose models in the Warp Agent CLI, bring your own API key, and track credit usage and per-response cost. The Warp Agent CLI gives you the same model options as the Warp app. You can pick the model that powers your conversations, bring your own provider API keys, route requests through custom model routers, and see what every response costs as you work. ## Choosing a model [Section titled “Choosing a model”](#choosing-a-model) Run `/model` to open the model picker. You can also click the model name in the [statusline](/agents/cli/configuration/#statusline) to open the same picker. Models that your plan or your team’s settings don’t allow appear disabled in the picker. Your choice is saved as the base model of your active profile, so it persists across sessions. See [permissions and profiles](/agents/cli/permissions-and-profiles/) for how profiles work in the CLI. For the full list of supported models and to learn more about how Warp’s Auto models pick for you, see [Model choice](/agents/inference/model-choice/). ## Bring your own API key [Section titled “Bring your own API key”](#bring-your-own-api-key) The CLI supports [Bring Your Own API Key (BYOK)](/agents/inference/bring-your-own-api-key/) for OpenAI, Anthropic, and Google models, and can connect an [X Premium or SuperGrok subscription](/agents/inference/grok-subscription/) for Grok models. When you select a model covered by one of your keys, requests are billed through your provider account and don’t consume your Warp [credits](/support-and-community/plans-and-billing/credits/). Run `/api-keys` to open the key management menu. It lists each provider with its connection state, plus a Warp credit fallback toggle: * **Set a key** - Press `Enter` on OpenAI, Anthropic, or Google and enter the key. Input is masked, so the key never appears in your transcript or shell history, and it’s saved to your device’s secure storage. Warp does not store provider keys on its servers. * **Replace or clear a key** - On a connected provider, `Enter` loads the stored key (still masked) for editing, and saving an empty field clears it. `Ctrl+X` clears the highlighted provider’s key from the list. * **Connect X Premium or SuperGrok** - Press `Enter` on the subscription row and the CLI opens your browser to sign in to your xAI account. `Ctrl+X` disconnects it. Running `/connect-grok` jumps straight to this row and starts the sign-in. * **Warp credit fallback** - Press `Enter` to toggle whether a request that fails through your key is retried with Warp credits. See [failover and fallback behavior](/agents/inference/bring-your-own-api-key/#failover-and-fallback-behavior). You can also store or clear keys outside a session with the `--set-provider-api-key` and `--clear-provider-api-key` flags. See the [Warp Agent CLI reference](/agents/cli/reference/#command-line-flags). X Premium/SuperGrok connections can only be managed from inside a session, with `/api-keys` or `/connect-grok`. Note Warp’s built-in Auto models always consume Warp credits, even with BYOK configured. To bill through your own account, select a specific provider model, or use a [custom router](/agents/inference/custom-routers/#using-your-own-api-keys-byok) whose targets your keys cover. See [BYOK usage and billing behavior](/agents/inference/bring-your-own-api-key/#byok-usage-and-billing-behavior) for the full rules. ## Custom model routing [Section titled “Custom model routing”](#custom-model-routing) [Custom routers](/agents/inference/custom-routers/) appear in the `/model` picker alongside individual models. Select one and each prompt resolves to a concrete model using the routing logic you defined. The CLI loads the same router definitions as the Warp app. These are YAML files in `~/.warp/custom_model_routers/`, plus any team-synced routers your admin shares. [Authoring a router as a file](/agents/inference/custom-routers/#author-a-router-as-a-file) documents the file format. ## Usage and cost [Section titled “Usage and cost”](#usage-and-cost) The CLI shows usage at three levels: * **Account usage** - Run `/usage` to open a read-only panel with your plan, credit balances and consumption, and links to manage billing or upgrade. Press `Esc` to close it. Unlike `/cost`, this is account-level, not conversation-level. * **Conversation total** - Once a conversation has reported any usage, the [statusline](/agents/cli/configuration/#statusline) shows its accumulated credits (e.g., `2.5 credits`). Click the entry to switch between credits and the equivalent provider cost in dollars. Your choice persists across sessions. * **Per-response details** - Run `/cost` to toggle a summary row under the latest response showing how long it took and how many credits it spent (e.g., `12s • 1.2 credits`). The summary appears once the response finishes. Credits are Warp’s unit of usage for agent requests. For what credits cover and how plans differ, see [Credits](/support-and-community/plans-and-billing/credits/). ## Related pages [Section titled “Related pages”](#related-pages) * [Model choice](/agents/inference/model-choice/) - Supported models and how automatic model selection works. * [Bring Your Own API Key](/agents/inference/bring-your-own-api-key/) - How BYOK works, key storage, and billing behavior. * [SuperGrok subscription](/agents/inference/grok-subscription/) - Use Grok models through your xAI account. * [Custom routers](/agents/inference/custom-routers/) - Define routing logic that picks a model per task. * [Warp Agent CLI reference](/agents/cli/reference/) - Flags and slash commands, including the API key commands. # Oz CLI reference Canonical page: [/agents/cli/oz-cli/](https://docs.warp.dev/agents/cli/oz-cli/) > Use the Oz CLI to run, configure, and manage agents from the terminal. Caution The Oz CLI (the `oz` binary, which previously shipped as `warp-cli`) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. The Oz CLI is the command-line tool for running and managing Warp’s cloud agents from any terminal, script, or CI pipeline. Use it to start agents locally or in the cloud, connect MCP servers, configure integrations, and authenticate without requiring the Warp desktop app. ## What is the CLI? [Section titled “What is the CLI?”](#what-is-the-cli) The Oz CLI is the command-line tool that lets you run [Cloud Agents](/platform/) from anywhere, including terminals, scripts, automated systems, or services. It’s the standard runtime entry point that turns a **prompt** plus **configuration** into an **executable agent task** that runs on either a **Warp-hosted or [self-hosted](/factories/self-hosting/) runner**. With the Oz CLI, you can: * Run agents locally for development and debugging * Run agents on remote machines * Connect agents to MCP servers like GitHub and Linear * Configure integrations that connect agents to Slack, Linear, and other trigger surfaces ## Installing the CLI [Section titled “Installing the CLI”](#installing-the-cli) You can install the Oz CLI as part of the Warp desktop app, or as a standalone package. ### Bundled with Warp [Section titled “Bundled with Warp”](#bundled-with-warp) The Oz CLI is automatically distributed with the Warp desktop app and can be used right away in Warp. To make the CLI globally available, add it to your `PATH`. * macOS To add the Oz CLI to your `PATH`: 1. Open the [Command Palette](/terminal/command-palette/) (`Cmd+P`) 2. In the search field, find and select the **Install Oz CLI Command** action. Note **Note:** Administrator permissions are required to install the CLI into `/usr/local/bin` . * Windows In the Warp installer, select **Add Warp to PATH**. If you are installing for all users, this will put the CLI on the system path. Otherwise, the CLI is only added to the path for your account. * Linux To run the Oz CLI on Linux, use the same command that you’d use to start Warp normally. If you installed Warp via a package manager, it should already be on the system `PATH`. ### Standalone package [Section titled “Standalone package”](#standalone-package) Warp provides standalone packages for the CLI on macOS and Linux, without the Warp app. * macOS On macOS, we recommend that you install and update the standalone CLI with [Homebrew](https://brew.sh/), using the [`warpdotdev/warp` tap](https://github.com/warpdotdev/homebrew-warp): ```sh $ brew tap warpdotdev/warp $ brew update $ brew install --cask oz ``` If you’re using Warp Preview, install the preview version of the CLI instead: ```sh brew install --cask oz@preview ``` *** You can also download the CLI directly from these URLs: * [Apple Silicon](https://app.warp.dev/download/cli?os=macos\&package=tar\&arch=aarch64) * [Intel](https://app.warp.dev/download/cli?os=macos\&package=tar\&arch=x86_64) * [Apple Silicon, Warp Preview](https://app.warp.dev/download/cli?os=macos\&channel=preview\&package=tar\&arch=aarch64) * [Intel, Warp Preview](https://app.warp.dev/download/cli?os=macos\&channel=preview\&package=tar\&arch=x86_64) Note **Note:** These builds do not auto-update. * Linux On Linux, we recommend that you install and update the standalone CLI through your distribution’s package manager. We support `apt`, `yum`, and `pacman`. 1. Add the Warp package repository for your distribution (see the [installation instructions](/getting-started/quickstart/installation-and-setup/)). 2. Install either the stable or Preview package (replace `apt` with `yum` or `pacman` as needed): ```sh # Stable sudo apt install oz-stable # Preview (beta/early-access) sudo apt install oz-preview ``` Note **Note:** The package name (`oz-stable`) differs from the CLI command executable (`oz`). After installation, use the CLI via `oz` commands. *** You can also install the CLI by downloading a package directly. These installers automatically add the Warp repository, so future updates come through your package manager: * x86-64: [`.deb`](https://app.warp.dev/download/cli?os=linux\&package=deb\&arch=x86_64), [`.rpm`](https://app.warp.dev/download/cli?os=linux\&package=rpm\&arch=x86_64), [pacman](https://app.warp.dev/download/cli?os=linux\&package=pacman\&arch=x86_64) * aarch64: [`.deb`](https://app.warp.dev/download/cli?os=linux\&package=deb\&arch=aarch64), [`.rpm`](https://app.warp.dev/download/cli?os=linux\&package=rpm\&arch=aarch64), [pacman](https://app.warp.dev/download/cli?os=linux\&package=pacman\&arch=aarch64) * Windows A standalone CLI package is not currently available on Windows. To use the Oz CLI on Windows, install the Warp app, which bundles the CLI. You can install Warp using [WinGet](https://learn.microsoft.com/en-us/windows/package-manager/winget/): ```powershell winget install Warp.Warp ``` After installation, see [Bundled with Warp](#bundled-with-warp) for instructions on adding the CLI to your `PATH`. ## Running the CLI [Section titled “Running the CLI”](#running-the-cli) Regardless of your OS or installation method, the CLI command is `oz`. If you’re using [Warp Preview](/support-and-community/community/warp-preview-and-alpha-program/), use `oz-preview` instead. ## Logging in [Section titled “Logging in”](#logging-in) The Oz CLI supports two authentication methods, depending on where and how you’re running agents. * **Interactive login —** best for local machines where you have Warp installed and can authenticate through a browser. * **API keys** — best for automated or remote environments that need to authenticate without human interaction. ### Interactive login (local machines) [Section titled “Interactive login (local machines)”](#interactive-login-local-machines) Use interactive login when you’re working on a machine where you already use the Warp app, or when you can open a browser to complete authentication. If you use the CLI on a host where you’re already signed in to Warp, it automatically reuses your existing credentials. To authenticate interactively: ```bash oz login ``` The CLI prints out a URL that you can open in any browser to login to Warp. ### Checking who you’re signed in as [Section titled “Checking who you’re signed in as”](#checking-who-youre-signed-in-as) Use `oz whoami` to print information about the currently authenticated principal: ```sh oz whoami ``` The output includes your user or service account ID, display name, email, and team (when available). When the CLI is authenticated as a service account principal, that principal is a [cloud agent](/platform/agents/) on your team. For machine-readable output, set `--output-format json` or `--output-format text`. ```sh # JSON output for scripts oz whoami --output-format json # Compact "type:id" output oz whoami --output-format text ``` If `oz whoami` reports that it could not determine your user ID, your credentials are missing or invalid. Run `oz login` (or set `WARP_API_KEY`) and try again. ### Logging out [Section titled “Logging out”](#logging-out) Use `oz logout` to clear the CLI’s cached credentials on this machine: ```sh oz logout ``` If you weren’t logged in, the command prints `You are not logged in.` and exits. After logging out, run `oz login` to authenticate again. Note `oz logout` only affects credentials stored by the CLI. API keys authenticated through `WARP_API_KEY` or `--api-key` are not affected — unset the environment variable or omit the flag to stop using them. ### API key authentication [Section titled “API key authentication”](#api-key-authentication) Use an API key when the environment must authenticate on its own, such as CI pipelines, headless servers, VMs, Codespaces, or containers. API keys let the CLI authenticate non-interactively. For detailed instructions on creating, managing, and using API keys, see [API Keys](/agents/cli/oz-cli/api-keys/). **Quickstart:** ```sh $ export WARP_API_KEY="wk-xxx..." $ oz agent run --prompt "analyze this codebase" ``` *** ## Running agents [Section titled “Running agents”](#running-agents) The Oz CLI offers two ways to run agents, depending on where you want the work to happen: **Use `oz agent run` when:** * You’re developing locally and want immediate feedback * You need the agent to work with files in your current directory * You want to inspect and modify the agent’s work in real time * You’re debugging or iterating on prompts **Use `oz agent run-cloud` when:** * You want the agent to run on a remote machine or standardized environment * You’re triggering agent work from CI/CD or automated systems * You need the agent to run independently of your local session * You’re delegating work that doesn’t require your immediate attention ### Running locally: \`oz agent run\` [Section titled “Running locally: \`oz agent run\`”](#running-locally-oz-agent-run) To start an agent, use the `oz agent run` subcommand. You’ll need to specify a prompt and, optionally, the [MCP servers](/agents/capabilities/mcp/) and [agent profile](/agents/capabilities/agent-profiles-permissions/) to use. ```sh oz agent run --prompt "set up a new Rust crate named warp-cli" ``` **Key flags:** * `--cwd ` (`-C`) — run from a different directory. * `--name ` (`-n`) — label the run for grouping and traceability. * `--share` — share the session with teammates (see [Collaboration](/agents/cli/oz-cli/#collaboration)). * `--profile ` — use a specific agent profile (see [Using Agent Profiles](/agents/cli/oz-cli/#using-agent-profiles)). * `--model ` — override the default model (see [Model Choice](/agents/inference/model-choice/)). * `--skill ` — use a skill as the base prompt (see [Using Skills](/agents/cli/oz-cli/#using-skills)). * `--mcp ` — start one or more MCP servers before execution (UUID, JSON file path, or inline JSON). Can be repeated. * `--environment ` (`-e`) — run in a specific cloud environment. * `--file ` (`-f`) — load run configuration from a YAML or JSON file. The agent will automatically carry out the task you gave it, printing out tool calls and responses as it works. By default, the agent runs in your current working directory. To run from a different directory, use the `-C/--cwd` flag. ### Running agents remotely: \`oz agent run-cloud\` [Section titled “Running agents remotely: \`oz agent run-cloud\`”](#running-agents-remotely-oz-agent-run-cloud) Cloud runs dispatch tasks to remote environments. Use cloud runs for: * Background processing * Standardized team configurations * Remote execution on servers you don’t directly access ```sh oz agent run-cloud \ --environment \ --name "Repo summary" \ --prompt "Summarize this repo and list the top 5 risky areas" \ --open ``` **Key flags** * `--environment ` (`-e`) — select the environment to run in. * `--no-environment` — run without an environment (not recommended). * `--open` — view the agent’s session in Warp once it’s available. * `--name ` (`-n`) — label the run for grouping and traceability (see [Naming runs](/agents/cli/oz-cli/#naming-runs) below). * `--title