diff --git a/.agents/skills/style_lint/SKILL.md b/.agents/skills/style_lint/SKILL.md index 188c2a84..8e510cc0 100644 --- a/.agents/skills/style_lint/SKILL.md +++ b/.agents/skills/style_lint/SKILL.md @@ -1,6 +1,6 @@ --- name: style_lint -description: Scan Warp Astro Starlight documentation for style guide violations including formatting issues (Settings path format, UI element format, header case, missing frontmatter, image alt text, callout syntax) and terminology issues (product name casing, Oz terms to avoid, deprecated terms). Run with --changed for PR workflows or --all for periodic audits. Optionally auto-fix high-confidence issues with --fix. +description: Scan Warp Astro Starlight documentation for style guide violations including formatting issues (Settings path format, UI element format, header case, missing frontmatter, image alt text, standardized screenshot widths, callout syntax) and terminology issues (product name casing, Oz terms to avoid, deprecated terms). Run with --changed for PR workflows or --all for periodic audits. Optionally auto-fix high-confidence issues with --fix. --- # Style Lint @@ -46,6 +46,7 @@ python3 .warp/skills/style_lint/style_lint.py --all --fix --create-pr - **Header case**: Title Case in H2/H3/H4 headers (should be sentence case, with exceptions for proper feature names) - **Missing frontmatter**: Pages without YAML `description` field - **Image alt text**: `` or `
` without alt text or with generic alt text ("screenshot", "image") +- **Screenshot widths**: Likely UI/product screenshots must use `
` with a standard width (`300px`, `350px`, `375px`, or `563px`) - **Callout syntax**: Leftover GitBook `{% hint %}` tags that should be migrated to Starlight `:::note` / `:::caution` / `:::danger` asides - **List format**: Bulleted feature/capability lists missing the bold term + dash pattern (report only, never auto-fixed) diff --git a/.agents/skills/style_lint/style_lint.py b/.agents/skills/style_lint/style_lint.py index 644ef86b..1c3e31b7 100644 --- a/.agents/skills/style_lint/style_lint.py +++ b/.agents/skills/style_lint/style_lint.py @@ -92,6 +92,31 @@ TERMINOLOGY_FILE = Path(".warp/references/terminology.md") +STANDARD_SCREENSHOT_WIDTHS = {"300px", "350px", "375px", "563px"} + +SCREENSHOT_PATH_HINTS = ( + "/assets/", + "../../assets/", + "../../../assets/", + "../../../../assets/", + "../../../../../assets/", + ".png", + ".gif", + ".jpg", + ".jpeg", + ".webp", +) + +NON_SCREENSHOT_HINTS = ( + "architecture", + "diagram", + "flowchart", + "infra", + "infrastructure", + "logo", + "use-cases", +) + # Common bolded words that are NOT product terms (false positive suppression) COMMON_BOLD_WORDS = { # General emphasis words @@ -333,6 +358,84 @@ def check_image_alt_text(lines: List[str], filepath: str) -> List[Issue]: return issues +def _is_likely_screenshot(markdown_image_line: str) -> bool: + """Return True for UI/product screenshots while avoiding diagrams/logos.""" + lower = markdown_image_line.lower() + if not any(hint in lower for hint in SCREENSHOT_PATH_HINTS): + return False + if any(hint in lower for hint in NON_SCREENSHOT_HINTS): + return False + return True + + +def _figure_width(line: str) -> Optional[str]: + """Extract a maxWidth value from an MDX figure opening tag.""" + match = re.search(r"maxWidth:\s*[\"']([^\"']+)[\"']", line) + if match: + return match.group(1) + return None + + +def check_screenshot_widths(lines: List[str], filepath: str) -> List[Issue]: + """Check that screenshot images use standardized width-controlled figures. + + The docs style guide asks screenshots to use consistent widths. This check + flags likely UI/product screenshots that are standalone Markdown images or + figure-wrapped images missing a standard maxWidth. Architecture diagrams, + logos, and broad conceptual illustrations are intentionally excluded by + filename/alt-text hints because they often need default content width. + """ + issues = [] + in_code_block = False + figure_start_line: Optional[int] = None + figure_opening = "" + figure_has_likely_screenshot = False + + for i, line in enumerate(lines, 1): + stripped = line.strip() + if stripped.startswith("```"): + in_code_block = not in_code_block + continue + if in_code_block: + continue + + if " with a standard maxWidth (300px, 350px, 375px, or 563px)", + "warning", + )) + else: + figure_has_likely_screenshot = True + + if "
" in line and figure_start_line is not None: + if figure_has_likely_screenshot: + width = _figure_width(figure_opening) + if width is None: + issues.append(Issue( + filepath, figure_start_line, "screenshot-width", + "Screenshot figure is missing a standard maxWidth (300px, 350px, 375px, or 563px)", + "warning", + )) + elif width not in STANDARD_SCREENSHOT_WIDTHS: + issues.append(Issue( + filepath, figure_start_line, "screenshot-width", + f"Screenshot figure uses non-standard maxWidth \"{width}\"; use one of {', '.join(sorted(STANDARD_SCREENSHOT_WIDTHS))}", + "warning", + )) + figure_start_line = None + figure_opening = "" + figure_has_likely_screenshot = False + + return issues + + def check_callout_syntax(lines: List[str], filepath: str) -> List[Issue]: """Check for malformed hint/callout syntax.""" issues = [] @@ -561,6 +664,7 @@ def run_all_checks(filepath: Path) -> List[Issue]: issues.extend(check_ui_element_backticks(lines, str(filepath))) issues.extend(check_header_case(lines, str(filepath))) issues.extend(check_image_alt_text(lines, str(filepath))) + issues.extend(check_screenshot_widths(lines, str(filepath))) issues.extend(check_callout_syntax(lines, str(filepath))) issues.extend(check_product_casing(lines, str(filepath))) issues.extend(check_oz_terms(lines, str(filepath))) diff --git a/src/content/docs/agent-platform/capabilities/mcp.mdx b/src/content/docs/agent-platform/capabilities/mcp.mdx index b8b8a06b..5ba7549a 100644 --- a/src/content/docs/agent-platform/capabilities/mcp.mdx +++ b/src/content/docs/agent-platform/capabilities/mcp.mdx @@ -1,7 +1,7 @@ --- title: Model Context Protocol (MCP) description: >- - Configure MCP servers in the Warp desktop app to extend local agents with + Configure MCP servers in the Warp app to extend local agents with custom tools and data sources through a standardized interface. --- import { Tabs, TabItem } from '@astrojs/starlight/components'; @@ -12,7 +12,7 @@ MCP servers extend Warp's [local agents](/agent-platform/local-agents/interactin 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 desktop app. If you're using cloud agents, see [MCP Servers for cloud agents](/agent-platform/cloud-agents/mcp/). +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](/agent-platform/cloud-agents/mcp/). ::: ### How to access MCP Server settings @@ -26,7 +26,7 @@ You can navigate to the MCP servers page in any of the following ways: 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](../../../../assets/agent-platform/mcp-servers-list.png)
MCP servers page.
@@ -41,7 +41,7 @@ MCP server types you can add: Provide a startup command. Warp will launch this command when starting up and shut it down on exit. -
+
![Adding a CLI MCP Server (Command)](../../../../assets/agent-platform/mcp-servers-add-cli.png)
Adding a CLI MCP Server (Command).
@@ -62,7 +62,7 @@ MCP server types you can add: Provide a URL where Warp can reach an already-running MCP server that supports Server-Sent Events. -
+
![Adding an SSE MCP Server (URL)](../../../../assets/agent-platform/mcp-servers-add-sse.png)
Adding an SSE MCP Server (URL).
@@ -134,7 +134,10 @@ 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. +
![Toggle to auto-spawn global file-based MCP servers](/assets/agent-platform/file-based-mcp-setting.png) +
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. @@ -170,7 +173,7 @@ You can rename and edit a server's name, as well as delete the server. If you ar 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 a MCP Server](../../../../assets/agent-platform/mcp-servers-share.png)
Sharing a MCP Server.
diff --git a/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx b/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx index 3c8d4e1e..d7234a58 100644 --- a/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx +++ b/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx @@ -114,6 +114,8 @@ When a task is naturally divisible, use [multi-agent orchestration](/agent-platf Use this when you need to control where agent execution happens while still using Oz orchestration and visibility. Repositories are cloned and stored only on your infrastructure; orchestration metadata, session transcripts, and LLM inference route through Warp's backend under [ZDR](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr). +Think of self-hosted execution as **customer-hosted execution with Warp-hosted orchestration**, not as a fully offline agent stack. Code repositories, build artifacts, runtime secrets, and execution workspaces stay on your infrastructure. Code context can still appear in session transcripts and LLM prompts as the agent works. + :::note **Enterprise feature**: Self-hosted execution is available exclusively to teams on an Enterprise plan. ::: diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx index faadaf15..ed6b8236 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx @@ -17,7 +17,7 @@ Watch this walkthrough to see how cloud-to-cloud handoff continues a cloud agent Use this handoff direction when: * You want to send a follow-up to a cloud agent after its session has ended. -* You want to continue a background cloud agent run, such as a scheduled or integration-triggered run, while preserving it as a single unit of work in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/). +* You want to continue a background cloud agent run, such as a scheduled or integration-triggered run, while preserving it as a single unit of work in the [Agent Management Panel](/agent-platform/cloud-agents/managing-cloud-agents/) in the Warp app and the [Runs page in the Oz web app](/agent-platform/cloud-agents/oz-web-app/#runs). ## What carries over @@ -58,9 +58,9 @@ Cloud-to-cloud handoff also works for supported third-party agent runtimes, but ## Inspecting a run that's been handed off -The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows one row per run, even when the run spans multiple sessions. +The [Agent Management Panel](/agent-platform/cloud-agents/managing-cloud-agents/) in the Warp app and the [Runs page in the Oz web app](/agent-platform/cloud-agents/oz-web-app/#runs) show one row per run, even when the run spans multiple sessions. -1. Open the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) in the Warp app or Oz web app. +1. Open the [Agent Management Panel](/agent-platform/cloud-agents/managing-cloud-agents/) in the Warp app or the [Runs page in the Oz web app](/agent-platform/cloud-agents/oz-web-app/#runs). 2. Select the handed-off run. 3. Review the transcript. Each session appears in order, so you can see where one session ended and the next began. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx index 6f39e50c..5345cc7a 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx @@ -50,7 +50,7 @@ Each direction has a clear motivating workflow. ## Related pages * [Cloud agents overview](/agent-platform/cloud-agents/overview/) - What cloud agents are, when to use them, and how they fit into the Oz Platform. -* [Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Inspect handoff runs from the management view alongside local conversations. +* [Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Inspect handoff runs from the Agent Management Panel in the Warp app or the Runs page in the Oz web app alongside local conversations. * [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) - Open and continue a cloud run locally with **Continue locally** or `/continue-locally`. * [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) - How conversations sync between local and cloud so handoff can find them. * [Environments](/agent-platform/cloud-agents/environments/) - The runtime context a cloud agent runs in after a handoff. diff --git a/src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx b/src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx index fb731a5b..deebccd1 100644 --- a/src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx @@ -11,9 +11,9 @@ import VideoEmbed from '@components/VideoEmbed.astro'; Oz can run third-party agent harnesses as cloud agents alongside Warp Agent, including [Claude Code](/agent-platform/cloud-agents/harnesses/claude-code/) and [Codex](/agent-platform/cloud-agents/harnesses/codex/). You choose the harness (agent runtime) that fits the task; the platform around the run stays the same. -Watch this walkthrough to see how to run Warp Agent, Claude Code, or Codex as an Oz cloud agent. +Watch this walkthrough to see how to run Warp Agent, Claude Code, or Codex as a cloud agent. - + ## What stays the same @@ -30,7 +30,7 @@ Claude Code and Codex each call their provider directly using credentials you su ## How to switch harnesses -### Warp desktop app +### Warp app In Cloud Mode, choose a harness from the **Agent harness** dropdown above the input. diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx index 9bf7f2d7..909c336e 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx @@ -12,6 +12,8 @@ Run agents directly in your GitHub Actions workflows using `oz-agent-action`. Th **Getting started?** See the [GitHub Actions quickstart](/agent-platform/cloud-agents/integrations/quickstart-github-actions/) to set up your first workflow, or visit the [oz-agent-action repository](https://github.com/warpdotdev/oz-agent-action) for detailed setup instructions and ready-to-use workflow templates. ::: +If you're comparing GitHub Actions with schedules, Slack, Linear, the Oz CLI, or API-triggered runs, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). + Watch this demo to see the integration in action: diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/index.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/index.mdx index 2ede48d2..58f96de6 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/index.mdx @@ -13,6 +13,8 @@ Warp integrations let your team trigger agents directly from the terminal, or fr * Run code inside your codebase in a remote environment * Open pull requests and perform other multi-step agent workflows on your behalf +If you're deciding whether an agent should run from a schedule, Slack or Linear, GitHub Actions, the Oz CLI, or the API, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). + :::note For a full walkthrough of Warp's integrations and configurable environments, please refer to [Integration setup](/reference/cli/integration-setup/). ::: diff --git a/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx b/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx index 31fe8c34..9e5773e6 100644 --- a/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx @@ -1,39 +1,44 @@ --- title: Managing cloud agents description: >- - Monitor and manage cloud agent activity across your team with Warp's - centralized management view, including filtering, status tracking, and - session inspection. + Monitor and manage agent activity across your team with Warp's Agent + Management Panel and the Oz web app's Runs page. sidebar: label: "Managing cloud agents" --- import VideoEmbed from '@components/VideoEmbed.astro'; -Warp provides a centralized management view where you can monitor agent activity across your account and (where applicable) your team. You can access this view in the Warp app or through the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) at [oz.warp.dev](https://oz.warp.dev), which works on mobile devices. +Warp provides two management surfaces for tracking and observing agent activity across your account and, where applicable, your team: the **Agent Management Panel** in the Warp app and the [**Runs** page in the Oz web app](/agent-platform/cloud-agents/oz-web-app/#runs) at [oz.warp.dev](https://oz.warp.dev), which works on mobile devices. In Warp, open the Agent Management Panel from the Agent Management Panel button in the tab bar; in the web app, go to the Runs page. -The management view is designed to answer, at a glance: +Use these surfaces as the starting point for real-time agent observability in Warp. They help you see which agents are active, which runs are blocked or failed, where each run started, and which session link opens the prompt, plan, commands, logs, outputs, and follow-up messages behind the work. -* Which agents have been running recently (and what's running right now) -* Which runs succeeded, failed, or were canceled -* Where an agent run was triggered from (a local agent conversation, the Oz CLI, Slack, etc.) -* How many credits those runs consumed +The Agent Management Panel and Oz web app Runs page are designed to answer, at a glance: + +* Which agents are active or have been running recently. +* Which runs are working, blocked, failed, succeeded, or canceled. +* Where an agent run was triggered from, such as a local agent conversation, the Oz CLI, Slack, Linear, a schedule, or the API. +* How parent and child runs relate in orchestrated workflows. +* Which session to open when you need prompt, plan, command, log, output, or follow-up context. +* How many credits those runs consumed. + +Warp's agent observability is run- and session-oriented. It is not a replacement for full APM, OpenTelemetry, or Datadog-style tracing across arbitrary agent frameworks. Use Warp to track agent run status, trigger/source, owner, parent-child relationships, transcripts, commands, logs, outputs, and replayable session links. -This management view includes your **local (interactive) agents** and [cloud agent](/agent-platform/cloud-agents/overview/) runs. +These management surfaces include your **local (interactive) agents** and [cloud agent](/agent-platform/cloud-agents/overview/) runs. -
-![Warp's management view showing interactive and cloud agent runs.](../../../../assets/agent-platform/management-view-scannable-list.png) -
Warp's management view showing interactive and cloud agent runs.
+
+![Warp's Agent Management Panel showing interactive and cloud agent runs.](../../../../assets/agent-platform/management-view-scannable-list.png) +
Warp's Agent Management Panel showing interactive and cloud agent runs.
-### What appears in the management view +### What appears in the agent management surfaces -The management view includes two categories of agent activity. +The Agent Management Panel and Oz web app Runs page include two categories of agent activity. #### Interactive agents -* Initiated from the Warp desktop app. +* Initiated from the Warp app. * The conversation is owned by you. It opens locally in Warp, and can be shared via a link when needed. * Credit usage reflects inference. @@ -51,9 +56,23 @@ In the **Personal** tab, you can view all of the interactive and cloud agent con --- +### Inspect or review an agent run + +Use the Agent Management Panel or Oz web app Runs page as the starting point when a teammate asks, "What did the agent do?" + +1. In the agents list, use the filter menu to filter by source, day, creator, or status. +2. Select the matching row to open the shared session or local conversation. +3. Inspect the prompt, plan, commands, logs, outputs, and follow-up messages where available. +4. Share the session link with teammates if they need to review the same context. +5. For PR-producing workflows, include the session link alongside the PR link so reviewers can inspect both the code diff and the agent's execution context. + +For cloud agent runs, the session opens in [Cloud agent session sharing](/agent-platform/cloud-agents/viewing-cloud-agent-runs/). For local interactive agents, the conversation opens in Warp and can be shared with [Agent Session Sharing](/agent-platform/local-agents/session-sharing/). + +--- + ### The agents list -Each row represents a single item in the management view (either an interactive conversation or a cloud agent run). The list is intended to be scannable: you should be able to understand “what happened” without opening anything. +Each row represents a single item in the agents list (either an interactive conversation or a cloud agent run). The list is intended to be scannable: you should be able to understand “what happened” without opening anything. #### Fields you’ll see @@ -84,10 +103,10 @@ Warp uses a small set of statuses to help you quickly identify what needs attent **The primary interaction is simple:** -* Clicking a cloud agent row opens the [shared session](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) for that run (logs/messages/output). +* Clicking a cloud agent row opens the [shared session](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) for that run (prompt, plan, commands, logs, messages, and output where available). * Clicking an interactive row opens the conversation locally in the Warp app. -This makes the management view a navigation surface: find the thing you care about, click once, and you’re in the right context to inspect or continue work. +This makes the agents list a navigation surface: find the thing you care about, click once, and you’re in the right context to inspect or continue work. ### Filtering @@ -106,8 +125,8 @@ This is the fastest way to isolate "everything that failed today," "runs from Sl When a parent agent spawns one or more child agents through [multi-agent orchestration](/agent-platform/cloud-agents/orchestration/), the parent and each child are tracked as separate runs. Where you see them depends on the surface: -* **Local children in the Warp app** - while you're viewing the parent agent, an orchestration pill bar above the agent view header shows one pill per child with a live status badge. Click a child pill to switch the pane to that child's conversation in place; click the parent pill - or the breadcrumb that replaces the pill bar while you're viewing a child - to return. Local children don't appear as separate rows in the management view list. -* **Cloud children in the Warp app** - appear in the management view list as their own rows alongside the parent and other runs. Filter by source, status, or creator to isolate them. +* **Local children in the Warp app** - while you're viewing the parent agent, an orchestration pill bar above the agent view header shows one pill per child with a live status badge. Click a child pill to switch the pane to that child's conversation in place; click the parent pill - or the breadcrumb that replaces the pill bar while you're viewing a child - to return. Local children don't appear as separate rows in the Agent Management Panel list. +* **Cloud children in the Warp app** - appear in the Agent Management Panel list as their own rows alongside the parent and other runs. Filter by source, status, or creator to isolate them. * **Cloud children in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/)** - grouped under the parent's row on the Runs page, and surfaced together inside the parent's detail pane on a **Sub-agents** tab. The parent's own status reflects only its work - a parent can finish successfully while a child is still running or has failed. To verify that an orchestration completed, check each child individually from the pill bar (in the Warp app) or the **Sub-agents** tab (in the Oz web app). diff --git a/src/content/docs/agent-platform/cloud-agents/mcp.mdx b/src/content/docs/agent-platform/cloud-agents/mcp.mdx index a5b806c4..754fdd0c 100644 --- a/src/content/docs/agent-platform/cloud-agents/mcp.mdx +++ b/src/content/docs/agent-platform/cloud-agents/mcp.mdx @@ -118,6 +118,7 @@ As a workaround, you can pass Figma mockups as **image context** to the agent, w ## Learn more +* [Connect developer tools to agents with MCP workflows](/guides/external-tools/using-mcp-servers-with-warp/) — choose between local, cloud, and shared MCP setup paths * [MCP Servers (CLI reference)](/reference/cli/mcp-servers/) — how to pass MCP configuration using the `--mcp` flag * [Model Context Protocol (MCP)](/agent-platform/capabilities/mcp/) — configuring MCP servers in Warp for local agents * [Environments](/agent-platform/cloud-agents/environments/) — set up the runtime context (repo, image, startup commands) for cloud agent tasks diff --git a/src/content/docs/agent-platform/cloud-agents/orchestration/index.mdx b/src/content/docs/agent-platform/cloud-agents/orchestration/index.mdx index 3408e749..55477f3e 100644 --- a/src/content/docs/agent-platform/cloud-agents/orchestration/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/orchestration/index.mdx @@ -27,7 +27,7 @@ Orchestrations today are exactly one level deep: a parent and its direct childre The parent and child don't have to run in the same place. Orchestration supports four combinations: -* **Local → local** - a [Warp Agent](/agent-platform/local-agents/overview/) conversation in the desktop app spawns child Warp Agent conversations on the same machine. Useful for trying orchestration patterns without spinning up cloud infrastructure. +* **Local → local** - a [Warp Agent](/agent-platform/local-agents/overview/) conversation in the Warp app spawns child Warp Agent conversations on the same machine. Useful for trying orchestration patterns without spinning up cloud infrastructure. * **Local → cloud** - a local parent spawns one or more cloud children that run in [environments](/agent-platform/cloud-agents/environments/) on Warp-hosted or self-hosted infrastructure. The parent keeps working while children execute in parallel. * **Cloud → cloud** - a cloud parent spawns cloud children that each run in their own environment. This is the canonical pattern for review swarms, large fan-outs, and any orchestration triggered from Slack, Linear, a schedule, or the API. * **Cloud → cloud-local** - a cloud parent spawns children that run inside the parent's own cloud environment, rather than each child getting its own environment. Useful when children need to share state with the parent (a filesystem, a long-running process, a shell session) or when spinning up an environment per child would be wasteful. @@ -50,7 +50,7 @@ The main user-visible states a child run can reach are: Track run state transitions in these places: * **The parent's transcript** - the parent agent receives child state transitions as it runs and reflects them in its own conversation. -* **The orchestration pill bar** - in the Warp desktop app, while you're viewing the parent agent, a horizontal pill bar above the agent view header shows the parent on the left and one pill per child. Each pill displays the child's name and a status badge that updates live. Click a pill to switch the pane to that child's conversation in place; click the parent pill to switch back. +* **The orchestration pill bar** - in the Warp app, while you're viewing the parent agent, a horizontal pill bar above the agent view header shows the parent on the left and one pill per child. Each pill displays the child's name and a status badge that updates live. Click a pill to switch the pane to that child's conversation in place; click the parent pill to switch back. * **The Oz web app** - cloud children appear under the parent on the [Runs page](https://oz.warp.dev/runs) and in the parent's **Sub-agents** tab, with their status updating live. * **The Oz API** - `GET /agent/runs/{runId}` returns the latest state of any run, and `GET /agent/runs?ancestor_run_id=PARENT_RUN_ID` lists every descendant in one call. @@ -111,7 +111,7 @@ In both cases, approval is required before the parent launches children. Approvi Because every parent and child is tracked as its own conversation or run, the existing observability surfaces work without changes: -* **[Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/)** - in the Warp app, the orchestration pill bar above the agent view header lets you switch between the parent and each child while you're viewing the parent. Cloud children also appear as their own rows in the management view list. +* **[Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/)** - in the Warp app, the orchestration pill bar above the agent view header lets you switch between the parent and each child while you're viewing the parent. Cloud children also appear as their own rows in the Agent Management Panel list. * **[Oz web app](/agent-platform/cloud-agents/oz-web-app/)** - the Runs page groups cloud children under the parent's row, and the parent's detail pane adds a **Sub-agents** tab. * **[Oz API](/reference/api-and-sdk/)** - list every descendant of a parent in one call and fetch any run with its conversation, transcript, and artifacts. See [Running orchestrated agents](/agent-platform/cloud-agents/orchestration/multi-agent-runs/#retrieving-conversations-and-artifacts). * **[Agent notifications](/agent-platform/capabilities/agent-notifications/)** - in-app notifications fire on the parent agent's conversation only. Use the pill bar or the **Sub-agents** tab to drill into a specific child. @@ -119,6 +119,7 @@ Because every parent and child is tracked as its own conversation or run, the ex ## Related pages * [Running orchestrated agents](/agent-platform/cloud-agents/orchestration/multi-agent-runs/) - how to start an orchestrated run from the CLI, slash command, web app, or API. +* [How to run multiple AI coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) - practical guidance for splitting tasks, assigning worktrees, validating child output, and handing work off for review. * [Oz API and SDK](/reference/api-and-sdk/) - REST endpoints for runs, conversations, and artifacts. * [Cloud agents overview](/agent-platform/cloud-agents/overview/) - what a cloud agent run is and how it fits into the Oz Platform. * [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns/) - higher-level deployment models that orchestration composes with. diff --git a/src/content/docs/agent-platform/cloud-agents/orchestration/multi-agent-runs.mdx b/src/content/docs/agent-platform/cloud-agents/orchestration/multi-agent-runs.mdx index 96bc35c7..df352b4c 100644 --- a/src/content/docs/agent-platform/cloud-agents/orchestration/multi-agent-runs.mdx +++ b/src/content/docs/agent-platform/cloud-agents/orchestration/multi-agent-runs.mdx @@ -23,7 +23,7 @@ Cloud parents that spawn cloud children need access to one or more [environments ## Starting an orchestrated run from Warp -In the Warp desktop app, open the agent input and type `/orchestrate` followed by your task. The agent enters `orchestrate` mode and proposes a breakdown before spawning any children. +In the Warp app, open the agent input and type `/orchestrate` followed by your task. The agent enters `orchestrate` mode and proposes a breakdown before spawning any children. ```text /orchestrate Migrate every test file in this repo from Jest to Vitest. Spawn one child per top-level directory under packages/. @@ -43,7 +43,7 @@ You can also reach the same approval flow from `/plan`. When you ask the agent t ### Spawning cloud children from a local parent -A local parent - a Warp Agent conversation in the desktop app - can spawn cloud children by specifying an environment for each child. The parent asks for the environment if it isn't already clear from context. You can select any environment from your account or team. +A local parent - a Warp Agent conversation in the Warp app - can spawn cloud children by specifying an environment for each child. The parent asks for the environment if it isn't already clear from context. You can select any environment from your account or team. Cloud children inherit the parent's authentication; the same credit and credentials rules from the [Cloud agents overview](/agent-platform/cloud-agents/overview/) apply. @@ -118,7 +118,7 @@ Content-Type: application/json } ``` -Setting `parent_run_id` is what links the child to its parent across the management view, the web app, and the descendants query (`?ancestor_run_id=`). +Setting `parent_run_id` is what links the child to its parent across the Agent Management Panel in the Warp app, the Oz web app Runs page, and the descendants query (`?ancestor_run_id=`). A scripted fan-out, including parent linking, looks like this: @@ -189,7 +189,8 @@ Self-hosted, local, and GitHub Action runs cannot be cancelled through this endp ## Related pages * [Multi-agent orchestration](/agent-platform/cloud-agents/orchestration/) - parent/child model, run state transitions, and common patterns. +* [How to run multiple AI coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) - practical task decomposition, worktree ownership, validation, and review handoff guidance. * [Oz CLI](/reference/cli/) - command reference for `oz agent run-cloud` and `oz run`. * [Oz API and SDK](/reference/api-and-sdk/) - full HTTP reference and typed SDKs. -* [Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/) - how parent and child runs appear in the management view. +* [Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/) - how parent and child runs appear in the Agent Management Panel in the Warp app and the Runs page in the Oz web app. * [Environments](/agent-platform/cloud-agents/environments/) - configure the runtime context cloud children execute in. diff --git a/src/content/docs/agent-platform/cloud-agents/overview.mdx b/src/content/docs/agent-platform/cloud-agents/overview.mdx index a5608f05..c9258da0 100644 --- a/src/content/docs/agent-platform/cloud-agents/overview.mdx +++ b/src/content/docs/agent-platform/cloud-agents/overview.mdx @@ -8,10 +8,16 @@ sidebar: --- import VideoEmbed from '@components/VideoEmbed.astro'; -Cloud agents are autonomous, background agents that run on Warp's cloud infrastructure or your own, triggered by system events, schedules, or integrations like Slack and GitHub. They execute tasks with full observability — every run is tracked, auditable, and shareable across your team. +Cloud agents are autonomous, background agents that run on Warp's cloud infrastructure or your own, triggered by system events, schedules, or integrations like Slack and GitHub. They execute tasks with full observability — every run is tracked, inspectable, and shareable across your team. **New to cloud agents?** Start with the [Cloud agents quickstart](/agent-platform/cloud-agents/quickstart/) to run your first cloud agent in ~10 minutes. +### Monitor, inspect, and share cloud agent runs + +To understand what a cloud agent did, start from the [Agent Management Panel](/agent-platform/cloud-agents/managing-cloud-agents/) in the Warp app or the [Runs page in the Oz web app](/agent-platform/cloud-agents/oz-web-app/#runs). From there, you can find a run by source, status, trigger, or owner; open the run transcript; inspect the prompt, plan, commands, logs, and output; and share the session link with teammates for review. + +For a full walkthrough, see [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/). If the run came from Slack, Linear, GitHub Actions, a schedule, the CLI, or the API, it still produces a reviewable cloud agent run record. + ### What cloud agents are designed for @@ -21,7 +27,7 @@ Cloud agents are designed for situations where: * **You need agents to react to system events.** * Examples include crashes, bug reports, Slack interactions, cron timers, or CI steps. * **You want observability into agent activity across a team or system.** - * This includes being able to see what ran, when it ran, and what it did. + * This includes being able to see what ran, when it ran, what triggered it, what the agent did, and how teammates can review or share the result. * **You need more parallelism than local execution typically allows.** * For example, running many agent tasks concurrently in the cloud, sharding a repo-wide task into multiple runs, or fanning out the same task across multiple targets. * **You want agents to operate continuously as part of engineering infrastructure.** @@ -40,7 +46,7 @@ Each task includes: * **Inputs**: a prompt, and often additional context from the triggering system (for example a Slack message, PR metadata, or CI logs). * **Execution context (optional)**: an [Environment](/agent-platform/cloud-agents/environments/) that defines the repo, image, and startup commands the agent should run with. * **Lifecycle state**: created → running → completed / failed. -* **Persistent record**: status, metadata, and a session transcript that can be reviewed after the task completes. +* **Persistent record**: status, metadata, and a session transcript that can be reviewed after the task completes, including the prompt, plan, commands, logs, outputs, and follow-up messages where available. :::note If you are evaluating whether something should be a cloud agent, a good test is whether you can define:\ @@ -61,7 +67,7 @@ For teams that need execution to stay within their network boundary, self-hostin ### What you get by default -Because cloud agents run on the [Oz Platform](/agent-platform/cloud-agents/platform/), each run is tracked and produces a persistent record that can be observed, shared, and audited (even if execution happens outside the Warp app). +Because cloud agents run on the [Oz Platform](/agent-platform/cloud-agents/platform/), each run is tracked and produces a persistent record that can be observed, shared, and reviewed (even if execution happens outside the Warp app). #### Codebase Context @@ -71,9 +77,9 @@ Cloud agent runs automatically benefit from [Codebase Context](/agent-platform/c Cloud agent tasks are designed to be inspectable by the team: -* [Agent Session Sharing](/agent-platform/local-agents/session-sharing/) lets authorized teammates attach to a running task to monitor progress and, where supported, steer the agent while it runs. -* Each run produces a session transcript and task metadata, which provides a record of what the agent did. -* A [management experience](/agent-platform/cloud-agents/managing-cloud-agents/) surfaces task status and history. +* The [Agent Management Panel](/agent-platform/cloud-agents/managing-cloud-agents/) in the Warp app and the [Runs page in the Oz web app](/agent-platform/cloud-agents/oz-web-app/#runs) surface task status, source, trigger, creator, history, and credit usage. +* [Cloud agent session sharing](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) opens the run transcript so teammates can inspect the prompt, plan, commands, logs, files changed, outputs, and follow-up messages where available. +* [Agent Session Sharing](/agent-platform/local-agents/session-sharing/) lets authorized teammates share, monitor, and steer live local or third-party agent sessions. #### Centralized configuration @@ -93,12 +99,12 @@ The Oz Platform exposes task visibility via the [**Oz API and SDKs**](/reference ### Using cloud agents with or without the Warp app -Cloud agents do not require the Warp desktop app. Teams can deploy and operate them through the [Oz Platform](/agent-platform/cloud-agents/platform/) using: +Cloud agents do not require the Warp app. Teams can deploy and operate them through the [Oz Platform](/agent-platform/cloud-agents/platform/) using: * [Oz CLI](/reference/cli/) — run agents from scripts, CI, or the terminal * [Oz web app](/agent-platform/cloud-agents/oz-web-app/) — visual interface for managing runs, schedules, environments, and integrations (works on mobile) * [Agent Session Sharing](/agent-platform/local-agents/session-sharing/) — attach to running tasks to monitor or steer -* [Agent Management UX](/agent-platform/cloud-agents/managing-cloud-agents/) — view agent activity and run history +* [Agent Management Panel](/agent-platform/cloud-agents/managing-cloud-agents/) — view agent activity and run history in the Warp app * [APIs and SDKs](/reference/api-and-sdk/) — programmatic access for custom integrations If your team also uses Warp's terminal, you get an additional workflow: tasks launched via the CLI can be handed off into an interactive session for review, edits, or continuation. diff --git a/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx b/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx index f1efdd14..98a03331 100644 --- a/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx +++ b/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx @@ -21,9 +21,9 @@ Watch this short demo to create an environment and run an agent using the Oz web
PagePathWhat you can do
Runs/runsView all runs, filter by status/source/creator, start new runs, inspect transcripts
Agents/agentsBrowse saved agents, create agents, configure defaults, and start runs
Skills/skillsBrowse skills from your environments, view suggested skills, create skills for agents, and start runs
Schedules/schedulesCreate scheduled agents, pause/enable schedules, view run history
Environments/environmentsCreate and manage environments with repos, Docker images, and setup commands
Secrets/secretsCreate and manage Warp-managed secrets for cloud agent runs
Integrations/integrationsConnect Slack and Linear to trigger agents from external tools
-
-![The Oz web app's management view.](../../../../assets/agent-platform/oz-web-app-runs-view.png) -
The Oz web app management view.
+
+![The Oz web app's Runs page.](../../../../assets/agent-platform/oz-web-app-runs-view.png) +
The Oz web app Runs page.
## When to use the web app @@ -46,7 +46,7 @@ When you first sign in to the Oz web app, you'll see a guided onboarding flow th The onboarding asks "What brings you to Oz?" and offers three paths: * **Create an agent automation** — Walks you through setting up a scheduled agent, integration-triggered agent, or other automation -* **Run Cloud Agents in Warp** — Opens the Warp desktop app (or takes you to the download page) to run cloud agents interactively +* **Run Cloud Agents in Warp** — Opens the Warp app (or takes you to the download page) to run cloud agents interactively * **Build an app that uses agents** — Links to the [Oz Platform](/agent-platform/cloud-agents/platform/) docs for using the CLI, SDK, or API You can skip onboarding at any time to go directly to the Runs page. @@ -97,7 +97,7 @@ Skills are reusable instruction sets stored in repositories. You can attach exis Saved agents use Warp's team-scoped identity model, which lets a reusable agent own runs and carry default configuration for teammates. You manage saved agents from the Agents page. For plan limits, API endpoints, and API key binding behavior, see [Agent identities](/agent-platform/cloud-agents/agents/). -
+
![The Agents page in the Oz web app.](../../../../assets/agent-platform/oz-web-app-agents.png)
The Agents page in the Oz web app.
@@ -118,7 +118,7 @@ To create a saved agent: For deeper guidance on reusable skills and team-scoped identities, see [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/) and [Agent identities](/agent-platform/cloud-agents/agents/). -
+
![Creating a new agent in the Oz web app.](../../../../assets/agent-platform/oz-web-app-new-agent.png)
Creating a new agent in the Oz web app.
@@ -142,7 +142,7 @@ To create a skill for agents: 3. Define the skill. Add a skill name, description, and instructions. 4. Click **Open Skill PR** to create a pull request that adds the skill to the selected repository. -
+
![Creating a skill for agents in the Oz web app.](../../../../assets/agent-platform/oz-web-app-new-skill.png)
Creating a skill in the Oz web app.
@@ -159,7 +159,7 @@ Each schedule displays:
FieldDescription
NameA descriptive name for the scheduled task
FrequencyHuman-readable description of the cron schedule (e.g., "Every Monday at 10am")
Next runWhen the schedule will next execute
EnvironmentWhich environment the scheduled agent runs in
AgentWhich saved agent the schedule uses (if any)
StatusWhether the schedule is active or paused
-
+
![The Schedules page in the Oz web app.](../../../../assets/agent-platform/oz-web-app-schedules.png)
The Schedules page in the Oz web app.
@@ -199,7 +199,7 @@ Each environment displays:
FieldDescription
NameThe environment's identifier
Docker imageThe container image used for execution
RepositoriesWhich repos the agent can access
Setup commandsCommands run before the agent starts
-
+
![The Environments page in the Oz web app.](../../../../assets/agent-platform/oz-web-app-environments.png)
The Environments page in the Oz web app.
@@ -227,7 +227,7 @@ The **Integrations** page (`/integrations`) lets you configure first-party integ
IntegrationDescription
SlackTag @Oz in messages or threads to trigger agents directly from Slack conversations
LinearTag @Oz on issues to trigger agents from your issue tracker
-
+
![The Integrations page in the Oz web app.](../../../../assets/agent-platform/oz-web-app-integrations.png)
The Integrations page in the Oz web app.
diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/index.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/index.mdx index cbb98904..df8f61ee 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/index.mdx @@ -6,7 +6,7 @@ description: >- control. --- -Self-hosting lets your team run cloud agent workloads on your own infrastructure instead of Warp-managed servers. You control the execution environment, compute resources, and network access. Repositories are cloned and stored only on your machines, and agents can reach services behind your VPN or firewall. +Self-hosting lets your team run cloud agent workloads on your own infrastructure instead of Warp-managed servers. You control the execution environment, compute resources, and network access. Repository clones, source files, build artifacts, runtime secrets, and agent execution workspaces stay on your infrastructure, and agents can reach services behind your VPN or firewall. **New to self-hosting?** Start with the [Self-hosting quickstart](/agent-platform/cloud-agents/self-hosting/quickstart/) to get a managed worker running on Docker in under 10 minutes. @@ -40,6 +40,8 @@ The two architectures are not mutually exclusive. Some teams run managed workers Warp uses a split-plane architecture: **execution happens on your infrastructure**, while **orchestration, session management, and LLM inference route through Warp's backend**. Agent interactions — including code context in session transcripts and LLM prompts — transit Warp's control plane under [Zero Data Retention (ZDR)](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements. Warp does not persistently store your source code or train on it. +If your security requirement is "repository clones and execution must stay on our infrastructure," self-hosting is designed for that. If your requirement is "no code context can ever route through Warp or an external LLM provider," review [Security and networking](/agent-platform/cloud-agents/self-hosting/security-and-networking/) with your Warp account team before deploying. + ![Self-hosted Oz architecture showing customer-managed execution with Oz orchestration](../../../../../assets/agent-platform/customer-dedicated-saas.png) With any self-hosted architecture: diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/security-and-networking.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/security-and-networking.mdx index 8533c7cd..da253c00 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/security-and-networking.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/security-and-networking.mdx @@ -13,6 +13,8 @@ This page applies to both the [managed](/agent-platform/cloud-agents/self-hostin ## Data boundaries +Self-hosted execution keeps repository clones, source files, build artifacts, runtime secrets, environment variables, and agent workspaces on infrastructure you control. Agents can also reach internal systems that your host can reach, such as VPN-only services, private databases, or self-hosted source control. + **Stored and executed only on your infrastructure:** * Repository clones and source files. diff --git a/src/content/docs/agent-platform/cloud-agents/triggers/index.mdx b/src/content/docs/agent-platform/cloud-agents/triggers/index.mdx index 84fa9652..9fae1b70 100644 --- a/src/content/docs/agent-platform/cloud-agents/triggers/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/triggers/index.mdx @@ -9,6 +9,8 @@ Triggers allow you to run cloud agents automatically without manual intervention To set up your first recurring agent, follow the [Scheduled Agents Quickstart](/agent-platform/cloud-agents/triggers/scheduled-agents-quickstart/). +If you're choosing between schedules, Slack, Linear, GitHub Actions, the Oz CLI, or the API, start with [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). + ## Available trigger types * **[Scheduled Agents](/agent-platform/cloud-agents/triggers/scheduled-agents/)** - Run agents on a recurring schedule using cron expressions. diff --git a/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents-quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents-quickstart.mdx index 279b7067..01379cef 100644 --- a/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents-quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents-quickstart.mdx @@ -31,7 +31,7 @@ Watch this short demo of creating and testing a scheduled agent: 5. Under **Frequency**, choose a preset or enter a custom cron expression (e.g., `0 9 * * 1` for every Monday at 9 AM). 6. Click **Create schedule**. -**Breaking it down:** The schedule lives in Oz's cloud infrastructure. Unlike a local cron job, it fires even when your machine is off. Each run starts a fresh, isolated session with no state carried over from previous executions, and every run is tracked and auditable in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/). +**Breaking it down:** The schedule lives in Oz's cloud infrastructure. Unlike a local cron job, it fires even when your machine is off. Each run starts a fresh, isolated session with no state carried over from previous executions, and every run is tracked and reviewable in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/). --- @@ -54,6 +54,7 @@ Runs are also accessible from the conversation panel view in the Warp app and on ## Next steps +* **Choose the right unattended trigger** - Compare schedules, Slack, Linear, GitHub Actions, CLI, and API workflows in [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). * **Trigger agents from your tools** - Connect Oz to Slack or Linear to trigger agents from mentions or issue updates. See [Integrations Quickstart](/agent-platform/cloud-agents/integrations/quickstart/). * **Manage and refine your schedule** - Change the frequency, swap skills, or pause and resume the schedule. See [Scheduled Agents](/agent-platform/cloud-agents/triggers/scheduled-agents/) for the full reference. * **Share with your team** - Schedules and environments are shared across your Warp team, so everyone benefits automatically. diff --git a/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents.mdx b/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents.mdx index ebf79683..b41429af 100644 --- a/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents.mdx @@ -14,6 +14,8 @@ Warp's Scheduled Agents let you run cloud agents automatically on a **recurring Scheduled Agents run in the background on Warp’s infrastructure. Each run starts from a clean session, executes a fixed prompt, and produces its own task and session history that can be inspected after the fact. +If you're deciding whether to use a schedule, Slack or Linear trigger, GitHub Actions, the Oz CLI, or the API, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). + --- ### What are Scheduled Agents? @@ -154,7 +156,7 @@ Each completed run also includes links to: * The task created by the agent. * The full agent session, including logs and outputs. -This makes it easy to audit what ran, when it ran, and what the agent did. +This makes it easy to review what ran, when it ran, and what the agent did. #### Viewing a specific Scheduled Agent @@ -172,7 +174,7 @@ This command returns additional details not shown in the list view, including: * Recent runs and execution metadata * Links to related tasks and agent sessions -This is useful when auditing behavior, debugging failures, or reviewing how a Scheduled Agent is configured. +This is useful when reviewing behavior, debugging failures, or inspecting how a Scheduled Agent is configured. ### Pausing and unpausing schedules @@ -266,7 +268,7 @@ oz schedule delete SCHEDULE_ID oz schedule delete abc123 ``` -Deleting a schedule immediately stops all future runs. Previous runs and their session history remain accessible for auditing and review. +Deleting a schedule immediately stops all future runs. Previous runs and their session history remain accessible for inspection and review. --- diff --git a/src/content/docs/agent-platform/cloud-agents/viewing-cloud-agent-runs.mdx b/src/content/docs/agent-platform/cloud-agents/viewing-cloud-agent-runs.mdx index 68af4ce6..0ad7cdc3 100644 --- a/src/content/docs/agent-platform/cloud-agents/viewing-cloud-agent-runs.mdx +++ b/src/content/docs/agent-platform/cloud-agents/viewing-cloud-agent-runs.mdx @@ -10,6 +10,8 @@ import VideoEmbed from '@components/VideoEmbed.astro'; Cloud agent session sharing lets you open, inspect, and continue interacting with agent tasks that are running on remote virtual machines. Whether a cloud agent was triggered from [integrations](/agent-platform/cloud-agents/integrations/) like Slack, Linear, GitHub Actions, or the [Oz CLI](/reference/cli/), you can view its full session, follow along in real time, ask follow-up questions, and even "fork" the work into your local Warp environment. +Use cloud agent session sharing when you need to inspect a cloud agent run, debug a failed automation, or give teammates a shared record of what the agent did. The shared session is the review surface for the run: it shows the prompt, plan, commands, logs, outputs, and follow-up messages where available. + This makes cloud agent runs observable, steerable, and collaborative — even if they weren't initiated from your machine. @@ -22,6 +24,7 @@ With cloud agent session sharing, you can view the full remote session for a clo * See every command the agent executed in the virtual environment * Inspect context, logs, and outputs directly in Warp or the web viewer +* Review the prompt, plan, task list, and decisions that led to the result * Ask follow-up questions or give additional instructions after the task completes * Bring the conversation into your local Warp session with Fork to local * Continue working on remote-generated code locally @@ -46,8 +49,10 @@ Once the session loads, you can: * Scroll through the cloud agent's actions * See the prompt, plan, and decisions it made +* Review commands, logs, terminal output, and generated artifacts * Review the code or config changes it produced * Understand what environment it executed in +* Copy the session link into a PR, issue, incident review, or team thread when teammates need the same execution context You’re viewing a remote VM, but the UI behaves like a local Warp session. @@ -88,9 +93,15 @@ Once forked: Cloud agent sessions can be viewed from: -* The Warp desktop app +* The Warp app * A browser via the web viewer * Remote teammates using the shared link * Local Warp sessions after forking You get consistent visibility into the work regardless of where you open it. + +### Related pages + +* [Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/) — Find cloud agent runs by source, status, trigger, or owner. +* [Attach agent session context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs/) — Share a run link with a PR so reviewers can inspect the agent's execution context. +* [Agent Session Sharing](/agent-platform/local-agents/session-sharing/) — Share local Warp agent or third-party CLI agent sessions. diff --git a/src/content/docs/agent-platform/local-agents/interactive-code-review.mdx b/src/content/docs/agent-platform/local-agents/interactive-code-review.mdx index 05837456..6967f812 100644 --- a/src/content/docs/agent-platform/local-agents/interactive-code-review.mdx +++ b/src/content/docs/agent-platform/local-agents/interactive-code-review.mdx @@ -43,13 +43,16 @@ This gives you a familiar pull-request style workflow inside Warp without switch Select any changed line or block and add a comment describing what you want adjusted. Warp anchors each comment to the relevant file and line so the agent understands exactly what to fix. +
![Adding an inline comment on a changed line in the Code Review panel.](../../../../assets/agent-platform/interactive-code-review-adding-comment.png) +
Inline comments in the Code Review panel.
+
### Batch comments and submit once Add as many comments as you need before submitting them. The agent receives your entire batch of feedback, applies the changes in one iteration, and returns an updated diff for verification. -
+
![Adding comments directly in the Code Review view.](../../../../assets/agent-platform/interactive-code-review-batch-comments.png)
Adding comments directly in the Code Review view.
@@ -76,4 +79,5 @@ This workflow can be repeated until the code matches your expectations. Once you're comfortable reviewing agent code locally, try running agents in the cloud for longer or parallel tasks. * **[Cloud Agents quickstart](/agent-platform/cloud-agents/quickstart/)** - Run agents on Warp's infrastructure for background tasks like PR review, issue triage, and dependency updates. +* **[Attach agent session context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs/)** - Share the agent's prompt, plan, commands, logs, validation, and reviewer asks with the PR. * **[Skills](/agent-platform/capabilities/skills/)** - Turn successful agent workflows into reusable, shareable instructions. diff --git a/src/content/docs/agent-platform/local-agents/session-sharing.mdx b/src/content/docs/agent-platform/local-agents/session-sharing.mdx index b052f651..ffd1f266 100644 --- a/src/content/docs/agent-platform/local-agents/session-sharing.mdx +++ b/src/content/docs/agent-platform/local-agents/session-sharing.mdx @@ -6,18 +6,31 @@ description: >- --- import VideoEmbed from '@components/VideoEmbed.astro'; -**Agent Session Sharing** extends Warp's regular [Session Sharing](/knowledge-and-collaboration/session-sharing/) to include full visibility and control over Agent activity. Share any agent session — Oz or third-party — so collaborators can watch progress, review output, and steer the agent from the Warp desktop app, a web browser, or a mobile device. +**Agent Session Sharing** extends Warp's regular [Session Sharing](/knowledge-and-collaboration/session-sharing/) to include full visibility and control over Agent activity. Share any agent session — Oz or third-party — so collaborators can watch progress, review output, and steer the agent from the Warp app, a web browser, or a mobile device. + +Use Agent Session Sharing when teammates need the execution context behind an agent's work, not just the final answer or code diff. A shared agent session can show the prompt, responses, thinking states, tool use, planning steps, terminal output, and follow-up messages in one reviewable link. ## Key capabilities * **Full Agent visibility** - Viewers see Agent prompts, responses, thinking states, tool use, planning steps, and [credit](/support-and-community/plans-and-billing/credits/) consumption in real time -* **Cross-device access** - Open shared sessions from the Warp desktop app, any web browser, or a mobile device. No install required for web viewers. +* **Cross-device access** - Open shared sessions from the Warp app, any web browser, or a mobile device. No install required for web viewers. * **Collaborative editing** - Grant edit access so collaborators can send their own Agent queries, execute commands, and start new conversations * **Multi-viewer support** - Multiple participants can observe and interact with the same session simultaneously, each with their own cursor and avatar * **Remote Control** - Publish third-party agent sessions to the cloud for persistent, asynchronous monitoring and steering from anywhere. See [Remote Control](/agent-platform/cli-agents/remote-control/). +## Review agent work with a shared session + +When you share an agent session, collaborators can inspect the work at the same level of detail you saw while the agent was running. This is useful when: + +* A teammate wants to review how an agent reached a conclusion +* A reviewer needs the agent's execution context alongside a PR or code diff +* An agent used a third-party CLI tool and you want a persistent record of the terminal session +* A workflow needs asynchronous review from a teammate on another machine or mobile device + +Share the link only with collaborators who should be able to see the session contents, including prompts, terminal output, and any context visible in the scrollback. + ## How it works When you share an agent session, Warp publishes it to the cloud and generates a shareable link. The session stays in sync — any new agent output or terminal activity appears for all viewers in real time. The person who shares the session controls who can view and who can interact. @@ -34,12 +47,12 @@ When you share an agent session, Warp publishes it to the cloud and generates a 4. Confirm the share. Warp uploads the session to the cloud and generates a shareable link. 5. Copy the link and share it with teammates, or open it on another device. -
+
![Starting a shared agent session from the right-click context menu](../../../../assets/agent-platform/agent-session-sharing-right-click-menu.png)
Start a shared session via the right click menu.
-
+
![Starting a shared agent session from the Command Palette](../../../../assets/agent-platform/agent-session-sharing-command-palette.png)
Start a shared session via the Command Palette.
@@ -48,7 +61,7 @@ When you share an agent session, Warp publishes it to the cloud and generates a Shared sessions are accessible from: -* **Warp desktop app** - Paste the link into Warp on a different machine for the full desktop experience +* **Warp app** - Paste the link into Warp on a different machine for the full app experience * **Web browser** - Open the shared link in any browser. No app install required. * **Mobile** - Open the link on a phone or tablet browser to check on progress while away from your desk @@ -89,4 +102,5 @@ Multiple participants can join the same session from different machines, browser * [Remote Control](/agent-platform/cli-agents/remote-control/) * [Third-Party CLI Agents](/agent-platform/cli-agents/overview/) * [Cloud Agent Session Sharing](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) +* [Attach agent session context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs/) * [Session Sharing (terminal)](/knowledge-and-collaboration/session-sharing/) diff --git a/src/content/docs/code/code-review.mdx b/src/content/docs/code/code-review.mdx index f411412e..15f258ab 100644 --- a/src/content/docs/code/code-review.mdx +++ b/src/content/docs/code/code-review.mdx @@ -21,7 +21,7 @@ Any uncommitted changes appear in the panel (or compare the changes on your bran -
+
![Full view of Code Review panel and terminal pane.](../../../assets/terminal/code-review-panel-update.png)
Full view of Code Review panel and terminal pane.
@@ -30,6 +30,10 @@ Any uncommitted changes appear in the panel (or compare the changes on your bran To review agent-generated diffs, leave inline comments, batch your feedback, and have the agent apply all requested changes, see [Interactive Code Review](/agent-platform/local-agents/interactive-code-review/). ::: +:::tip +If the agent's changes are headed to a GitHub pull request, include a shared session or cloud run link in the PR so reviewers can inspect the prompt, plan, commands, logs, and validation behind the diff. See [Attach agent session context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs/). +::: + ## Opening the Code Review panel The Code Review panel can be opened in several ways. Each entry point makes it easy to inspect and manage changes without leaving your workflow. @@ -42,23 +46,38 @@ You can also open the Code Review panel with `CMD – SHIFT – +` on macOS or ` In terminal mode, when you're in a Git repository with changes, the Git diff chip shows the number of files modified along with lines added and removed. Clicking the chip opens the Code Review panel with the relevant diffs. +
![Terminal input bar showing the Git diff chip with branch name, modified file count, and lines added and removed](../../../assets/terminal/whole-UDI-bar.png) +
The Git diff chip in the terminal input.
+
+
![Git diff chip with a View changes tooltip showing branch name, file count, and lines changed](../../../assets/terminal/git-chip-tooltip-1.png) +
The Git diff chip tooltip.
+
#### 2. Agent conversation: review changes button When an Agent makes code edits in an [Agent Conversation](/agent-platform/local-agents/interacting-with-agents/), a `Review changes` button appears at the bottom of the conversation. Click the button to open the code review panel. +
![Review changes at bottom of Agent Conversation.](../../../assets/terminal/Blocklist-with-review-changes.png) +
The Review changes button in a conversation.
+
+
![Agent conversation footer with feedback buttons and a Review changes button](../../../assets/terminal/review-changes-in-footer.png) +
The conversation footer actions.
+
#### 3. Agent conversation: toolbelt (bottom right) During an Agent conversation, you can view all changed files in the toolbelt chips at the persistent bottom right. From there, you can open the Code Review panel directly. +
![Agent conversation with toolbelt chips in the bottom right showing file changes and action buttons](../../../assets/terminal/ai_control_panel_buttons_larger_view.png) +
The conversation toolbelt chips.
+
#### 4. Warp tab bar @@ -68,7 +87,10 @@ In any Git-tracked repository, you can open the Code Review panel by clicking th Inside the Code Review panel, you can open the file sidebar to browse all changed files in your repository. Clicking on a file will automatically scroll to that file in the panel. +
![Viewing all edited files in the code review panel, with the file sidebar open.](../../../assets/terminal/whole-git-diff-view-with-one-file-collapsed.png) +
The Code Review panel file sidebar.
+
:::note By default, the Code Review panel opens as a pane on the right, but you can drag it to reposition wherever you prefer. @@ -87,11 +109,20 @@ Warp offers two ways to review changes: You can manually switch between the two views either in the Code Review panel or via the Git diff chip in the terminal input: +
![Changing diff view in the Code Review Panel.](../../../assets/terminal/diff-dropdown-to-change-base-from-the-code-review-pane.png) +
The diff view menu.
+
+
![Changing diff view from the terminal input.](../../../assets/terminal/git-diff-change-base-dropdown.png) +
The Git diff chip menu.
+
-
![Changing diff view against an arbitrary branch.](../../../assets/terminal/arbitrary-branch-diff.png)
+
+![Changing diff view against an arbitrary branch.](../../../assets/terminal/arbitrary-branch-diff.png) +
The arbitrary branch diff menu.
+
Any saved edits made outside of Warp (e.g. in another editor), as well as changes applied by Warp's Agents, appear automatically. The panel updates in real time, ensuring it always reflects the current state of your working file and directory. @@ -99,7 +130,7 @@ Any saved edits made outside of Warp (e.g. in another editor), as well as change The Code Review pane makes it simple to share changes with the Agent. You can attach an entire diff to a prompt so the Agent has full visibility into what was added or removed. -
+
![Attaching a diff as context from the Code Review panel.](../../../assets/terminal/attach-diff-hunk-as-context.png)
Attaching a diff as context from the Code Review panel.
@@ -110,7 +141,10 @@ This ensures responses are grounded in your latest edits, whether you're asking The Code Review panel lets you easily undo changes at different levels. In the gutter next to each diff, you’ll see an option to revert a hunk: roll back a specific set of changes (a “diff hunk”) within a file. This removes the added or modified lines and restores the previous version. +
![Code diff gutter showing the Revert diff hunk tooltip on a changed line](../../../assets/terminal/revert-diff-hunk.png) +
The Revert diff hunk tooltip.
+
When you revert, the changes are immediately updated in your working directory. The file is restored to match the selected version, so you can continue editing or commit without the reverted code. @@ -118,7 +152,10 @@ When you revert, the changes are immediately updated in your working directory. In addition to reviewing and editing diffs directly in the Code Review pane, you can open a file directly in Warp's [Code Editor](/code/code-editor/). +
![Code Review panel header showing file name, lines changed, and buttons for attach, revert, and open in editor](../../../assets/terminal/code-review-header.png) +
The Code Review panel header.
+
* Clicking the **expand button** (right-most button on the header) opens the file in a new editor tab, allowing you to see the full file beyond just the changed lines. * This is useful when you need additional context around a diff, want to make broader edits, or prefer working in the full editor rather than inline. @@ -131,7 +168,10 @@ In addition to reviewing and editing diffs directly in the Code Review pane, you Alternatively, from the Code Review panel, you are able to click and edit the diffs directly: +
![Directly editing code in the Code Review panel inline diff view](/assets/terminal/directly-editing-diffs.gif) +
Editing code in an inline diff.
+
### Sending comments to a running agent @@ -147,7 +187,10 @@ For more on supported agents, see [Third-Party CLI Agents](/agent-platform/cli-a The Code Review panel also lets you discard every uncommitted change on your branch in one action. Clicking Discard all removes all local modifications shown in the panel and restores each file to its state on the base branch. This is useful when you want to reset your working directory, abandon a set of edits, or start a new iteration from a clean slate. +
![Code Review panel header with Uncommitted changes dropdown, attach button, and Discard all button](../../../assets/terminal/discard-all-changes.png) +
The Discard all changes button.
+
Discarding changes will ask you confirm, but still make sure you've saved or backed up anything you want to keep before using it. diff --git a/src/content/docs/enterprise/security-and-compliance/security-overview.mdx b/src/content/docs/enterprise/security-and-compliance/security-overview.mdx index b5101594..e38c9df7 100644 --- a/src/content/docs/enterprise/security-and-compliance/security-overview.mdx +++ b/src/content/docs/enterprise/security-and-compliance/security-overview.mdx @@ -70,6 +70,7 @@ Team admins can enforce telemetry settings organization-wide through the Admin P * **Codebase Context** - During indexing, code is sent to Warp's servers to generate embeddings; the raw code is not stored, only the resulting embeddings are retained * **Agent requests** - Warp sends requests to contracted LLM providers (Anthropic, OpenAI, Google) with Zero Data Retention agreements for Enterprise teams * **BYOLLM** - Requests are proxied through Warp's servers to your cloud infrastructure, where inference runs. Warp does not store the content of these requests. +* **Self-hosted cloud agent execution** - Repository clones, build artifacts, runtime secrets, and execution workspaces stay on your infrastructure. Orchestration metadata, session transcripts, and LLM inference requests and responses route through Warp under ZDR, and can include code context from agent interactions. ### Encryption @@ -166,7 +167,7 @@ Security-relevant controls include: Route agent inference through your own cloud infrastructure for complete control: -* **Data locality** - Cloud agent inference runs in your AWS account +* **Data locality** - Interactive agent inference runs in your AWS account * **Cloud-native IAM** - Authenticate using your user's existing identity and access management process * **No key storage** - Warp never stores your cloud credentials or API keys * **Billing control** - Inference costs billed directly to your cloud account diff --git a/src/content/docs/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs.mdx b/src/content/docs/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs.mdx new file mode 100644 index 00000000..cf3c374d --- /dev/null +++ b/src/content/docs/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs.mdx @@ -0,0 +1,136 @@ +--- +title: Share agent context in GitHub PRs +description: >- + Share a Warp agent session or cloud agent run link in a GitHub pull request + so reviewers can inspect the prompt, plan, commands, logs, and output behind + agent-generated changes. +sidebar: + label: "Attach agent context to PRs" +tags: + - "agents" + - "code-review" + - "session-sharing" +--- + +When an agent helps prepare a pull request, reviewers need the execution context behind the diff: the original prompt, plan, commands, validation results, code changes, and decisions that still need human review. + +Add a Warp session or cloud agent run link to the PR description or a PR comment. That link gives reviewers a record of the agent's work alongside the GitHub diff. + +Use these Warp docs and surfaces to collect the right context: + +* [Agent Session Sharing](/agent-platform/local-agents/session-sharing/) for local Warp agents or third-party CLI agents running in Warp. +* [Cloud agent session sharing](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) for cloud agent runs started from Slack, Linear, GitHub Actions, schedules, the Oz CLI, or the API. +* The [Code Review panel](/code/code-review/) and [Interactive Code Review](/agent-platform/local-agents/interactive-code-review/) to inspect and refine the actual code diff before or after you share the PR. + +## What to include in the PR + +Add the shared session link near the top of the PR description or as a pinned PR comment. Pair it with a short review summary so teammates can decide what to inspect first. + +At minimum, include: + +* **Goal** - What the agent was asked to do. +* **Agent context** - Link to the shared Warp session or cloud agent run. +* **Changed files** - The main areas reviewers should inspect. +* **Validation** - Tests, lint, typecheck, build, or manual checks the agent or author ran. +* **Known risks** - Anything the agent could not verify, skipped, or changed speculatively. +* **Reviewer asks** - Specific files, behaviors, or decisions that need human review. + +## PR comment template + +```markdown +## Agent-generated change summary + +**Goal:** +**Agent session:** +**Changed files:** +**Validation:** +**Known risks:** +**Reviewer asks:** + +Notes: +- The session link contains the agent prompt, plan, commands, logs, output, and follow-up messages where available. +- Please review the code diff and the agent context before merging. +``` + +## 1. Share the agent session or cloud run + +Choose the link based on where the agent ran. + +### Local agent or third-party CLI agent in Warp + +If the agent ran locally in Warp, share the session: + +1. Open the agent session in Warp. +2. In the conversation pane header, open the three-dot menu, then click **Share session**. Do not use the top-level **Share** icon if you need the session transcript. +3. Choose the scrollback range to include. +4. Copy the shared session link. +5. Paste the link into the PR description or a PR comment. + +See [Agent Session Sharing](/agent-platform/local-agents/session-sharing/) for the full sharing flow. + +### Cloud agent run + +If the agent ran in the cloud, use the cloud run session link: + +1. Open the run from the [Agent Management Panel](/agent-platform/cloud-agents/managing-cloud-agents/) in the Warp app or the [Runs page in the Oz web app](/agent-platform/cloud-agents/oz-web-app/#runs). +2. Confirm the session shows the run context reviewers need. +3. Copy the cloud agent session link. +4. Paste the link into the PR description or a PR comment. + +See [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) for details. + +## 2. Review the diff before handing it off + +Before asking teammates to review the PR, inspect the code yourself in Warp: + +1. Open the [Code Review panel](/code/code-review/). +2. Compare the branch against the PR base branch, not just uncommitted changes. +3. Review the changed files, revert obvious mistakes, and leave inline comments for the agent if it should revise anything. +4. Run your project's tests, lint, typecheck, or build. +5. Add validation results to the PR summary. + +For a detailed local workflow, see [How to review AI-generated code](/guides/agent-workflows/how-to-review-ai-generated-code/) and [Interactive Code Review](/agent-platform/local-agents/interactive-code-review/). + +## 3. Make the agent context easy to review + +Reviewers should not have to read an entire transcript to understand what happened. In the PR summary, call out the most important parts of the session: + +* The original prompt or task source. +* The plan the agent followed. +* Commands that changed or validated the code. +* Files or directories that need extra attention. +* Any failed commands and how they were resolved. +* Any assumptions the agent made. + +If the PR came from an automated workflow, include the trigger source too. For example: Slack thread, Linear issue, GitHub Actions workflow, scheduled agent, Oz CLI command, or API call. + +## 4. Watch for sensitive context before sharing + +Shared sessions can include prompts, terminal output, logs, command history, environment details, and other scrollback. Before putting a session link in a PR: + +* Check whether the session includes secrets, tokens, private customer data, or unrelated terminal output. +* Choose the narrowest useful scrollback range for local session sharing. +* Prefer links visible only to the reviewers who need the context. +* If the agent produced logs or artifacts with sensitive values, remove or rotate those values before broader sharing. + +See [Secret Redaction](/support-and-community/privacy-and-security/secret-redaction/) for more on how Warp helps detect secrets. + +## 5. Keep the PR review focused + +Use the session link to make review faster, not to replace review. The GitHub diff is still the source of truth for what will merge. + +Good reviewer asks: + +* "Check the migration and rollback path in `db/migrations/`." +* "Verify the agent's test coverage for the auth edge cases." +* "Review the session commands around the failing lint step and the final fix." +* "Confirm whether the agent's assumption about the API contract is correct." + +Avoid vague asks like "review the agent output." Point reviewers to the decision, file, or validation result that needs human judgment. + +## Next steps + +* Use [Agent Session Sharing](/agent-platform/local-agents/session-sharing/) to share local or third-party agent sessions. +* Use [Cloud agent session sharing](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) to inspect cloud agent runs. +* Use [Code Review panel](/code/code-review/) to review Git diffs in Warp. +* Use [Interactive Code Review](/agent-platform/local-agents/interactive-code-review/) to leave inline comments and send feedback back to an agent. diff --git a/src/content/docs/guides/agent-workflows/how-to-review-ai-generated-code.mdx b/src/content/docs/guides/agent-workflows/how-to-review-ai-generated-code.mdx index 4ddc7e6f..6a48accb 100644 --- a/src/content/docs/guides/agent-workflows/how-to-review-ai-generated-code.mdx +++ b/src/content/docs/guides/agent-workflows/how-to-review-ai-generated-code.mdx @@ -46,14 +46,14 @@ Once the agent has finished the task, open Warp's [Code Review panel](/code/code * **Review changes button**: After an agent conversation, click **Review changes** at the bottom of the conversation * **Tab bar**: Click the Code Review button in the top-right corner of Warp -
+
![Code Review button in the top-right corner of the Warp title bar showing file and line change counts](../../../../assets/guides/code-review-button.png)
The Code Review button.
The panel shows all uncommitted changes as a visual diff, grouped by file. Additions are highlighted in green with a `+` prefix, removals in red with a `-` prefix. -
+
![Code Review panel showing file diffs between branches](../../../../assets/guides/code-review-panel-with-diffs.png)
Code Review panel with diffs.
@@ -68,7 +68,7 @@ With the Code Review panel, you can review changes file-by-file: Focus on the areas where agents are most likely to make mistakes: imports, error handling, and anything that touches security or authentication. -
+
![Code Review panel with file navigation sidebar showing changed files](../../../../assets/guides/code-review-file-sidebar.png)
Changed files sidebar.
@@ -78,7 +78,7 @@ Focus on the areas where agents are most likely to make mistakes: imports, error Click the "Add comment" button on any line or block of code and add a comment describing what needs to change. Warp anchors each comment to the exact file and line, so any agent understands precisely what to fix. You can add as many comments as you need before submitting — Warp batches them so the agent receives all your feedback at once instead of processing changes one at a time. -
+
![Adding an inline comment on a diff line in the Code Review panel](../../../../assets/guides/code-review-inline-comment.png)
Inline comments on specific diff lines.
@@ -122,6 +122,7 @@ You now have a structured workflow for reviewing AI-generated code in Warp: visu Explore related guides and features: * [Set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) or [Set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) to start using third-party agents in Warp +* [Attach agent session context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs/) to give reviewers the prompt, plan, commands, logs, and validation behind agent-generated changes * [Run multiple agents at once](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) to compare outputs from different agents on the same task * [Claude Code in Warp](https://www.warp.dev/agents/claude-code) | [Codex in Warp](https://www.warp.dev/agents/codex) | [Gemini CLI in Warp](https://www.warp.dev/agents/gemini-cli) | [OpenCode in Warp](https://www.warp.dev/agents/opencode) — agent-specific overviews on the Warp marketing site * [Code Review panel](/code/code-review/) — full reference for all Code Review features diff --git a/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx b/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx index 1516476d..9d6a9278 100644 --- a/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx +++ b/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx @@ -1,20 +1,50 @@ --- title: How to run multiple AI coding agents description: >- - Run Claude Code, Codex, and other AI coding agents in parallel using - vertical tabs, tab configs, and notifications to manage multiple sessions at - once. + Coordinate multiple AI coding agents, including Claude Code and Codex, across + separate workspaces, Git worktrees, cloud agents, and orchestrated runs with + clear task ownership, validation, and review handoff. sidebar: label: "Run multiple AI coding agents" --- -Different agents have different strengths. Claude Code might handle refactoring well while Codex might excel at test generation. Instead of choosing one, you can run them in parallel. Assign different tasks to different agents, compare their outputs on the same problem, or have one agent build while another reviews. This guide shows you how to set up a multi-agent workflow in Warp and manage it effectively. Plan on about 15 minutes. +Use multiple coding agents when work can be split into independent tasks, reviewed from separate branches, or delegated to cloud agents while you keep working locally. In Warp, you can coordinate agents in three ways: + +* **Local parallel sessions** - run Warp Agent, Claude Code, Codex, OpenCode, or another CLI agent in separate tabs or panes. +* **Isolated worktrees** - give each agent its own Git worktree and branch so parallel edits do not collide. +* **Oz cloud orchestration** - use `/orchestrate`, `/plan`, the Oz CLI, the Oz web app, or the Oz API to fan work out to child agents in cloud environments. + +The best multi-agent workflows have one thing in common: each agent owns a clear slice of work, reports back with validation results, and hands off a branch, diff, PR, or concise finding you can review. + +Plan on about 15 minutes for the local setup. Cloud orchestration takes longer only if you need to create or select an [environment](/agent-platform/cloud-agents/environments/) first. ## Prerequisites -* **Any coding agent** — For example, Warp's built-in agent, [Claude Code](/guides/external-tools/how-to-set-up-claude-code/), or [Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/). Any combination of supported agents works well: Oz by Warp, Claude Code, Codex, OpenCode, Gemini CLI, Amp, Pi, Droid, and others. +* **Any coding agent** — Any combination of supported agents works well: Warp Agent, [Claude Code](/guides/external-tools/how-to-set-up-claude-code/), [Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/), OpenCode, Gemini CLI, Amp, Pi, Droid, and others. * **A Git-tracked project** — Notifications and code review work best in a Git repository. +## Choose a multi-agent pattern + +| Pattern | Use it when | How to run it in Warp | +| ------- | ----------- | --------------------- | +| Same task, different agents | You want to compare approaches or pick the best implementation. | Run each agent in a separate tab and worktree, then compare diffs in the [Code Review panel](/code/code-review/). | +| Split by file or subsystem | A feature spans independent modules that can be changed in parallel. | Assign each agent a worktree, branch, file boundary, and validation command. | +| Builder plus reviewer | One agent implements while another reviews, writes tests, or checks edge cases. | Put the reviewer in a read-only or review-focused tab, or use a separate branch for test-only changes. | +| Cloud fan-out | The work is large, slow, or can run away from your laptop. | Use [Multi-agent orchestration](/agent-platform/cloud-agents/orchestration/) or [Running orchestrated agents](/agent-platform/cloud-agents/orchestration/multi-agent-runs/) to spawn cloud children. | +| Repeatable fleet workflow | You want the same agent pattern on every PR, issue, schedule, or release. | Use a cloud agent with a trigger, skill, or API workflow, then inspect parent and child runs in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/). | + +## Plan the split before launching agents + +Before you start agents, decide: + +* **Task ownership** - Which files, packages, tests, issues, or PRs each agent owns. +* **Workspace ownership** - Which branch or Git worktree each agent uses. +* **Validation ownership** - Which agent runs unit tests, typechecks, lint, smoke tests, or manual verification. +* **Handoff format** - Whether each agent should leave a local diff, branch, PR, patch, summary, or code review comments. +* **Merge strategy** - Whether you will keep one winner, cherry-pick changes, merge multiple branches, or open separate PRs. + +Use boundaries that minimize overlapping edits. For example, assign one agent to `packages/api`, another to `packages/web`, and a third to tests or docs. If two agents must touch the same files, make one the owner and ask the other to review or propose changes without editing. + ## 1. Switch to vertical tabs Vertical tabs are the foundation of a multi-agent workflow. Unlike horizontal tabs, they show rich metadata for each session: which agent is running, which branch you're on, which directory, and the current status. @@ -24,12 +54,12 @@ To enable vertical tabs: 2. Select **Use vertical tab layout**. You can configure what information to display for each tab: -* The running agent (Oz, Claude Code, Codex, etc.) +* The running agent (Warp Agent, Claude Code, Codex, etc.) * The current Git branch * The working directory * A status indicator showing whether the agent is active, waiting for input, or idle -
+
![Warp vertical tabs sidebar showing multiple terminal sessions with branch metadata](../../../../assets/terminal/vertical-tabs-multi-agent.png)
Vertical tabs overview.
@@ -62,7 +92,19 @@ Refactor src/auth/ to use async/await instead of callbacks Write comprehensive tests for src/auth/ covering edge cases ``` -
+For split work, include the same operating contract in every prompt: + +``` +You own src/auth/ and tests/auth/. +Do not edit src/billing/ or src/api/payments/. +Work on branch feature/auth-refactor-claude in ../your-project-claude. +Run npm test -- auth and npm run typecheck before handing off. +When done, report changed files, validation results, and any risks. +``` + +If one agent depends on another, do not let both edit at once. Ask the first agent to finish and report its branch, patch, or PR before starting the dependent work. + +
![Multiple agent tabs in Warp's vertical sidebar showing session status, branch, and directory metadata](../../../../assets/terminal/multi-agents.png)
Vertical tab with agent details.
@@ -83,7 +125,7 @@ Notification setup varies by agent: Agent notifications are currently supported for Claude Code, Codex, and OpenCode. For setup details, see [Agent notifications](/agent-platform/capabilities/agent-notifications/). For a full breakdown of which features work with each agent, see the [third-party CLI agents feature matrix](/agent-platform/cli-agents/overview/). ::: -
+
![Warp notification popup showing an agent requesting permission to edit a file](../../../../assets/guides/tab-notification-indicator.png)
Agent approval notification.
@@ -105,7 +147,7 @@ If you regularly work with the same multi-agent setup, save it as a tab config s 1. Hover over the tab and click the three dots on the right-hand side. 2. Click **Save as new config**. -
+
![Creating a new tab config from the tab context menu in Warp](../../../../assets/terminal/save-new-tab-config.png)
Saving a tab config.
@@ -122,22 +164,73 @@ Tab configs pair well with [Git worktrees](/code/git-worktrees/). Create a workt ## 6. Use Git worktrees for isolated agent workspaces -When multiple agents modify the same files, they can create conflicts. Git worktrees solve this by giving each agent its own copy of your repo on a separate branch. +When multiple agents modify the same files, they can create conflicts. Git worktrees give each agent its own copy of your repo on a separate branch. -Create worktrees for each agent: +1. Create one worktree per agent so each agent has an isolated branch. -```bash -git worktree add ../your-project-claude feature/claude-refactor -git worktree add ../your-project-codex feature/codex-refactor -``` + ```bash + git worktree add ../your-project-claude feature/claude-refactor + git worktree add ../your-project-codex feature/codex-refactor + ``` +2. Point each agent tab at its assigned worktree directory. +3. Give every worktree a branch name that makes ownership obvious: + * `agent/claude-auth-refactor` + * `agent/codex-auth-tests` + * `agent/warp-review-pass` -Then point each agent tab at its own worktree directory. Tab configs complement this workflow. Define each worktree directory and agent startup command in a config, then recreate the full setup with one click. +4. Keep a merge note somewhere lightweight, such as your parent Warp Agent conversation or PR description: + * Which branch each agent owns. + * Which tests each agent ran. + * Which branch should be merged first. + * Which conflicts or follow-up decisions remain. +5. After both agents finish, compare the branches and merge the best results. + ```bash + git diff feature/claude-refactor..feature/codex-refactor + ``` -After both agents finish, compare the branches and merge the best results: +6. Remove worktrees after you merge or discard the branch. + ```bash + git worktree remove ../your-project-claude + git worktree remove ../your-project-codex + ``` -```bash -git diff feature/claude-refactor..feature/codex-refactor -``` +## 7. Fan out work to cloud agents + +Use cloud agents when the work is long-running, resource-intensive, easy to shard, or better handled away from your local machine. For example: + +* Review every open PR in a repo. +* Run a migration across many packages. +* Ask one child agent per service to inspect logs, tests, or incidents. +* Let a parent agent coordinate a plan while children research, implement, or validate. + +1. Start in the Warp app with `/orchestrate` when you want a parent agent to propose the child-agent breakdown. + + ```text + /orchestrate Split this TypeScript monorepo migration by package. Use one child agent per package, require each child to run package tests, and summarize changed files and risks before merge. + ``` + +2. Use `/plan` for larger changes where you want to review the plan, orchestration config, child ownership, and merge strategy before agents launch. +3. For repeatable or unattended workflows, start the parent from the Oz CLI, the Oz web app, or the Oz API. See [Running orchestrated agents](/agent-platform/cloud-agents/orchestration/multi-agent-runs/) for launch options. +4. Inspect parent and child runs from the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) or the [Agent Management Panel](/agent-platform/cloud-agents/managing-cloud-agents/) in the Warp app. + +Cloud orchestration is the best fit when you need: + +* **Parallel fan-out** across many files, packages, PRs, issues, or services. +* **Clear observability** across parent and child runs. +* **Durable handoff** through child run summaries, session links, artifacts, PRs, or messages. +* **Team-scale execution** from Slack, Linear, schedules, GitHub Actions, the CLI, or the API. + +## 8. Validate, merge, and hand off + +Do not merge every agent's output automatically. Use a fan-in pass: + +1. Review each agent's summary, changed files, and validation results. +2. Open the [Code Review panel](/code/code-review/) for local branches, or inspect cloud run artifacts and session links for cloud children. +3. Merge or cherry-pick one branch at a time. +4. Re-run the full validation suite from the final integrated branch. +5. Attach context for reviewers: agent session links, changed files, validation commands, known risks, and reviewer asks. + +For GitHub handoff, see [Attach agent session context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs/). For reviewing the generated code itself, see [How to review AI-generated code](/guides/agent-workflows/how-to-review-ai-generated-code/). ## Productivity tips @@ -153,7 +246,10 @@ You set up a multi-agent workspace with vertical tabs, launched different agents Explore related guides and features: * [How to review AI-generated code](/guides/agent-workflows/how-to-review-ai-generated-code/) — review and refine the code your agents produced -* [Set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) or [Set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) if you haven't installed both yet +* [Attach agent session context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs/) — give reviewers the agent context behind a PR +* [Multi-agent orchestration](/agent-platform/cloud-agents/orchestration/) — coordinate parent and child agents across local and cloud runs +* [Running orchestrated agents](/agent-platform/cloud-agents/orchestration/multi-agent-runs/) — start orchestrated runs from Warp, the Oz CLI, the Oz web app, or the Oz API +* [Set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) or [Set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) — install both agents if you haven't already * [Claude Code in Warp](https://www.warp.dev/agents/claude-code) — overview of Claude Code support in Warp * [Codex in Warp](https://www.warp.dev/agents/codex) — overview of Codex support in Warp * [Gemini CLI in Warp](https://www.warp.dev/agents/gemini-cli) — overview of Gemini CLI support in Warp diff --git a/src/content/docs/guides/agent-workflows/how-to-run-unattended-agents.mdx b/src/content/docs/guides/agent-workflows/how-to-run-unattended-agents.mdx new file mode 100644 index 00000000..07e68717 --- /dev/null +++ b/src/content/docs/guides/agent-workflows/how-to-run-unattended-agents.mdx @@ -0,0 +1,124 @@ +--- +title: How to run unattended agents +description: >- + Run Warp agents in the background with schedules, Slack and Linear triggers, + GitHub Actions, the Oz CLI, or the API, then inspect every cloud agent run + from the Oz web app or the Warp app. +sidebar: + label: "Run unattended agents" +tags: + - "agents" + - "cloud-agents" + - "schedules" +--- + +Warp cloud agents can run unattended from schedules, team tools, CI, the Oz CLI, or the API. Use them when you want an agent to keep working after you leave your terminal, react to external events, or run recurring maintenance without a human starting each run. + +Every unattended workflow creates a cloud agent run that your team can inspect later. Open runs from the [Runs page in the Oz web app](/agent-platform/cloud-agents/oz-web-app/#runs), the [Agent Management Panel](/agent-platform/cloud-agents/managing-cloud-agents/) in the Warp app, or the session link posted back to the tool that triggered the agent. + +## Choose a trigger + +Use this table to decide where an unattended agent should start. + +| Trigger | Use it when | Where to configure | Where to inspect | +| ------- | ----------- | ------------------ | ---------------- | +| Scheduled agents | Work should run on a predictable cadence, like weekly triage, nightly dependency checks, or monthly cleanup. | [Scheduled Agents](/agent-platform/cloud-agents/triggers/scheduled-agents/) or the [Scheduled Agents quickstart](/agent-platform/cloud-agents/triggers/scheduled-agents-quickstart/) | Oz web app Runs page, Agent Management Panel in the Warp app, schedule history, and cloud agent session links | +| Slack | A teammate should delegate work from a Slack message or thread. | [Slack integration](/agent-platform/cloud-agents/integrations/slack/) | Slack thread updates, Oz web app Runs page, Agent Management Panel in the Warp app, and the shared run session | +| Linear | An issue, comment, or assignment should start the agent. | [Linear integration](/agent-platform/cloud-agents/integrations/linear/) | Linear issue updates, Oz web app Runs page, Agent Management Panel in the Warp app, and the shared run session | +| GitHub Actions | A repository event, PR workflow, issue workflow, or CI failure should start the agent. | [GitHub Actions](/agent-platform/cloud-agents/integrations/github-actions/) | GitHub Actions logs, PR or issue comments, Oz web app, and cloud agent runs | +| Oz CLI | You want to start a named cloud run from a terminal, script, or local automation. | [Oz CLI](/reference/cli/#running-agents-remotely-oz-agent-run-cloud) | CLI output, Oz web app Runs page, Agent Management Panel in the Warp app, and cloud agent session links | +| Oz API or SDK | Your internal system should create, query, or monitor runs programmatically. | [Oz API and SDK](/reference/api-and-sdk/) | Your system, API results, Oz web app, and run sessions | + +## Choose a workflow pattern + +### Run recurring maintenance + +Use [Scheduled Agents](/agent-platform/cloud-agents/triggers/scheduled-agents/) for tasks that should happen on a fixed cadence. Good fits include: + +* dependency update checks +* stale issue or PR triage +* repository hygiene +* documentation refreshes +* recurring reports or audits + +Each scheduled run starts a fresh cloud agent session and records its own task history, so you can review what ran, when it ran, and what the agent did. + +### Delegate work from Slack or Linear + +Use [Slack](/agent-platform/cloud-agents/integrations/slack/) or [Linear](/agent-platform/cloud-agents/integrations/linear/) when the task starts from team conversation or issue context. These integrations are best for: + +* turning a Slack thread into an implementation task +* asking an agent to investigate a Linear issue +* generating a PR from a bug report or product request +* letting teammates monitor progress without opening Warp + +The agent posts progress updates back to the source thread or issue and provides a shared run link for deeper inspection. + +### React to GitHub events + +Use [GitHub Actions](/agent-platform/cloud-agents/integrations/github-actions/) when the trigger should be tied to a repository event. + +For example: + +* review a PR when it opens +* respond to an `@oz-agent` comment +* summarize issues on a schedule +* attempt a fix when CI fails +* suggest fixes for review comments + +The GitHub Action can pass event data, prior step output, and repository context into the agent prompt. The agent can comment, review, or open branches depending on the workflow permissions you grant. + +### Start runs from scripts or internal systems + +Use the [Oz CLI](/reference/cli/#running-agents-remotely-oz-agent-run-cloud) for scripts and terminal workflows. Use the [Oz API and SDK](/reference/api-and-sdk/) when another service should create or monitor runs. This is useful for: + +* internal dashboards +* custom webhooks +* CI systems outside GitHub Actions +* recurring jobs managed by your own scheduler +* workflows that need to query run status or results programmatically + +Name cloud runs consistently with `--name` so your team can filter and review related runs later. + +## Define the run before deploying + +Before deploying an unattended agent, define: + +* **Trigger** - What starts the run: schedule, Slack, Linear, GitHub event, CLI command, API request, or another automation. +* **Context** - Which repository, issue, thread, PR, logs, or files the agent needs. +* **Environment** - Where the agent runs, including repos, image, setup commands, secrets, and any MCP servers. +* **Permissions** - What the agent can read or write in GitHub, Slack, Linear, or other systems. +* **Output** - Whether the agent should comment, open a PR, generate an artifact, post a summary, or only report findings. +* **Review path** - Where a human will inspect the run, validate results, and approve changes. + +If the agent can change code or infrastructure, keep the instructions narrow and make validation explicit. + +## Review unattended runs + +Unattended does not mean invisible. Use these surfaces to review what happened: + +* [Oz web app](/agent-platform/cloud-agents/oz-web-app/) - View runs, schedules, run metadata, and session transcripts from a browser or mobile device. +* [Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Filter runs by source, status, day, creator, or trigger. +* [Cloud agent session sharing](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) - Inspect the prompt, plan, commands, logs, output, and follow-up messages where available. +* [Oz API and SDK](/reference/api-and-sdk/) - Query runs and build internal monitoring around status, runtime, or outcomes. + +When a run creates a PR, include the cloud run link in the PR description or a comment. See [Attach agent session context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs/) for a template. + +## Start with one reviewable workflow + +Start with one narrow workflow before deploying many unattended agents: + +1. Pick one trigger and one repository. +2. Use a focused prompt or skill. +3. Run it manually or with **Run now** before enabling a recurring schedule. +4. Confirm the run has the right environment, secrets, and permissions. +5. Check the output and session transcript. +6. Add a review or approval step before merging code changes. +7. Expand the workflow only after the first runs are predictable. + +## Next steps + +* [Scheduled Agents quickstart](/agent-platform/cloud-agents/triggers/scheduled-agents-quickstart/) - Create your first recurring agent in the Oz web app. +* [Integrations quickstart](/agent-platform/cloud-agents/integrations/quickstart/) - Trigger agents from Slack or Linear. +* [GitHub Actions quickstart](/agent-platform/cloud-agents/integrations/quickstart-github-actions/) - Add an agent to a PR review workflow. +* [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) - Inspect and share unattended run sessions. diff --git a/src/content/docs/guides/agent-workflows/running-multiple-agents-at-once-with-warp.mdx b/src/content/docs/guides/agent-workflows/running-multiple-agents-at-once-with-warp.mdx index cce8860c..32f29df9 100644 --- a/src/content/docs/guides/agent-workflows/running-multiple-agents-at-once-with-warp.mdx +++ b/src/content/docs/guides/agent-workflows/running-multiple-agents-at-once-with-warp.mdx @@ -92,3 +92,5 @@ Open the Agent Mode Dashboard to see: * Logs and outputs You can refine or cancel tasks mid-run if needed, or switch back to manual commands. + +For a workflow-oriented setup guide that covers task decomposition, worktrees, cloud orchestration, validation, and review handoff, see [How to run multiple AI coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/). diff --git a/src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx b/src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx index 183ad825..a1bda2ac 100644 --- a/src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx +++ b/src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx @@ -1,92 +1,140 @@ --- -title: Using MCP Servers with Warp +title: Connect developer tools to agents with MCP workflows description: >- - Connect MCP servers to Warp's agent, add Rules for automatic tool selection, - and resolve tickets using external systems like Linear. + Use Model Context Protocol (MCP) servers to connect Warp agents to developer + tools like GitHub, Linear, Sentry, Figma, Notion, and internal services across + local and cloud agent workflows. sidebar: label: "Connect Agents to MCP servers" +tags: + - "mcp" +featured: true --- import VideoEmbed from '@components/VideoEmbed.astro'; -### 1. What Are MCP Servers? +MCP servers let Warp agents use external tools and data sources through a standard interface. Add an MCP server when an agent needs to read issues, inspect pull requests, query incidents, fetch design context, call internal APIs, or update systems outside the terminal. -MCP (Model Context Protocol) servers let Warp agents connect to external systems like GitHub, Linear, or Jira — so they can read, write, and reason about those systems natively. +Warp supports MCP in two places: -Each MCP server adds its own “tools” to Warp’s agent.\ -For example: +* **Local agents in the Warp app** use MCP servers configured in **Settings** > **Agents** > **MCP servers**, Warp Drive, or file-based config. +* **Cloud agents** use MCP servers passed through the Oz CLI, agent config files, or Warp-shared MCP server UUIDs. -* The Linear MCP Server handles tickets. -* The GitHub MCP Server handles pull requests and issues. +Use this guide to choose the right setup path, then jump to the source docs for exact configuration syntax. ---- +## Choose local or cloud MCP -### 2. Problem Setup +| Workflow | Use it when | Configure MCP with | Source docs | +| -------- | ----------- | ------------------ | ----------- | +| Local Warp agent | You are working interactively in Warp and want the agent to use tools from your machine or desktop-authenticated services. | Warp MCP settings, Warp Drive MCP servers, `.warp/.mcp.json`, or provider config files. | [Model Context Protocol (MCP)](/agent-platform/capabilities/mcp/) | +| Third-party CLI agent in Warp | You run Claude Code, Codex, OpenCode, or another CLI agent in Warp and want shared MCP config across tools. | File-based MCP config that Warp can detect and approve. | [File-based MCP servers](/agent-platform/capabilities/mcp/#file-based-mcp-servers) | +| Cloud agent run | The agent runs in a cloud environment from Slack, Linear, schedules, GitHub Actions, the CLI, or the API. | `--mcp`, an agent config file, or a Warp-shared MCP UUID. | [MCP Servers for cloud agents](/agent-platform/cloud-agents/mcp/) | +| Repeatable automation | You need the same MCP tools every time a scheduled agent, integration, or CI workflow runs. | Agent config files plus [Agent Secrets](/agent-platform/cloud-agents/secrets/) for credentials. | [MCP servers (CLI reference)](/reference/cli/mcp-servers/) | -Andrew starts with Warp’s universal input, but it doesn’t yet know what a “ticket” is. +## Common MCP workflows -> Prompt Example:\ -> “Help me solve this ticket.” +### Pull GitHub or Linear context into a local coding session -At this point, Warp can’t find or interpret the ticket, because no MCP server is connected. +Use local MCP when you want an interactive agent to understand an issue, PR, or ticket while you work in Warp. ---- +Example workflow: -### 3. Adding the Linear MCP Server +1. In the Warp app, add a GitHub or Linear MCP server from **Settings** > **Agents** > **MCP servers**. +2. Start a local agent conversation in the repo. +3. Ask the agent to fetch the issue, inspect linked context, and make a plan. +4. Review changes in the [Code Review panel](/code/code-review/). +5. Use [Agent Session Sharing](/agent-platform/local-agents/session-sharing/) if teammates need to inspect the agent context. -To connect Linear: +For setup details, see [Model Context Protocol (MCP)](/agent-platform/capabilities/mcp/). -1. Open the **MCP Panel** in Warp -2. Click **Add Server** -3. Paste in the JSON configuration for the Linear MCP Server +### Give cloud agents access to developer tools -Once added, Warp: +Use cloud MCP when an unattended or remote agent needs tool access while it runs away from your machine. -* Starts the MCP server -* Loads its tools (e.g., `get_ticket`, `update_ticket`, `create_ticket`) -* Makes them available to the agent instantly +Example workflow: ---- +1. Create or identify the MCP server the cloud agent should use. +2. Store required credentials as [Agent Secrets](/agent-platform/cloud-agents/secrets/) instead of hardcoding tokens in config files. +3. Attach the MCP server with `--mcp`, a config file, or a Warp-shared MCP UUID. +4. Run the cloud agent from the Oz CLI, Slack, Linear, GitHub Actions, a schedule, or the API. +5. Inspect the run in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) or [Cloud agent session sharing](/agent-platform/cloud-agents/viewing-cloud-agent-runs/). -### 4. Using Rules with MCP Servers +For schema and cloud-specific limitations, see [MCP Servers for cloud agents](/agent-platform/cloud-agents/mcp/). -Andrew adds a rule called **check-linear**, which helps the agent automatically associate “tickets” with the Linear MCP Server. +### Share an MCP server with a team -> **Rule Example:**\ -> “When the user says ‘ticket,’ check Linear.” +Use shared MCP servers when multiple teammates or workflows need the same tool connection. -Rules make context switching between systems seamless — the agent doesn’t need reminders. +For local agents, share the server from the MCP settings page. Warp scrubs sensitive environment values and prompts teammates to provide their own values when they install it. ---- +For cloud agents, reference a Warp-shared MCP server by UUID with the Oz CLI: -### 5. Dynamic Context Loading +```sh +oz mcp list +``` -Warp’s MCP support is **dynamic**: +Then pass the UUID to an agent run: -* You can start a conversation without any connected MCPs -* Add one mid-session -* The agent automatically updates its context on the next message +```sh +oz agent run-cloud --mcp "" --prompt "Summarize the latest production incidents" +``` -No need to restart Warp or reset your session. +See [MCP servers (CLI reference)](/reference/cli/mcp-servers/) for all `--mcp` formats. ---- +## Local MCP setup paths -### 6. Running the Task +For local agents, choose one of these paths: -After adding Linear, Andrew runs: +* **Warp settings** - Best for one-off setup and interactive use. In the Warp app, add servers from **Settings** > **Agents** > **MCP servers**. +* **Warp Drive** - Best for MCP servers you want to manage as Warp Drive objects. +* **File-based config** - Best when MCP config should live with a repo or follow you across Warp, Claude Code, Codex, and other agent tools. +* **`/agent-add-mcp` skill** - Best when you want Warp's agent to create or update `.warp/.mcp.json` with your approval. -> “Help me solve this ticket.” +File-based MCP is useful for teams because config can be versioned with a project, but it also needs review. Warp requires approval before project-scoped servers start so cloned repos cannot silently launch commands. -Now the agent: +## Cloud MCP setup paths -* Queries Linear for the ticket -* Pulls all related context -* Reads the codebase for linked references -* Generates the appropriate fix +For cloud agents, choose one of these paths: -He verifies the output by running: +* **Warp-shared MCP UUID** - Best when a server is already configured and shared in Warp. +* **Inline JSON** - Best for quick experiments. +* **JSON file** - Best for reusable scripts. +* **Agent config file** - Best for production workflows where model, environment, prompt, and MCP servers should live together. -```bash -cargo run -``` +Cloud agents run away from your desktop. Any secrets required by MCP tools should be available in the cloud run through [Agent Secrets](/agent-platform/cloud-agents/secrets/) or the execution environment, not only in your local shell. + +:::caution +OAuth-based MCP servers are not currently supported directly for cloud agents. If a server requires browser-based OAuth, use it with a local agent, choose a token-based/server-side configuration if the provider supports it, or pass the relevant artifact as context another way. +::: + +## Example tools MCP can connect + +Warp supports MCP servers for many developer tools, including: + +* **GitHub** - Read issues, PRs, files, and repository metadata. +* **Linear** - Fetch issues, update tickets, and reason over project context. +* **Sentry** - Inspect errors, traces, and release context. +* **Figma** - Pull design context for UI work. +* **Notion** - Retrieve docs, specs, and project notes. +* **Internal tools** - Expose your own APIs through a custom MCP server. + +For example configurations and demos, see the MCP server examples in [Model Context Protocol (MCP)](/agent-platform/capabilities/mcp/#mcp-server-configuration-examples) and the [MCP guides listed on the Guides page](/guides/). + +## Security checklist + +Before giving an agent tool access through MCP: + +* Use the narrowest credentials and scopes that let the workflow run. +* Prefer service accounts for team or scheduled workflows. +* Store cloud-run credentials in [Agent Secrets](/agent-platform/cloud-agents/secrets/). +* Review file-based MCP config before approving it, especially commands, args, environment variables, and URLs. +* Treat MCP logs as sensitive if they contain API responses, tokens, request headers, or private data. +* For cloud agents, confirm whether the MCP server can be reached from the cloud environment or self-hosted worker. + +## Next steps + +* [Model Context Protocol (MCP)](/agent-platform/capabilities/mcp/) - Configure MCP servers for local agents in the Warp app. +* [MCP Servers for cloud agents](/agent-platform/cloud-agents/mcp/) - Configure MCP servers for cloud runs and automation. +* [MCP servers (CLI reference)](/reference/cli/mcp-servers/) - Use `--mcp` with UUIDs, inline JSON, or files. +* [Agent Secrets](/agent-platform/cloud-agents/secrets/) - Store credentials for cloud agent runs. \ No newline at end of file diff --git a/src/content/docs/reference/cli/mcp-servers.mdx b/src/content/docs/reference/cli/mcp-servers.mdx index 42cff41d..1a7a2957 100644 --- a/src/content/docs/reference/cli/mcp-servers.mdx +++ b/src/content/docs/reference/cli/mcp-servers.mdx @@ -9,7 +9,7 @@ sidebar: MCP servers connect agents to external systems like GitHub, Linear, or Sentry. To use a [Model Context Protocol (MCP)](/agent-platform/capabilities/mcp/) server from the CLI, use the `--mcp` flag with `oz agent run` or `oz agent run-cloud`. -For a conceptual overview of MCP with cloud agents — including configuration schema, full agent config examples, and limitations — see [MCP Servers](/agent-platform/cloud-agents/mcp/) in the Cloud Agents docs. +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/). For a conceptual overview of MCP with cloud agents — including configuration schema, full agent config examples, and limitations — see [MCP Servers](/agent-platform/cloud-agents/mcp/) in the Cloud Agents docs. --- @@ -42,7 +42,7 @@ $ oz mcp list Alternatively, copy the UUID from Warp in **Settings** > **Agents** > **MCP servers**. -
+
![MCP servers page, showing a server with its UUID](../../../../assets/reference/mcp-server-id.png)
MCP servers page, showing a server with its UUID.
@@ -111,4 +111,5 @@ For cloud agent workflows, use [Oz-managed secrets](/agent-platform/cloud-agents * [MCP Servers (cloud agents)](/agent-platform/cloud-agents/mcp/) — configuration schema, full agent config file examples, and cloud agent limitations * [Model Context Protocol (MCP)](/agent-platform/capabilities/mcp/) — configuring MCP servers in Warp for local agents +* [Connect developer tools to agents with MCP workflows](/guides/external-tools/using-mcp-servers-with-warp/) — choose the setup path for local sessions, cloud runs, team sharing, and repeatable automation * [Secrets](/agent-platform/cloud-agents/secrets/) — store credentials in Warp so agents can access them at run time without exposing them in config files diff --git a/src/content/docs/terminal/more-features/full-screen-apps.mdx b/src/content/docs/terminal/more-features/full-screen-apps.mdx index 3f5acdd2..fbc2c7ee 100644 --- a/src/content/docs/terminal/more-features/full-screen-apps.mdx +++ b/src/content/docs/terminal/more-features/full-screen-apps.mdx @@ -49,7 +49,7 @@ Warp allows you to scale your terminal by fractions of a cell width | height. Wh Some full-screen applications don't behave well when resizing. If you are experiencing rendering issues with full screen apps, try turning this setting off. This will ensure that full-screen apps don't need to resize when starting up. ::: -
+
![alt-screen padding setting](../../../../assets/terminal/padding-settings.png)
The alt-screen padding setting in appearance preferences.
diff --git a/src/content/docs/terminal/windows/vertical-tabs.mdx b/src/content/docs/terminal/windows/vertical-tabs.mdx index e740e99a..6e29816c 100644 --- a/src/content/docs/terminal/windows/vertical-tabs.mdx +++ b/src/content/docs/terminal/windows/vertical-tabs.mdx @@ -45,7 +45,7 @@ To switch from horizontal tabs to the vertical tabs panel: The vertical tabs panel appears as a resizable sidebar on the left side of the window. The horizontal tab bar is hidden while vertical tabs are active. -
+
![A Warp window with the vertical tabs sidebar on the left listing a Claude Code tab and a codex tab alongside the main terminal pane](../../../../assets/terminal/multi-agents.png)
Vertical tab with agent details.
@@ -62,7 +62,7 @@ The vertical tabs panel supports two display densities that you can switch betwe Compact mode is the default. Each pane row displays an icon and title on one line, with an optional subtitle below it. The subtitle is configurable via the **Additional metadata** setting in the settings popup. -
+
![Vertical tabs sidebar in compact mode with each pane row showing an icon, title, and a short subtitle below](../../../../assets/terminal/vertical-tabs-condensed.png)
Vertical tabs in compact mode.
@@ -71,7 +71,7 @@ Compact mode is the default. Each pane row displays an icon and title on one lin Expanded mode shows each pane row with a title, description (such as the working directory or file path), and metadata (Git branch, diff stats badge, and PR badge when available). -
+
![Vertical tab rows in expanded mode showing titles, working directories, Git branches, diff stats, and agent status badges](../../../../assets/terminal/vertical-tabs-multi-agent.png)
Vertical tabs overview.
@@ -80,7 +80,7 @@ Expanded mode shows each pane row with a title, description (such as the working Click the settings icon (sliders) in the control bar at the top of the vertical tabs panel. In the popup, use the **Density** segmented control to switch between compact and expanded views. The change takes effect immediately. -
+
![The vertical tabs settings popup anchored to the sliders icon, showing View as, Density, Pane title as, Additional metadata, and Show details on hover options](../../../../assets/terminal/vertical-tab-settings.png)
Vertical tabs settings popup.
@@ -122,7 +122,7 @@ Agent pane icons display a small circular badge overlay in the bottom-right corn | **Cancelled** | Gray stop | The user cancelled the agent's last turn. | | **Blocked** | Yellow stop | The agent is waiting for user approval to proceed. | -
+
![Vertical tabs sidebar with four tab rows showing different agent status badges: a yellow blocked square, a magenta in-progress moon on the Claude Code brand icon, and green completion checks](../../../../assets/terminal/agent-status-badges.png)
Agent status badges on vertical tabs.
@@ -164,7 +164,7 @@ Renaming applies to tabs only. Individual panes can't be renamed at this time. Hover any pane row to open a floating detail card anchored to the right side of the panel. The sidecar shows full, un-clipped metadata (complete directory paths, full branch names, and the full conversation or command title) without changing which pane is focused. -
+
![The vertical tabs panel with a Claude Code tab hovered, showing a floating detail card with the agent's In progress status, working directory, and session title](../../../../assets/terminal/tab-hover-detail-card.png)
Hover detail card for a vertical tab.
diff --git a/src/sidebar.ts b/src/sidebar.ts index f873bdb6..661c2ed0 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -632,6 +632,8 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ label: 'Agent workflows', items: [ { slug: 'guides/agent-workflows/how-to-review-ai-generated-code', label: 'Review AI-Generated Code' }, + { slug: 'guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs', label: 'Attach Agent Context to PRs' }, + { slug: 'guides/agent-workflows/how-to-run-unattended-agents', label: 'Run Agents Unattended' }, { slug: 'guides/agent-workflows/how-to-run-multiple-ai-coding-agents', label: 'Run Multiple AI Coding Agents' }, { slug: 'guides/agent-workflows/how-to-use-voice-and-images-to-prompt-coding-agents', label: 'Use Voice and Images to Prompt Agents' }, { slug: 'guides/agent-workflows/how-to-explain-your-codebase-using-warp-rust-codebase', label: 'Explain Your Codebase with Agents' },