From e4d9e4412bb5fbbd811643990ae75888fc8ef42b Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Mon, 3 Aug 2026 09:25:53 +0000 Subject: [PATCH 1/3] docs: document OSC 8 hyperlinks, Codex Warp plugin, and context window breakdown Fills three GA feature gaps surfaced by a missing-docs audit against warp-internal: - Files, links, & scripts: OSC 8 hyperlink support (Cmd/Ctrl+click, copy behavior, any URL scheme), which was undocumented. - Codex: replace the stale `notification_condition = "always"` setup with the Warp plugin flow (install/update chip, `codex plugin marketplace add warpdotdev/codex-warp`, `codex plugin add warp@codex-warp`), which is how notifications work now. - Interacting with agents: the per-segment context window usage breakdown in the conversation usage card, including what each segment means and how to use it to decide what to trim. Co-Authored-By: Oz --- .../docs/agent-platform/cli-agents/codex.mdx | 25 +++++++++++++------ .../interacting-with-agents/index.mdx | 13 ++++++++++ .../more-features/files-and-links.mdx | 15 +++++++++++ 3 files changed, 45 insertions(+), 8 deletions(-) diff --git a/src/content/docs/agent-platform/cli-agents/codex.mdx b/src/content/docs/agent-platform/cli-agents/codex.mdx index 401fdc42a..618c8ed52 100644 --- a/src/content/docs/agent-platform/cli-agents/codex.mdx +++ b/src/content/docs/agent-platform/cli-agents/codex.mdx @@ -19,24 +19,33 @@ Codex is also available as a harness in Oz for cloud orchestration. See [Codex w ## Setting up notifications -Codex supports native notifications that Warp surfaces as in-app and desktop alerts — such as when Codex completes a task, encounters an error, or needs your input. +Warp surfaces Codex activity as in-app and desktop alerts — such as when Codex completes a task, encounters an error, or needs your input. This is powered by the Warp plugin for Codex, published from the [warpdotdev/codex-warp](https://github.com/warpdotdev/codex-warp) plugin marketplace. -First, update Codex to the latest version — support for this setting was recently added. See the [Codex upgrade instructions](https://developers.openai.com/codex/cli#upgrade). +When Warp detects a Codex session without the plugin, it shows an install chip in the terminal. Click the chip to install the plugin, then restart Codex. Warp shows an update chip the same way when a newer plugin version is required. -Then add the following to `~/.codex/config.toml`: +To install the plugin yourself, add the marketplace and the plugin: -```toml -[tui] -notification_condition = "always" +```bash +codex plugin marketplace add warpdotdev/codex-warp +codex plugin add warp@codex-warp ``` -Then restart Codex. If this config isn't set, Warp displays a setup chip in the terminal with instructions you can follow directly. +Restart Codex to activate the plugin. To update it later, upgrade the marketplace and reinstall the plugin: + +```bash +codex plugin marketplace upgrade codex-warp +codex plugin add warp@codex-warp +``` + +:::note +If you point `codex-warp` at a local (non-Git) marketplace source, Warp leaves that override alone and doesn't offer plugin updates for it. +::: ## Supported Warp features Codex supports the full set of Warp's agent integration features: -* **Agent notifications** - Receive in-app and desktop alerts when Codex needs your attention. Requires a one-time config change (see [Setting up notifications](#setting-up-notifications)). +* **Agent notifications** - Receive in-app and desktop alerts when Codex needs your attention. Requires the Warp plugin for Codex (see [Setting up notifications](#setting-up-notifications)). * **Rich input editor** - Press `Ctrl-G` to open an expanded input editor for composing longer prompts. * **Code review** - Send inline review comments directly to the agent from Warp's code review panel. * **Attach code as context** - Select code and send it to the agent as context. diff --git a/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx b/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx index 5a737ff55..2e8bc1313 100644 --- a/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx +++ b/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx @@ -140,6 +140,19 @@ The context window usage indicator is available in agent conversation views. If you switch models during a conversation, the context usage indicator updates only after you send your next message. ::: +### Context window usage breakdown + +To see what is filling the context window, open the conversation usage card and click the **Context window used** row. The row expands into a per-segment breakdown, with each segment's share of the window shown as a percentage: + +* **System Prompt** - Warp's instructions to the model, including your [rules](/agent-platform/capabilities/rules/). +* **Tool Definitions** - Descriptions of the tools available to the agent, including any [MCP servers](/agent-platform/capabilities/mcp/). +* **Conversation History** - Previous queries, responses, and tool results in the conversation. +* **Latest Input** - Your most recent query and the context attached to it. +* **Images** - Any [images](/agent-platform/local-agents/agent-context/images-as-context/) attached to the conversation. +* **Other** - Everything not covered by the segments above. + +Use the breakdown to decide what to trim: a large **Conversation History** segment is a good signal to start a new conversation or summarize, while a large **Tool Definitions** segment suggests turning off MCP servers you aren't using. + ## Conversation segmentation Warp automatically detects when your query has shifted to a new topic. When this happens, it suggests starting a new conversation instead of continuing in the same context. diff --git a/src/content/docs/terminal/more-features/files-and-links.mdx b/src/content/docs/terminal/more-features/files-and-links.mdx index 793f24bde..b00713345 100644 --- a/src/content/docs/terminal/more-features/files-and-links.mdx +++ b/src/content/docs/terminal/more-features/files-and-links.mdx @@ -71,6 +71,21 @@ Non-exhaustive list of editors, please submit new ones on our GitHub, see [Sendi +### OSC 8 hyperlinks + +Warp recognizes the OSC 8 escape sequence, so command-line tools can print a short label that links to a longer URL instead of printing the raw URL. When a program emits an OSC 8 hyperlink, Warp renders only the visible text and makes it clickable, the same way it treats auto-detected URLs: + +* Hold `⌘` (macOS) or `Ctrl` (Windows/Linux) and click the linked text to open it. +* Copying the block copies the visible text, not the escape sequence or the underlying URL. + +Any URL scheme works, including `file://` URLs without a hostname. To try it, print a hyperlink from your shell: + +```bash +printf '\033]8;;https://docs.warp.dev\033\\Warp docs\033]8;;\033\\\n' +``` + +The output shows `Warp docs` as a clickable link. Plain-text URL detection still works, so tools that print full URLs behave as before. + ## Scripts Warp can open `.command` and Unix Executable files from Finder directly. From 7c31ff0035b1c4235a60b2a7d875adf85618a679 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Mon, 3 Aug 2026 16:25:13 -0700 Subject: [PATCH 2/3] Apply suggestion from @oz-for-oss[bot] Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com> --- .../local-agents/interacting-with-agents/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx b/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx index 2e8bc1313..e6603664c 100644 --- a/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx +++ b/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx @@ -142,7 +142,7 @@ If you switch models during a conversation, the context usage indicator updates ### Context window usage breakdown -To see what is filling the context window, open the conversation usage card and click the **Context window used** row. The row expands into a per-segment breakdown, with each segment's share of the window shown as a percentage: +To see what is filling the context window, open the conversation usage card and click **View breakdown** in the **Context window used** row. The row expands into a per-segment breakdown, with each segment's share of the window shown as a percentage: * **System Prompt** - Warp's instructions to the model, including your [rules](/agent-platform/capabilities/rules/). * **Tool Definitions** - Descriptions of the tools available to the agent, including any [MCP servers](/agent-platform/capabilities/mcp/). From 0c828e023b2f4b4373bb5f0fd3b1cdb2fc3520d1 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Mon, 3 Aug 2026 23:30:21 +0000 Subject: [PATCH 3/3] Update context breakdown links to renamed /agents/ paths Co-Authored-By: Warp Agent --- .../agents/local-agents/interacting-with-agents/index.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/agents/local-agents/interacting-with-agents/index.mdx b/src/content/docs/agents/local-agents/interacting-with-agents/index.mdx index cc7db2e4b..9a94bc90b 100644 --- a/src/content/docs/agents/local-agents/interacting-with-agents/index.mdx +++ b/src/content/docs/agents/local-agents/interacting-with-agents/index.mdx @@ -144,11 +144,11 @@ If you switch models during a conversation, the context usage indicator updates To see what is filling the context window, open the conversation usage card and click **View breakdown** in the **Context window used** row. The row expands into a per-segment breakdown, with each segment's share of the window shown as a percentage: -* **System Prompt** - Warp's instructions to the model, including your [rules](/agent-platform/capabilities/rules/). -* **Tool Definitions** - Descriptions of the tools available to the agent, including any [MCP servers](/agent-platform/capabilities/mcp/). +* **System Prompt** - Warp's instructions to the model, including your [rules](/agents/capabilities/rules/). +* **Tool Definitions** - Descriptions of the tools available to the agent, including any [MCP servers](/agents/capabilities/mcp/). * **Conversation History** - Previous queries, responses, and tool results in the conversation. * **Latest Input** - Your most recent query and the context attached to it. -* **Images** - Any [images](/agent-platform/local-agents/agent-context/images-as-context/) attached to the conversation. +* **Images** - Any [images](/agents/local-agents/agent-context/images-as-context/) attached to the conversation. * **Other** - Everything not covered by the segments above. Use the breakdown to decide what to trim: a large **Conversation History** segment is a good signal to start a new conversation or summarize, while a large **Tool Definitions** segment suggests turning off MCP servers you aren't using.