Marimo Pair: 실행 중인 Reactive Python Notebook을 AI Agent 환경으로 활용하기

TL;DR Highlight

Marimo 노트북용 AI 에이전트 드롭인이 노트북의 반응형 실행 상태를 에이전트의 작업 메모리로 직접 활용하게 한다.

Who Should Read

데이터 사이언스나 ML 실험을 Marimo/Jupyter 노트북으로 하면서 Claude Code 같은 AI 에이전트를 인터랙티브하게 연동하고 싶은 파이썬 개발자. 특히 에이전트가 임시 스크립트를 던지는 방식이 아니라 '살아있는 세션' 안에서 협업하길 원하는 경우에 적합하다.

Core Mechanics

marimo-pair는 실행 중인 Marimo 노트북 세션에 에이전트를 직접 붙여주는 도구로, 에이전트가 노트북 셀을 읽고 실행하며 상태를 조작할 수 있게 해준다.
Marimo는 기존 Jupyter와 달리 반응형(reactive) 실행 모델을 쓰는 파이썬 노트북인데, 한 셀의 변수가 바뀌면 그에 의존하는 다른 셀이 자동으로 재실행된다. 이 구조 덕분에 노트북 런타임 자체가 에이전트의 영속적인 메모리 역할을 한다.
설치는 `npx skills add marimo-team/marimo-pair` 한 줄로 되고, Agent Skills 오픈 표준을 지원하는 어떤 에이전트 툴과도 연동된다. Claude Code용 플러그인도 별도로 제공한다.
에이전트가 실제로 쓰는 핵심 스크립트는 `discover-servers.sh`(실행 중인 Marimo 서버 탐지)와 `execute-code.sh`(코드 실행)로 단순하며, 노트북 접근에는 토큰 없이 자동 탐지(--no-token)하거나 `MARIMO_TOKEN` 환경변수로 인증할 수 있다.
에피머럴(ephemeral, 일회성) 스크립트를 던지는 기존 에이전트 방식과 달리, 에이전트가 노트북의 셀 구조와 현재 상태를 파악하면서 작업하기 때문에 인간과 모델이 같은 컨텍스트를 공유하며 협업하는 게 자연스럽다.
개발팀 저자에 따르면, 이 프로젝트는 '모델이 소비자인 API'를 만드는 색다른 엔지니어링 경험이었다고 한다. 버전 마이그레이션 없이 스킬 인터페이스를 여러 번 바꿨는데, 모델이 문서를 읽고 세션 안에서 스스로 새 기능을 발견하는 방식으로 작동하기 때문에 가능했다.
Marimo 노트북이 자신의 현재 상태와 구조를 잘 기술(describe)할 수 있다는 특성이, 에이전트에게 풍부한 컨텍스트를 제공하는 핵심 장점이다. 에이전트가 탐색과 실험을 하면서 동시에 재현 가능한 아티팩트(노트북)를 만들어가는 구조다.
현재 GitHub에 169 Star를 받았고(2025년 기준), v0.0.11까지 릴리즈된 초기 단계 프로젝트다. Apache-2.0 라이선스로 오픈소스다.

Evidence

실제 사용자가 Medicaid 데이터셋 데이터 사이언스 작업을 marimo-pair로 완료했다는 경험담을 공유했고, '버그 없이 바로 작동했다'고 평가했다.
Marimo의 반응형 모델에서 변수를 재할당할 수 없다는 제약이 에이전트(Claude)에게도 혼란을 준다는 사용자 지적이 있었다. '그래프 구조상 변수를 절대 재할당할 수 없다'는 점을 LLM이 자꾸 잊어버린다는 것인데, 이는 Marimo의 인터랙티비티를 위한 필수 제약이라는 점에서 트레이드오프다.
멀티에이전트 트레이딩 시스템을 만들 때 에이전트 상태 격리를 위해 BigQuery 같은 외부 영속 스토어를 썼다는 개발자가, '런타임 자체가 메모리가 되면 재현성을 공짜로 얻는다'는 marimo-pair 접근의 장점을 인정했다.
Posit의 개발자가 비슷한 방향으로 만든 단순 REPL 기반 MCP 도구(mcp-repl)를 소개하면서, 'REPL처럼 인터랙션 모델을 단순하게 유지하고 컨텍스트를 작게 가져가는 방식'과 'Marimo처럼 노트북 구조를 일찍 도입해서 모델이 탐색과 아티팩트 생성을 동시에 하게 하는 방식' 사이의 설계 트레이드오프에 대한 심도 있는 토론이 이어졌다.
Jeremy Howard(fast.ai/answer.ai)의 비슷한 프로젝트인 solveit과 ipyai, 그리고 독립 개발자들의 agentnb, cleon, replsh 등 유사한 방향의 여러 오픈소스 프로젝트들이 댓글에서 공유됐다. '노트북을 에이전트 실행 환경으로 쓴다'는 아이디어가 여러 팀에서 동시에 탐구되고 있다는 걸 보여준다.

