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.

add `marimo pair prompt` CLI command and "Pair with an agent" modal (#9000)

Myles Scolnickd1755380ddbd
diff --git a/frontend/src/components/editor/actions/pair-with-agent-modal.tsx b/frontend/src/components/editor/actions/pair-with-agent-modal.tsx
new file mode 100644
index 0000000000..51cf4af6b9
--- /dev/null
+++ b/frontend/src/components/editor/actions/pair-with-agent-modal.tsx
@@ -0,0 +1,142 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { useAtomValue } from "jotai";
+import { CheckIcon, CopyIcon } from "lucide-react";
+import React, { useState } from "react";
+import { Button } from "@/components/ui/button";
+import {
+ DialogContent,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+} from "@/components/ui/dialog";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
+import { runtimeConfigAtom } from "@/core/runtime/config";
+import { copyToClipboard } from "@/utils/copy";
+import { Events } from "@/utils/events";
+import { Tooltip } from "@/components/ui/tooltip";
+import type { RuntimeConfig } from "@/core/runtime/types";
+
+type AgentTab = "claude" | "codex" | "opencode";
+
+function buildRemoteUrl(config: RuntimeConfig) {
+ const url = new URL(config.url);
+ if (config.authToken) {
+ url.searchParams.set("auth", config.authToken);
+ }
+ return url.toString();
+}
+
+function getPromptCommand(agent: AgentTab, remoteUrl: string): string {
+ const command = import.meta.env.DEV ? "uv run marimo" : "uvx marimo@latest";
+ const base = `${command} pair prompt --url '${remoteUrl}'`;
+ switch (agent) {
+ case "claude":
+ return `claude "$(${base} --claude)"`;
+ case "codex":
+ return `codex "$(${base} --codex)"`;
+ case "opencode":
+ return `opencode "$(${base} --opencode)"`;
+ }
+}
+
+const SKILL_INSTALL = "npx skills add marimo-team/marimo-pair";
+
+export const PairWithAgentModal: React.FC<{
+ onClose: () => void;
+}> = ({ onClose }) => {
+ const [activeTab, setActiveTab] = useState<AgentTab>("claude");
+ const runtimeConfig = useAtomValue(runtimeConfigAtom);
+ const remoteUrl = buildRemoteUrl(runtimeConfig);
+ const promptCommand = getPromptCommand(activeTab, remoteUrl);
+
+ return (
+ <DialogContent className="sm:max-w-lg">
+ <DialogHeader>
+ <DialogTitle>Pair with an agent</DialogTitle>
+ <DialogDescription>
+ Use an AI coding agent to pair-program on this notebook.{" "}
+ <a
+ href="https://links.marimo.app/marimo-pair"
+ target="_blank"
+ rel="noopener noreferrer"
+ className="underline"
+ >
+ Learn more
+ </a>
+ .
+ </DialogDescription>
+ </DialogHeader>
+
+ <div className="flex flex-col gap-4 py-2">
+ <div className="flex flex-col gap-2">
+ <span className="text-sm font-medium">1. Install the skill</span>
+ <CommandBlock command={SKILL_INSTALL} />
+ </div>
+
+ <div className="flex flex-col gap-2">
+ <span className="text-sm font-medium">2. Run in your terminal</span>
+ <Tabs
+ value={activeTab}
+ onValueChange={(v) => setActiveTab(v as AgentTab)}
+ >
+ <TabsList className="w-full">
+ <TabsTrigger value="claude" className="flex-1">
+ Claude
+ </TabsTrigger>
+ <TabsTrigger value="codex" className="flex-1">
+ Codex
+ </TabsTrigger>
+ <TabsTrigger value="opencode" className="flex-1">
+ OpenCode
+ </TabsTrigger>
+ </TabsList>
+
+ <TabsContent value="claude" className="mt-3">
+ <CommandBlock command={promptCommand} />
+ </TabsContent>
+ <TabsContent value="codex" className="mt-3">
+ <CommandBlock command={promptCommand} />
+ </TabsContent>
+ <TabsContent value="opencode" className="mt-3">
+ <CommandBlock command={promptCommand} />
+ </TabsContent>
+ </Tabs>
+ </div>
+ </div>
+
+ <DialogFooter>
+ <Button variant="secondary" onClick={onClose}>
+ Close
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ );
+};
+
+const CommandBlock: React.FC<{ command: string }> = ({ command }) => {
+ const [copied, setCopied] = useState(false);
+
+ const copy = Events.stopPropagation(async (e) => {
+ e.preventDefault();
+ await copyToClipboard(command);
+ setCopied(true);
+ setTimeout(() => setCopied(false), 2000);
+ });
+
+ return (
+ <div className="flex items-center gap-2 rounded-md bg-muted px-3 py-2 font-mono text-xs">
+ <code className="flex-1 select-all break-words">{command}</code>
+ <Tooltip content="Copied!" open={copied}>
+ <Button onClick={copy} size="xs" variant="ghost">
+ {copied ? (
+ <CheckIcon size={14} strokeWidth={1.5} />
+ ) : (
+ <CopyIcon size={14} strokeWidth={1.5} />
+ )}
+ </Button>
+ </Tooltip>
+ </div>
+ );
+};
diff --git a/frontend/src/components/editor/actions/useNotebookActions.tsx b/frontend/src/components/editor/actions/useNotebookActions.tsx
index 90304a1650..b68b89e914 100644
--- a/frontend/src/components/editor/actions/useNotebookActions.tsx
+++ b/frontend/src/components/editor/actions/useNotebookActions.tsx
@@ -36,6 +36,7 @@ import {
PresentationIcon,
SettingsIcon,
Share2Icon,
+ SparklesIcon,
Undo2Icon,
XCircleIcon,
YoutubeIcon,
@@ -45,6 +46,7 @@ import { settingDialogAtom } from "@/components/app-config/state";
import { MarkdownIcon } from "@/components/editor/cell/code/icons";
import { useImperativeModal } from "@/components/modal/ImperativeModal";
import { renderShortcut } from "@/components/shortcuts/renderShortcut";
+import { PairWithAgentModal } from "@/components/editor/actions/pair-with-agent-modal";
import { ShareStaticNotebookModal } from "@/components/static-html/share-modal";
import { toast } from "@/components/ui/use-toast";
import {
@@ -343,6 +345,14 @@ export function useNotebookActions() {
],
},
+ {
+ icon: <SparklesIcon size={14} strokeWidth={1.5} />,
+ label: "Pair with an agent",
+ handle: async () => {
+ openModal(<PairWithAgentModal onClose={closeModal} />);
+ },
+ },
+
{
icon: <Share2Icon size={14} strokeWidth={1.5} />,
label: "Share",
diff --git a/marimo/_cli/cli.py b/marimo/_cli/cli.py
index 7688c2205d..e637991c37 100644
--- a/marimo/_cli/cli.py
+++ b/marimo/_cli/cli.py
@@ -28,6 +28,7 @@ from marimo._cli.errors import (
from marimo._cli.export.commands import export
from marimo._cli.files.file_path import validate_name
from marimo._cli.help_formatter import ColoredGroup
+from marimo._cli.pair.commands import pair
from marimo._cli.parse_args import parse_args
from marimo._cli.parser_ux import show_compact_usage_error
from marimo._cli.print import bright_green, light_blue, red
@@ -1530,3 +1531,4 @@ main.command()(convert)
main.add_command(export)
main.add_command(config)
main.add_command(development)
+main.add_command(pair)
diff --git a/marimo/_cli/pair/__init__.py b/marimo/_cli/pair/__init__.py
new file mode 100644
index 0000000000..32e3c3b3b4
--- /dev/null
+++ b/marimo/_cli/pair/__init__.py
@@ -0,0 +1,2 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
diff --git a/marimo/_cli/pair/commands.py b/marimo/_cli/pair/commands.py
new file mode 100644
index 0000000000..8b26d6023b
--- /dev/null
+++ b/marimo/_cli/pair/commands.py
@@ -0,0 +1,129 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import click
+
+from marimo._cli.help_formatter import ColoredCommand, ColoredGroup
+
+SKILL_NAME = "marimo-pair"
+SKILL_FILE = "SKILL.md"
+
+
+@dataclass(frozen=True)
+class AgentConfig:
+ name: str
+ skill_dirs: list[Path] = field(default_factory=list)
+
+ def has_skill(self) -> bool:
+ return any(
+ (d / SKILL_NAME / SKILL_FILE).exists() for d in self.skill_dirs
+ )
+
+
+AGENTS: dict[str, AgentConfig] = {
+ "claude": AgentConfig(
+ name="Claude Code",
+ skill_dirs=[
+ Path.home() / ".claude" / "skills",
+ Path.cwd() / ".claude" / "skills",
+ ],
+ ),
+ "codex": AgentConfig(
+ name="Codex",
+ skill_dirs=[
+ Path.home() / ".codex" / "skills",
+ Path.cwd() / ".codex" / "skills",
+ ],
+ ),
+ "opencode": AgentConfig(
+ name="opencode",
+ skill_dirs=[
+ Path.home() / ".config" / "opencode" / "skills",
+ Path.cwd() / ".config" / "opencode" / "skills",
+ ],
+ ),
+}
+
+
+ cls=ColoredGroup,
+ help="""Commands for pair programming with AI.""",
+)
+def pair() -> None:
+ pass
+
+
+ cls=ColoredCommand,
+ help="""Generate a prompt for pair programming on a running marimo notebook.""",
+)
+ "--url",
+ required=True,
+ type=str,
+ help="URL of the running marimo kernel.",
+)
+ "--claude",
+ is_flag=True,
+ default=False,
+ help="Validate that the marimo-pair Claude Code skill is installed.",
+)
+ "--codex",
+ is_flag=True,
+ default=False,
+ help="Validate that the marimo-pair Codex skill is installed.",
+)
+ "--opencode",
+ is_flag=True,
+ default=False,
+ help="Validate that the marimo-pair opencode skill is installed.",
+)
+def prompt(url: str, claude: bool, codex: bool, opencode: bool) -> None:
+ """
+ Generate a prompt for pair programming.
+
+ Example usage:
+
+ claude $(marimo pair prompt --url 'https://localhost:8000?auth=...' --claude)
+ codex $(marimo pair prompt --url 'https://localhost:8000?auth=...' --codex)
+ opencode $(marimo pair prompt --url 'https://localhost:8000?auth=...' --opencode)
+ """
+ selected_agents = {
+ "claude": claude,
+ "codex": codex,
+ "opencode": opencode,
+ }
+ for key, agent in AGENTS.items():
+ if not selected_agents[key]:
+ continue
+ if not agent.has_skill():
+ click.echo(
+ f"The marimo-pair skill for {agent.name} is not installed.\n\n"
+ "Let the user know they need to install it with:\n\n"
+ " npx skills add marimo-team/marimo-pair\n\n"
+ "or\n\n"
+ " uvx deno -A npm:skills add marimo-team/marimo-pair\n\n"
+ "More instructions at "
+ "https://github.com/marimo-team/marimo-pair",
+ err=True,
+ )
+ sys.exit(1)
+
+ click.echo(
+ "Use the /marimo-pair skill to pair-program on a running "
+ "marimo notebook.\n\n"
+ f"Connect to the notebook at: {url}\n\n"
+ f"Use `execute-code.sh --url {url}` from the marimo-pair "
+ "skill to execute code in the notebook. \n\n"
+ "Once you are connected, send a fun toast to the user inside marimo letting them know you're ready to pair."
+ )
+
+
+pair.add_command(prompt)
diff --git a/tests/_cli/test_cli_pair.py b/tests/_cli/test_cli_pair.py
new file mode 100644
index 0000000000..1e55f796d8
--- /dev/null
+++ b/tests/_cli/test_cli_pair.py
@@ -0,0 +1,64 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+from unittest.mock import patch
+
+from click.testing import CliRunner
+
+from marimo._cli.cli import main as cli_main
+from marimo._cli.pair.commands import AgentConfig
+
+_runner = CliRunner()
+
+TEST_URL = "https://localhost:8000?auth=tok123"
+
+
+class TestPairGroup:
+ def test_pair_help(self) -> None:
+ result = _runner.invoke(cli_main, ["pair", "--help"])
+ assert result.exit_code == 0
+ assert "pair programming" in result.output.lower()
+ assert "prompt" in result.output
+
+ def test_prompt_help(self) -> None:
+ result = _runner.invoke(cli_main, ["pair", "prompt", "--help"])
+ assert result.exit_code == 0
+ assert "--url" in result.output
+ assert "--claude" in result.output
+ assert "--codex" in result.output
+ assert "--opencode" in result.output
+
+
+class TestPairPrompt:
+ def test_prompt_requires_url(self) -> None:
+ result = _runner.invoke(cli_main, ["pair", "prompt"])
+ assert result.exit_code != 0
+
+ def test_prompt_outputs_url(self) -> None:
+ result = _runner.invoke(
+ cli_main, ["pair", "prompt", "--url", TEST_URL]
+ )
+ assert result.exit_code == 0
+ assert TEST_URL in result.output
+ assert "execute-code.sh" in result.output
+ assert "marimo-pair" in result.output
+
+ def test_prompt_skill_missing(self) -> None:
+ with patch.object(AgentConfig, "has_skill", return_value=False):
+ for flag in ("--claude", "--codex", "--opencode"):
+ result = _runner.invoke(
+ cli_main,
+ ["pair", "prompt", "--url", TEST_URL, flag],
+ )
+ assert result.exit_code != 0, flag
+ assert "not installed" in result.output, flag
+
+ def test_prompt_skill_installed(self) -> None:
+ with patch.object(AgentConfig, "has_skill", return_value=True):
+ for flag in ("--claude", "--codex", "--opencode"):
+ result = _runner.invoke(
+ cli_main,
+ ["pair", "prompt", "--url", TEST_URL, flag],
+ )
+ assert result.exit_code == 0, flag
+ assert TEST_URL in result.output, flag