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.

load marimo claude.md rules from source (with a fallback to docs.marimo.io) (#7279)

Myles Scolnickab55eaac7d90
diff --git a/.github/workflows/cla.yml b/.github/workflows/cla.yml
index 44b98ec46d..1d16f02198 100644
--- a/.github/workflows/cla.yml
+++ b/.github/workflows/cla.yml
@@ -29,7 +29,7 @@ jobs:
path-to-document: "https://marimo.io/cla" # e.g. a CLA or a DCO document
# branch should not be protected
branch: "main"
- allowlist: user1,bot*
+ allowlist: bot*,copilot
# the followings are the optional inputs - If the optional inputs are not given, then default values will be taken
remote-organization-name: marimo-team
diff --git a/marimo/_ai/_tools/tools/rules.py b/marimo/_ai/_tools/tools/rules.py
index cc7028734c..5a412637fb 100644
--- a/marimo/_ai/_tools/tools/rules.py
+++ b/marimo/_ai/_tools/tools/rules.py
@@ -8,12 +8,14 @@ import marimo._utils.requests as requests
from marimo import _loggers
from marimo._ai._tools.base import ToolBase
from marimo._ai._tools.types import EmptyArgs, SuccessResult, ToolGuidelines
+from marimo._utils.paths import marimo_package_path
LOGGER = _loggers.marimo_logger()
-# We load the rules remotely, so we can update these without requiring a new release.
-# If requested, we can bundle this into the library instead.
+# We ship the rules with the package in _static/CLAUDE.md
+# If the file doesn't exist (development or edge cases), we fallback to fetching from the URL
MARIMO_RULES_URL = "https://docs.marimo.io/CLAUDE.md"
+MARIMO_RULES_PATH = marimo_package_path() / "_static" / "CLAUDE.md"
@dataclass
@@ -41,6 +43,26 @@ class GetMarimoRules(ToolBase[EmptyArgs, GetMarimoRulesOutput]):
def handle(self, args: EmptyArgs) -> GetMarimoRulesOutput:
del args
+ # First, try to load from the bundled file
+ if MARIMO_RULES_PATH.exists():
+ try:
+ rules_content = MARIMO_RULES_PATH.read_text(encoding="utf-8")
+ return GetMarimoRulesOutput(
+ rules_content=rules_content,
+ source_url="bundled",
+ next_steps=[
+ "Follow the guidelines in the rules when working with marimo notebooks",
+ ],
+ )
+ except Exception as e:
+ LOGGER.warning(
+ "Failed to read bundled marimo rules from %s: %s",
+ MARIMO_RULES_PATH,
+ str(e),
+ )
+ # Fall through to fetch from URL
+
+ # Fallback: fetch from the URL
try:
response = requests.get(MARIMO_RULES_URL, timeout=10)
response.raise_for_status()
diff --git a/scripts/buildfrontend.sh b/scripts/buildfrontend.sh
index 75394f8a0f..6b6025822d 100755
--- a/scripts/buildfrontend.sh
+++ b/scripts/buildfrontend.sh
@@ -18,6 +18,8 @@ if $cmd; then
mkdir -p marimo/_static/
cp -R frontend/dist/* marimo/_static/
rm -rf marimo/_static/files/wasm-intro.py
+ echo "Copying CLAUDE.md documentation..."
+ cp docs/_static/CLAUDE.md marimo/_static/CLAUDE.md
echo "Compilation succeeded.\n"
else
echo "Frontend compilation failed.\n"
diff --git a/tests/_ai/tools/tools/test_rules.py b/tests/_ai/tools/tools/test_rules.py
index d966987b29..97aa16a05a 100644
--- a/tests/_ai/tools/tools/test_rules.py
+++ b/tests/_ai/tools/tools/test_rules.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+from pathlib import Path
from unittest.mock import Mock, patch
import pytest
@@ -17,13 +18,63 @@ def tool() -> GetMarimoRules:
return GetMarimoRules(ToolContext())
+def test_get_rules_from_bundled_file(tool: GetMarimoRules) -> None:
+ """Test successfully loading marimo rules from the bundled file."""
+ mock_path = Mock(spec=Path)
+ mock_path.exists.return_value = True
+ mock_path.read_text.return_value = "# Marimo Rules\n\nBundled content"
+
+ with patch("marimo._ai._tools.tools.rules.MARIMO_RULES_PATH", mock_path):
+ result = tool.handle(EmptyArgs())
+
+ assert result.status == "success"
+ assert result.rules_content == "# Marimo Rules\n\nBundled content"
+ assert result.source_url == "bundled"
+ assert len(result.next_steps) == 1
+ assert "Follow the guidelines" in result.next_steps[0]
+ mock_path.exists.assert_called_once()
+ mock_path.read_text.assert_called_once_with(encoding="utf-8")
+
+
+def test_get_rules_bundled_file_read_error_fallback_to_url(
+ tool: GetMarimoRules,
+) -> None:
+ """Test falling back to URL when bundled file exists but can't be read."""
+ mock_path = Mock(spec=Path)
+ mock_path.exists.return_value = True
+ mock_path.read_text.side_effect = OSError("Permission denied")
+
+ mock_response = Mock()
+ mock_response.text.return_value = "# Marimo Rules\n\nURL content"
+ mock_response.raise_for_status = Mock()
+
+ with (
+ patch("marimo._ai._tools.tools.rules.MARIMO_RULES_PATH", mock_path),
+ patch("marimo._utils.requests.get", return_value=mock_response),
+ ):
+ result = tool.handle(EmptyArgs())
+
+ assert result.status == "success"
+ assert result.rules_content == "# Marimo Rules\n\nURL content"
+ assert result.source_url == "https://docs.marimo.io/CLAUDE.md"
+ mock_path.exists.assert_called_once()
+ mock_path.read_text.assert_called_once_with(encoding="utf-8")
+ mock_response.raise_for_status.assert_called_once()
+
+
def test_get_rules_success(tool: GetMarimoRules) -> None:
- """Test successfully fetching marimo rules."""
+ """Test successfully fetching marimo rules from URL when bundled file doesn't exist."""
+ mock_path = Mock(spec=Path)
+ mock_path.exists.return_value = False
+
mock_response = Mock()
mock_response.text.return_value = "# Marimo Rules\n\nTest content"
mock_response.raise_for_status = Mock()
- with patch("marimo._utils.requests.get", return_value=mock_response):
+ with (
+ patch("marimo._ai._tools.tools.rules.MARIMO_RULES_PATH", mock_path),
+ patch("marimo._utils.requests.get", return_value=mock_response),
+ ):
result = tool.handle(EmptyArgs())
assert result.status == "success"
@@ -31,15 +82,22 @@ def test_get_rules_success(tool: GetMarimoRules) -> None:
assert result.source_url == "https://docs.marimo.io/CLAUDE.md"
assert len(result.next_steps) == 1
assert "Follow the guidelines" in result.next_steps[0]
+ mock_path.exists.assert_called_once()
mock_response.raise_for_status.assert_called_once()
def test_get_rules_http_error(tool: GetMarimoRules) -> None:
- """Test handling HTTP errors when fetching rules."""
+ """Test handling HTTP errors when fetching rules from URL."""
+ mock_path = Mock(spec=Path)
+ mock_path.exists.return_value = False
+
mock_response = Mock()
mock_response.raise_for_status.side_effect = Exception("404 Not Found")
- with patch("marimo._utils.requests.get", return_value=mock_response):
+ with (
+ patch("marimo._ai._tools.tools.rules.MARIMO_RULES_PATH", mock_path),
+ patch("marimo._utils.requests.get", return_value=mock_response),
+ ):
result = tool.handle(EmptyArgs())
assert result.status == "error"
@@ -52,10 +110,16 @@ def test_get_rules_http_error(tool: GetMarimoRules) -> None:
def test_get_rules_network_error(tool: GetMarimoRules) -> None:
- """Test handling network errors when fetching rules."""
- with patch(
- "marimo._utils.requests.get",
- side_effect=Exception("Connection refused"),
+ """Test handling network errors when fetching rules from URL."""
+ mock_path = Mock(spec=Path)
+ mock_path.exists.return_value = False
+
+ with (
+ patch("marimo._ai._tools.tools.rules.MARIMO_RULES_PATH", mock_path),
+ patch(
+ "marimo._utils.requests.get",
+ side_effect=Exception("Connection refused"),
+ ),
):
result = tool.handle(EmptyArgs())
@@ -67,10 +131,16 @@ def test_get_rules_network_error(tool: GetMarimoRules) -> None:
def test_get_rules_timeout(tool: GetMarimoRules) -> None:
- """Test handling timeout when fetching rules."""
- with patch(
- "marimo._utils.requests.get",
- side_effect=Exception("Request timeout"),
+ """Test handling timeout when fetching rules from URL."""
+ mock_path = Mock(spec=Path)
+ mock_path.exists.return_value = False
+
+ with (
+ patch("marimo._ai._tools.tools.rules.MARIMO_RULES_PATH", mock_path),
+ patch(
+ "marimo._utils.requests.get",
+ side_effect=Exception("Request timeout"),
+ ),
):
result = tool.handle(EmptyArgs())