Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

feat: make local agent pairing easier to discover (#10946)

Shahmir Varqha3533899069c2
diff --git a/frontend/src/components/app-config/ai-config.tsx b/frontend/src/components/app-config/ai-config.tsx
index b4ef69285b..6130c9ec2b 100644
--- a/frontend/src/components/app-config/ai-config.tsx
+++ b/frontend/src/components/app-config/ai-config.tsx
@@ -59,6 +59,7 @@ import {
listModelsForAiSettings,
} from "../ai/ai-utils";
import { getTagColour } from "../ai/display-helpers";
+import { PairWithAgentBanner } from "../editor/actions/pair-with-agent";
import {
Accordion,
AccordionContent,
@@ -2005,6 +2006,7 @@ export const AiConfig: React.FC<AiConfigProps> = ({
{aiEnabled !== false && (
<>
<TabsContent value="ai-providers">
+ <PairWithAgentBanner className="mb-4" />
<AiProvidersConfig
form={form}
config={config}
diff --git a/frontend/src/components/chat/chat-panel.tsx b/frontend/src/components/chat/chat-panel.tsx
index f4e4fc18af..41c96b73d0 100644
--- a/frontend/src/components/chat/chat-panel.tsx
+++ b/frontend/src/components/chat/chat-panel.tsx
@@ -64,6 +64,10 @@ import { cn } from "@/utils/cn";
import { Logger } from "@/utils/Logger";
import { AIModelDropdown } from "../ai/ai-model-dropdown";
import { useOpenSettingsToTab } from "../app-config/state";
+import {
+ PairWithAgentBanner,
+ PairWithAgentButton,
+} from "../editor/actions/pair-with-agent";
import { PairWithAgentModal } from "../editor/actions/pair-with-agent-modal";
import { PromptInput } from "../editor/ai/add-cell-with-ai";
import {
@@ -163,6 +167,9 @@ const ChatHeader: React.FC<ChatHeaderProps> = ({
</Button>
</Tooltip>
<div className="flex items-center gap-2">
+ <Tooltip content="Connect your agent">
+ <PairWithAgentButton className="mr-1" label="Connect" />
+ </Tooltip>
<MCPStatusIndicator />
<Tooltip content="AI Settings">
<Button
@@ -493,7 +500,7 @@ const PairWithAgentCallout: React.FC<{
onClick={onPairWithAgent}
>
<SparklesIcon className="h-3.5 w-3.5 shrink-0" />
- <span>Work on this notebook with your own agent</span>
+ <span>Connect your own agent to this notebook</span>
<ArrowRightIcon className="h-3 w-3 shrink-0" />
</Button>
);
@@ -509,13 +516,17 @@ const ChatPanel = () => {
title="Chat with AI"
description="No AI provider configured or Chat model not selected"
action={
- <Button
- variant="outline"
- size="sm"
- onClick={() => handleClick("ai", "ai-providers")}
- >
- Edit AI settings
- </Button>
+ <div className="flex flex-col gap-3">
+ <Button
+ variant="outline"
+ size="sm"
+ className="self-start"
+ onClick={() => handleClick("ai", "ai-providers")}
+ >
+ Edit AI settings
+ </Button>
+ <PairWithAgentBanner />
+ </div>
}
icon={<BotMessageSquareIcon />}
/>
diff --git a/frontend/src/components/editor/actions/__tests__/pair-with-agent.test.tsx b/frontend/src/components/editor/actions/__tests__/pair-with-agent.test.tsx
new file mode 100644
index 0000000000..9e8aeb912a
--- /dev/null
+++ b/frontend/src/components/editor/actions/__tests__/pair-with-agent.test.tsx
@@ -0,0 +1,107 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { fireEvent, render, screen } from "@testing-library/react";
+import { Provider } from "jotai";
+import type React from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ModalProvider } from "@/components/modal/ImperativeModal";
+import { TooltipProvider } from "@/components/ui/tooltip";
+import { store } from "@/core/state/jotai";
+import { PairWithAgentBanner, PairWithAgentButton } from "../pair-with-agent";
+
+const mocks = vi.hoisted(() => ({
+ isWasm: vi.fn(() => false),
+}));
+
+vi.mock("@/core/wasm/utils", () => ({
+ isWasm: mocks.isWasm,
+}));
+
+function wrapper({ children }: { children: React.ReactNode }) {
+ return (
+ <Provider store={store}>
+ <TooltipProvider>
+ <ModalProvider>{children}</ModalProvider>
+ </TooltipProvider>
+ </Provider>
+ );
+}
+
+function stubTokenFetch() {
+ vi.stubGlobal(
+ "fetch",
+ vi.fn().mockResolvedValue(new Response(JSON.stringify({ token: null }))),
+ );
+}
+
+describe("PairWithAgent", () => {
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ mocks.isWasm.mockReset();
+ mocks.isWasm.mockReturnValue(false);
+ });
+
+ it("shows local agent options", () => {
+ render(<PairWithAgentBanner />, { wrapper });
+
+ expect(
+ screen.getByRole("group", { name: "Supported agents" }),
+ ).toBeVisible();
+ expect(screen.getByRole("figure", { name: "Claude Code" })).toBeVisible();
+ expect(screen.getByRole("figure", { name: "Codex" })).toBeVisible();
+ expect(screen.getByRole("figure", { name: "Cursor" })).toBeVisible();
+ expect(screen.getByRole("figure", { name: "Gemini CLI" })).toBeVisible();
+ expect(screen.getByRole("figure", { name: "OpenCode" })).toBeVisible();
+ expect(
+ screen.getByRole("figure", { name: "GitHub Copilot" }),
+ ).toBeVisible();
+ expect(
+ screen.getByRole("figure", { name: "Any local agent" }),
+ ).toBeVisible();
+ expect(
+ screen.getByRole("button", {
+ name: "Learn more.",
+ }),
+ ).toBeVisible();
+ });
+
+ it("opens the pairing dialog from the banner description", () => {
+ stubTokenFetch();
+ render(<PairWithAgentBanner />, { wrapper });
+
+ fireEvent.click(
+ screen.getByRole("button", {
+ name: "Learn more.",
+ }),
+ );
+
+ expect(
+ screen.getByRole("dialog", { name: "Pair with an agent" }),
+ ).toBeVisible();
+ });
+
+ it("opens the pairing dialog and preserves a passed click handler", () => {
+ const onClick = vi.fn();
+ stubTokenFetch();
+ render(<PairWithAgentButton onClick={onClick} />, { wrapper });
+
+ fireEvent.click(screen.getByRole("button", { name: "Connect your agent" }));
+
+ expect(onClick).toHaveBeenCalledOnce();
+ expect(
+ screen.getByRole("dialog", { name: "Pair with an agent" }),
+ ).toBeVisible();
+ });
+
+ it("hides pairing controls in WASM", () => {
+ mocks.isWasm.mockReturnValue(true);
+
+ const { container, rerender } = render(<PairWithAgentButton />, {
+ wrapper,
+ });
+ expect(container).toBeEmptyDOMElement();
+
+ rerender(<PairWithAgentBanner />);
+ expect(container).toBeEmptyDOMElement();
+ });
+});
diff --git a/frontend/src/components/editor/actions/pair-with-agent.tsx b/frontend/src/components/editor/actions/pair-with-agent.tsx
new file mode 100644
index 0000000000..d5be0a7d99
--- /dev/null
+++ b/frontend/src/components/editor/actions/pair-with-agent.tsx
@@ -0,0 +1,119 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { BotIcon } from "lucide-react";
+import React from "react";
+import { AiProviderIcon } from "@/components/ai/ai-provider-icon";
+import { useImperativeModal } from "@/components/modal/ImperativeModal";
+import { Button, type ButtonProps } from "@/components/ui/button";
+import { isWasm } from "@/core/wasm/utils";
+import { cn } from "@/utils/cn";
+import { PairWithAgentModal } from "./pair-with-agent-modal";
+
+const FEATURED_AGENTS = [
+ { id: "claude", label: "Claude Code" },
+ { id: "codex", label: "Codex" },
+ { id: "cursor", label: "Cursor" },
+ { id: "gemini", label: "Gemini CLI" },
+ { id: "opencode", label: "OpenCode" },
+ { id: "github", label: "GitHub Copilot" },
+ { id: "openai-compatible", label: "Any local agent" },
+] as const satisfies ReadonlyArray<{
+ id: React.ComponentProps<typeof AiProviderIcon>["provider"];
+ label: string;
+}>;
+
+export const usePairWithAgentModal = () => {
+ const { openModal, closeModal } = useImperativeModal();
+
+ return React.useCallback(
+ () => openModal(<PairWithAgentModal onClose={closeModal} />),
+ [openModal, closeModal],
+ );
+};
+
+export const PairWithAgentButton: React.FC<
+ ButtonProps & { label?: string }
+> = ({ className, label = "Connect your agent", onClick, ...props }) => {
+ const openPairWithAgentModal = usePairWithAgentModal();
+
+ if (isWasm()) {
+ return null;
+ }
+
+ return (
+ <Button
+ type="button"
+ variant="link"
+ size="xs"
+ className={cn("h-auto gap-1 px-0", className)}
+ onClick={(event) => {
+ onClick?.(event);
+ if (!event.defaultPrevented) {
+ openPairWithAgentModal();
+ }
+ }}
+ {...props}
+ >
+ {label}
+ </Button>
+ );
+};
+
+export const PairWithAgentBanner: React.FC<{
+ label?: string;
+ className?: string;
+}> = ({ label = "Connect your agent", className }) => {
+ const openPairWithAgentModal = usePairWithAgentModal();
+
+ if (isWasm()) {
+ return null;
+ }
+
+ return (
+ <div
+ className={cn(
+ "rounded-lg border border-(--blue-6) bg-(--blue-2)/50 p-3",
+ className,
+ )}
+ >
+ <div className="flex items-center gap-2 text-sm font-semibold">
+ {label}
+ <fieldset
+ className="m-0 flex min-w-0 -space-x-1.5 border-0 p-0 mb-0.5"
+ aria-label="Supported agents"
+ >
+ {FEATURED_AGENTS.map(({ id, label }) => (
+ <figure
+ key={id}
+ title={label}
+ aria-label={label}
+ className="flex size-6 items-center justify-center rounded-full border bg-background shadow-xs"
+ >
+ {id === "openai-compatible" ? (
+ <BotIcon className="size-3.5" aria-hidden={true} />
+ ) : (
+ <AiProviderIcon
+ provider={id}
+ className="size-3.5"
+ aria-hidden={true}
+ />
+ )}
+ </figure>
+ ))}
+ </fieldset>
+ </div>
+ <div className="mt-1 text-xs leading-relaxed">
+ <p className="inline">
+ Use your AI coding agent to pair-program on this notebook.
+ </p>
+ <button
+ type="button"
+ onClick={openPairWithAgentModal}
+ className="text-link hover:underline ml-1"
+ >
+ Learn more.
+ </button>
+ </div>
+ </div>
+ );
+};
diff --git a/frontend/src/components/editor/actions/useNotebookActions.tsx b/frontend/src/components/editor/actions/useNotebookActions.tsx
index 0ccca730c2..cfc4c29a44 100644
--- a/frontend/src/components/editor/actions/useNotebookActions.tsx
+++ b/frontend/src/components/editor/actions/useNotebookActions.tsx
@@ -297,11 +297,12 @@ export function useNotebookActions({
{
icon: <SparklesIcon size={14} strokeWidth={1.5} />,
- label: "Pair with an agent",
+ label: "Connect your agent",
hidden: isWasm(),
handle: async () => {
openModal(<PairWithAgentModal onClose={closeModal} />);
},
+ additionalKeywords: ["connect"],
},
{
diff --git a/frontend/src/components/editor/ai/add-cell-with-ai.tsx b/frontend/src/components/editor/ai/add-cell-with-ai.tsx
index acd1541e65..ecb7dde208 100644
--- a/frontend/src/components/editor/ai/add-cell-with-ai.tsx
+++ b/frontend/src/components/editor/ai/add-cell-with-ai.tsx
@@ -29,6 +29,7 @@ import useEvent from "react-use-event-hook";
import { DefaultChatTransport } from "ai";
import { z } from "zod";
import { AIModelDropdown } from "@/components/ai/ai-model-dropdown";
+import { PairWithAgentButton } from "@/components/editor/actions/pair-with-agent";
import {
AddContextButton,
AttachFileButton,
@@ -301,6 +302,7 @@ export const AddCellWithAI: React.FC<{
showAddCustomModelDocs={true}
/>
{languageDropdown}
+ <PairWithAgentButton />
</div>
<div className="flex flex-row items-center">
{files.length > 0 && (