How to Apply

Claude Code를 이미 쓰고 있고 Marimo 노트북에서 데이터 분석을 한다면, `/plugin marketplace add marimo-team/marimo-pair` → `/plugin install marimo-pair@marimo-team-marimo-pair` 두 명령으로 플러그인을 설치하면 Claude가 현재 열려있는 노트북 세션에 직접 접근해서 셀을 실행하고 결과를 확인할 수 있다.
반복적인 Bash 권한 승인 프롬프트가 귀찮다면, 설치된 스킬의 스크립트 절대경로를 `.claude/settings.json`의 `permissions.allow` 배열에 추가하면 자동으로 허용된다. 프로젝트별로 설정하려면 프로젝트 루트의 `.claude/settings.json`에, 전역 설정은 `~/.claude/settings.json`에 추가한다.
팀 단위로 데이터 분석 작업을 재현 가능하게 관리하고 싶다면, 에이전트가 노트북 안에서 작업한 내용이 셀 단위로 남기 때문에 노트북 자체가 실험 아티팩트이자 프롬프트 히스토리가 된다. 이 특성을 활용해서 에이전트 작업 결과를 노트북으로 버전 관리하면 재현성을 확보할 수 있다.
Claude Code가 아닌 다른 에이전트 툴을 쓴다면, Agent Skills 오픈 표준을 지원하는 도구에서 `npx skills add marimo-team/marimo-pair`로 설치 가능하다. npx가 없으면 uv가 설치돼 있을 때 `uvx deno -A npm:skills add marimo-team/marimo-pair`를 쓸 수 있다.

Code Example

snippet

# Claude Code 플러그인 설치
/plugin marketplace add marimo-team/marimo-pair
/plugin install marimo-pair@marimo-team-marimo-pair

# Agent Skills (npx) 설치
npx skills add marimo-team/marimo-pair

# uv 환경에서 설치 (npx 없을 때)
uvx deno -A npm:skills add marimo-team/marimo-pair

# Marimo 서버 실행 시 토큰 없이 자동 탐지 허용
marimo edit notebook.py --no-token

# 인증이 필요한 서버는 환경변수로
export MARIMO_TOKEN=your_token_here

# .claude/settings.json - Bash 권한 자동 허용 설정
{
  "permissions": {
    "allow": [
      "Bash(bash /path/to/skills/marimo-pair/scripts/discover-servers.sh *)",
      "Bash(bash /path/to/skills/marimo-pair/scripts/execute-code.sh *)"
    ]
  }
}

Terminology

reactive notebook셀 간 의존성을 자동으로 추적해서, 한 셀의 값이 바뀌면 그것에 의존하는 다른 셀이 자동으로 재실행되는 노트북. 스프레드시트처럼 연결된 계산 그래프라고 생각하면 된다.

Agent Skills에이전트 도구들이 서로 호환되도록 만든 오픈 표준. npm 패키지처럼 `npx skills add`로 설치해서 여러 에이전트 툴에 공통으로 쓸 수 있는 스킬을 배포/관리하는 방식이다.

ephemeral script에이전트가 실행하고 나면 결과만 돌려주고 사라지는 일회성 스크립트. 상태가 유지되지 않아서 이전 실행 컨텍스트를 이어받기 어렵다.

MCPModel Context Protocol의 약자로, AI 모델이 외부 도구나 데이터 소스에 표준화된 방식으로 접근할 수 있게 해주는 프로토콜. 에이전트가 노트북, DB, API 등 다양한 환경과 연동할 때 쓴다.

drop-in기존 시스템을 거의 수정하지 않고 그대로 끼워 넣을 수 있는 방식. 여기서는 이미 실행 중인 노트북 세션에 에이전트를 추가 설정 없이 붙일 수 있다는 뜻이다.

아티팩트(artifact)에이전트나 모델이 작업한 결과물로 남는 파일이나 구조물. marimo-pair 맥락에서는 에이전트가 작업한 내용이 노트북 셀로 남아 재현 가능한 문서가 되는 것을 의미한다.