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

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

# 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

Related Resources

• marimo-pair GitHub 저장소
• Jeremy Howard의 ipyai (AnswerDotAI)
• solve.it (Jeremy Howard)
• agentnb - iPython persistent kernel for agents
• mcp-repl (Posit Dev) - plain REPL 기반 MCP 도구
• cleon - Jupyter용 CLI 에이전트 하네스
• replsh - 로컬 Python 세션용 REPL 에이전트