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

관련 논문

• ctx – 로컬 머신의 코딩 에이전트 히스토리를 검색하는 CLI 도구

  Claude Code, Cursor, Codex 등 코딩 에이전트가 이전 세션의 논의·결정·실패 시도를 잊지 않도록 SQLite로 인덱싱해 재사용할 수 있게 해주는 오픈소스 CLI 도구다.

• Micro-Agent: Model API 내부 협업으로 Frontier 모델을 이기는 방법 (vLLM Semantic Router)

  vLLM 팀이 단일 모델 API 호출 뒤에서 여러 모델이 협업하는 'Micro-Agent' 개념을 공개했습니다. 별도의 에이전트 코드 없이 라우터 레이어에서 모델 조합을 실행해 GPT-4급 결과를 더 저렴하게 낼 수 있다는 아이디어입니다.

• Ornith-1.0: 에이전틱 코딩을 위한 자기 개선형 오픈소스 모델

  Gemma 4와 Qwen 3.5를 기반으로 파인튜닝한 코딩 특화 오픈소스 모델로, RL(강화학습)을 통해 스캐폴드(에이전트 실행 구조)까지 함께 최적화하는 방식을 주장하지만, 커뮤니티에서는 벤치마크 과최적화에 불과하다는 의심을 받고 있다.

• Tool-Augmented Agent에서의 Entity Binding 실패 분석

  AI 에이전트가 올바른 도구를 선택해도 잘못된 대상에 실행하는 'Entity Binding 실패' 문제를 정의하고, 이를 막는 실행 정책을 평가한 논문.

• Herdr: 터미널에서 여러 AI Agent를 한 번에 관리하는 Agent Multiplexer

  여러 AI 코딩 에이전트(Claude, Codex 등)를 하나의 터미널에서 동시에 실행·관리할 수 있는 Rust 기반 오픈소스 툴로, tmux처럼 세션이 유지되고 SSH로 원격 접속도 가능해 멀티 에이전트 워크플로우를 크게 단순화해준다.

• Ornith-1.0: 스스로 Scaffold를 생성하는 Agentic Coding LLM

  모델이 문제 풀이 전략(scaffold)을 직접 생성하고 개선하는 자기강화 학습 프레임워크를 적용한 오픈소스 코딩 특화 LLM으로, 9B 소형 모델부터 397B 대형 모델까지 라인업을 갖추고 SWE-Bench 등 주요 벤치마크에서 Claude Opus 4.7을 능가하는 성능을 보여줬다.

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 에이전트