notebook-intelligence/notebook-intelligence

Notebook Intelligence (NBI)는 JupyterLab을 위한 AI 코딩 어시스턴트(AI coding assistant)이자 확장 가능한 AI 프레임워크(extensible AI framework)입니다. NBI는 채팅(chat), 인라인 편집(inline edit), 자동 완성(auto-complete), 그리고 노트북을 구동할 수 있는 에이전트(agent) 기능을 추가합니다. 이는 GitHub Copilot, OpenAI 호환 또는 LiteLLM 호환 엔드포인트(endpoint), 로컬 Ollama 모델, 또는 Anthropic의 Claude Code CLI를 기반으로 작동합니다.

NBI는 무료이며 오픈 소스(open-source)입니다. 원하는 무료 또는 유료 LLM 제공업체 — GitHub Copilot, 모든 OpenAI 또는 LiteLLM 호환 엔드포인트, Ollama (로컬), 또는 Anthropic Claude (Claude Code CLI를 통해) — 에 연결하여 사용할 수 있습니다. 해당되는 경우, 제공업체 이용 요금은 제공업체에 직접 지불됩니다.

• 요구 사항 (Requirements)

• 빠른 시작 (Quick start)

• 개념 (Concepts)

• 주요 기능 (Feature highlights)

• 설정 (Configuration)

• 내장 도구 (Built-in tools)

• 모델 컨텍스트 프로토콜 (Model Context Protocol (MCP)) 지원

• 규칙 세트 (Rulesets)

• Claude 기술 (Claude Skills)

• Claude MCP 서버 (Claude MCP Servers)

• Claude 플러그인 (Claude Plugins)

• 채팅 피드백 (Chat feedback)

• 문서 (Documentation)

• 추가 읽기 (Further reading)

• 로드맵 (Roadmap)

• 라이선스 (License)

• Python 3.10+

• JupyterLab 4.x

• Node.js — Claude 모드 (Claude Code CLI) 및 npx를 통해 실행되는 MCP 서버의 경우에만 필요합니다.

• NBI가 시스템 Python과 충돌하지 않도록 새로운 가상 환경(virtualenv) 또는 conda 환경을 사용하는 것을 권장합니다.

pip install notebook-intelligence
jupyter lab # JupyterLab이 이미 실행 중이라면 재시작하세요

재시작 후:

• 왼쪽 사이드바에서 NBI 아이콘을 클릭하여 채팅 패널을 엽니다.
• NBI 설정(채팅 패널의 기어 아이콘, 또는 Settings → Notebook Intelligence Settings)을 엽니다.
• 제공업체에 로그인합니다 — GitHub Copilot의 경우 Sign in을 클릭하고, OpenAI 또는 LiteLLM 호환 엔드포인트의 경우 API 키를 붙여넣으며, Ollama의 경우 로컬 데몬(daemon)을 지정합니다. Claude를 사용하려면 Claude 모드를 활성화하세요(아래 참조).
• 채팅 패널에 메시지를 입력하고 Enter를 누릅니다.

패널이 비어 있거나 로그인이 작동하지 않는 경우, 문제 해결(Troubleshooting) 섹션을 참조하세요.

이 문서 전반에서 참조될 짧은 용어 사전입니다.

LLM Provider (LLM 제공자)— 모델을 실행하는 서비스입니다. NBI는 GitHub Copilot, OpenAI 호환(OpenAI-compatible), LiteLLM 호환(LiteLLM-compatible), 그리고 Ollama의 네 가지 제공자 어댑터(provider adapters)를 제공합니다. Anthropic Claude는 Claude 모드를 통해 사용할 수 있으며, 최상위 제공자(top-level provider)로 제공되지는 않습니다.

Chat Participant (채팅 참여자)— 채팅 패널 내에서 @mention이 가능한 페르소나입니다 (@workspace, @mcp 등). 참여자는 요청을 특정 도구 인터페이스(tool surface)로 라우팅합니다.

Default mode vs Claude mode (기본 모드 대 Claude 모드)— Default (기본) 모드는 채팅, 인라인 채팅(inline chat), 자동 완성(auto-complete)에 설정된 LLM 제공자를 사용합니다. *Claude mode (Claude 모드)*는 채팅 패널에 Claude Code CLI를 사용하며(이를 통해 도구, 기술(skills), MCP 서버 및 사용자 정의 명령을 가져옴), 인라인 채팅과 자동 완성에는 Anthropic API를 통해 Claude 모델을 사용합니다. 이 모드를 사용하려면 PATH에 Claude Code CLI가 설정되어 있어야 합니다.

Claude Code vs the Anthropic API (Claude Code 대 Anthropic API)— Anthropic API (api.anthropic.com)는 Claude 모드에서 인라인 채팅과 자동 완성을 위해 NBI가 직접 호출하는 HTTPS 엔드포인트입니다. Claude Code는 Anthropic의 로컬 CLI 에이전트로, NBI가 채팅 패널을 위해 셸 명령(shell out)으로 호출하며, 이는 Anthropic과 직접 통신합니다.

MCP— Model Context Protocol (모델 컨텍스트 프로토콜). LLM이 외부 도구(파일 읽기, API 호출, 스크립트 실행)를 호출할 수 있는 방법입니다.

Ruleset (규칙 세트)— 컨벤션(conventions), 코딩 표준 또는 도메인 규칙을 강제하기 위해 시스템 프롬프트(system prompt)에 주입되는 ~/.jupyter/nbi/rules/ 내의 마크다운(markdown) 파일들입니다.

Skill (기술): SKILL.md와 보조 파일들을 포함하고 있는 ~/.claude/skills/ (또는 <project>/.claude/skills/) 하위의 디렉토리입니다. Claude는 이를 워크스페이스에 범위가 지정된 호출 가능한 플러그인(callable plugin)처럼 호출할 수 있습니다.

Claude plugin (Claude 플러그인): claude plugin install을 위해 패키징된 단위로, 마켓플레이스(marketplace, 일반적으로 플러그인 매니페스트를 게시하는 GitHub 리포지토리)를 통해 배포됩니다. NBI 자체의 labextension과는 구별되며, 플러그인은 Claude Code 세션 내에서 실행됩니다.

NBI는 Claude Code 통합을 위한 전용 모드를 제공합니다. **Claude 모드 (Claude mode)**에서 NBI는 채팅 패널을 위해 Claude Code CLI를 사용하며, 인라인 채팅 (inline chat) 및 자동 완성 (auto-complete) 제안을 위해 Claude 모델 (Anthropic API를 통해)을 사용합니다. 이를 통해 Claude Code의 도구 (tools), 기술 (skills), MCP 서버, 그리고 커스텀 명령 (custom commands)을 JupyterLab으로 가져옵니다.

NBI 설정 (Settings) 대화 상자(채팅 패널의 톱니바퀴 아이콘 또는 Settings → Notebook Intelligence Settings)를 통해 구성하십시오. Enable Claude mode를 활성화한 후 다음을 설정할 수 있습니다:

Chat model (채팅 모델)— 채팅 패널 및 인라인 채팅에 사용되는 Claude 모델.
Auto-complete model (자동 완성 모델)— 자동 완성 제안에 사용되는 Claude 모델.
Chat Agent setting sources (채팅 에이전트 설정 소스)— Claude Code의 설정을 반영하여 사용자 (user), 프로젝트 (project), 또는 둘 다를 선택합니다.
Chat Agent tools (채팅 에이전트 도구)— 활성화할 도구 세트입니다. Claude Code tools는 항상 켜져 있습니다. Jupyter UI tools는 NBI 자체 도구입니다 (노트북 작성, 셀 실행 등).
API key (API 키) 및 Base URL (기본 URL)— Anthropic 또는 자체 호스팅된 엔드포인트(endpoint)를 지정합니다.

Claude Code CLI가 PATH에 있으면 NBI가 이를 자동으로 실행합니다. 위치를 재정의하려면 JupyterLab을 시작하기 전에 NBI_CLAUDE_CLI_PATH 환경 변수를 설정하십시오.

Claude 모드가 켜져 있으면 채팅 사이드바의 톱니바퀴 옆에 기록 (history) 아이콘이 표시됩니다. 이를 클릭하면 현재 작업 디렉토리(current working directory)에 기록된 Claude Code 세션 목록이 나타납니다 (이는 Claude Code CLI가 ~/.claude/projects/ 아래에 저장하는 것과 동일한 트랜스크립트(transcripts)입니다). 세션을 선택하면 resume을 통해 다시 연결되므로, 다음에 보내는 메시지는 이전의 모든 문맥(context)을 포함하여 해당 트랜스크립트를 이어갑니다.

Claude CLI가 PATH에 있으면, JupyterLab 런처(새 탭과 함께 열리는 패널)에 표준 커널 런처와 함께 Claude Code 타일이 표시됩니다. 이를 클릭하면 세션 선택기(session picker)가 열립니다. 과거 트랜스크립트를 검색하여 새 터미널에서 세션을 재개하거나, 파일 브라우저의 활성 하위 디렉토리에서 새 세션을 시작할 수 있습니다. 세션 ID는 선택기에서 복사하여 claude --resume <id> 명령에 붙여넣을 수 있습니다.

다음 CLI 중 하나라도 PATH에 있으면

, 런처는 각 CLI에 대한 타일을 추가합니다. 타일을 클릭하면 파일 브라우저의 현재 디렉토리에서 터미널이 열리며 해당 CLI가 실행됩니다:

opencode (NBI_OPENCODE_CLI_PATH로 경로 재정의 가능)

Pi (NBI_PI_CLI_PATH로 경로 재정의 가능)

GitHub Copilot CLI (NBI_GITHUB_COPILOT_CLI_PATH로 경로 재정의 가능)

OpenAI Codex (NBI_CODEX_CLI_PATH로 경로 재정의 가능)

CLI를 사용할 수 있거나 사용할 수 없게 됨에 따라 타일은 스스로 추가되거나 제거됩니다. 타일 사용에는 Claude 모드가 필요하지 않습니다.

에이전트 (Agent) 모드에서는 내장된 AI 에이전트가 사용자를 대신하여 대화형으로 노트북을 생성, 편집 및 실행합니다. 에이전트는 셀의 문제를 감지하고 이를 수정할 수 있습니다.

셀 툴바의 반짝임 아이콘을 사용하거나 키보드 단축키를 사용하여 인라인 채팅 팝오버 (inline chat popover)를 표시할 수 있습니다.

Ctrl+G / Cmd+G를 누르면 팝오버가 열립니다. Ctrl+Enter / Cmd+Enter를 누르면 제안을 수락합니다. Esc를 누르면 닫힙니다. 수락 단축키는 팝오버가 열려 있는 동안에만 JupyterLab의 기본 셀 실행 (run cell) 바인딩을 재정의합니다. 팝오버 외부에서는 Ctrl+Enter / Cmd+Enter가 여전히 활성 셀을 실행합니다.

타이핑하는 동안 자동 완성 (Auto-complete) 제안이 표시됩니다. Tab을 누르면 수락됩니다. NBI는 코드 셀과 Python 파일 에디터에서 자동 완성을 제공합니다.

채팅 프롬프트와 함께 이미지를 붙여넣거나 첨부할 수 있습니다. 활성 모델이 비전 (vision) 기능을 지원하는 경우 이미지는 모델의 입력값으로 전달됩니다.

셀 출력물을 우클릭하거나(또는 툴바를 위해 호버하면) 이를 컨텍스트 (context)로서 채팅으로 바로 보낼 수 있습니다:

셀 오류 설명 (Explain cell errors)— 오류가 발생한 셀에

/ NBI_OUTPUT_FOLLOWUP_POLICY

/ NBI_OUTPUT_TOOLBAR_POLICY

.

활성화된 노트북은 툴바(toolbar)에 반짝이는 아이콘(sparkle icon)을 표시합니다. 이 아이콘을 클릭하면 팝오버(popover)가 열리며, 생성 요청(generation request)의 범위를 해당 특정 노트북으로 제한합니다. 이는 채팅 사이드바가 컨텍스트 (context)를 점유하는 것을 원치 않는 멀티 노트북 세션에서 유용합니다.

채팅 패널의 톱니바퀴 아이콘, /settings 채팅 명령어, 또는 JupyterLab 커맨드 팔레트(command palette)를 통해 NBI 설정 (NBI Settings)에서 프로바이더 (provider), 모델 (model), API 키 (API key)를 구성할 수 있습니다. 배경 지식은 프로바이더 블로그 포스트를 참조하세요.

NBI는 설정을 ~/.jupyter/nbi/config.json에 저장합니다. 또한 <env-prefix>/share/jupyter/nbi/config.json에 있는 환경 전체 기본 설정 (environment-wide base configuration)도 지원합니다. 조직은 해당 위치에 기본 설정을 배포할 수 있으며, 사용자 변경 사항은 그 위에 오버라이드 (overrides)로 저장됩니다.

이 설정 파일들은 프로바이더 (provider), 모델 (model), 그리고 MCP 설정을 저장합니다. 커스텀 LLM 프로바이더를 위한 API 키 또한 여기에 평문 (plaintext)으로 저장됩니다 — ~/.jupyter/nbi/config.json을 절대 git에 커밋하거나, 공유하거나, 사용자 간에 동기화하지 마세요. 키가 유출되면 즉시 프로바이더에서 키를 교체(rotate)하십시오.

config.json을 수동으로 편집하면 적용을 위해 JupyterLab을 재시작해야 합니다. 설정(Settings) 대화 상자를 통한 편집은 실시간으로 반영됩니다.

대부분의 설정 패널 토글 (toggles)은 조직 관리자(org administrators)에 의해 잠길 수 있습니다. 두 가지 형태가 있습니다:

**불리언 정책 (Boolean policies)**은 *_POLICY 접미사를 사용하며 세 가지 값을 허용합니다: user-choice (기본값 — 사용자가 자유롭게 토글), force-on (활성화로 고정), force-off (비활성화로 고정). 강제 설정 시, 패널 컨트롤은 "관리자에 의해 잠겼습니다 (Locked by your administrator)"라는 툴팁과 함께 비활성화되며, 클라이언트 측의 모든 쓰기 작업은 무시됩니다.

환경 변수 (Env var)	다음 항목에 대한 설정 패널 제어 잠금
NBI_EXPLAIN_ERROR_POLICY	"Explain cell errors (셀 오류 설명)"
NBI_OUTPUT_FOLLOWUP_POLICY	"Ask about cell outputs (셀 출력에 대해 질문하기)"
NBI_OUTPUT_TOOLBAR_POLICY	"Show output toolbar (출력 도구 모음 표시)"
NBI_CLAUDE_MODE_POLICY	"Enable Claude mode (Claude 모드 활성화)"
NBI_CLAUDE_CONTINUE_CONVERSATION_POLICY	"Remember conversation history (대화 기록 기억)"
NBI_CLAUDE_CODE_TOOLS_POLICY	"Claude Code tools (Claude Code 도구)"
NBI_CLAUDE_JUPYTER_UI_TOOLS_POLICY	"Jupyter UI tools (Jupyter UI 도구)"
NBI_CLAUDE_SETTING_SOURCE_USER_POLICY	설정 소스: 사용자 (Setting source: User)
NBI_CLAUDE_SETTING_SOURCE_PROJECT_POLICY	설정 소스: 프로젝트 (Setting source: Project)
NBI_STORE_GITHUB_ACCESS_TOKEN_POLICY	"Remember my GitHub Copilot access token (내 GitHub Copilot 액세스 토큰 기억)"
NBI_SKILLS_MANAGEMENT_POLICY	Skills 탭 (강제 비활성화(force-off) 시 탭이 숨겨지고 API에 403 오류를 반환하며, 관리되는 기술(managed-skills) 조정기(reconciler)도 비활성화됩니다)
NBI_CLAUDE_MCP_MANAGEMENT_POLICY	Claude 모드 MCP Servers 탭 (강제 비활성화 시 탭이 숨겨지고 /claude-mcp/*에 403 오류를 반환하며, 비-Claude MCP Servers 탭과는 독립적입니다)
NBI_CLAUDE_PLUGINS_MANAGEMENT_POLICY	Claude 모드 Plugins 탭 (강제 비활성화 시 탭이 숨겨지고 /plugins/*에 403 오류를 반환합니다)
NBI_TERMINAL_DRAG_DROP_POLICY	터미널 드래그 앤 드롭 파일 첨부 기능

처음 세 가지 항목은 NotebookIntelligence 상의 일치하는 트레이틀릿 (traitlets) (explain_error_policy, output_followup_policy, output_toolbar_policy)도 가지고 있습니다. 필요한 경우 동일한 형태로 나머지를 추가하십시오:

c.NotebookIntelligence.claude_mode_policy = "force-on"
c.NotebookIntelligence.claude_jupyter_ui_tools_policy = "force-off"

사용자별 기본 설정(셀 출력 기능의 경우 기본적으로 활성화됨)은 config.json 내에 enable_explain_error, enable_output_followup, enable_output_toolbar로 저장됩니다.

리스트 형태의 차단 목록 (List-shaped denylists) (LLM 제공업체, 내장 도구, 코딩 에이전트 런처 타일)은 *_POLICY 환경 변수 대신 트레이틀릿 (traitlets)을 사용합니다. disabled_providers, disabled_tools, disabled_coding_agent_launchers 설정 방법은 docs/admin-guide.md를 참조하십시오.

비불리언 (non-boolean) 설정에 대한 값 존재 잠금 (Value-presence locks): 환경 변수 (env var)를 비어 있지 않은 값으로 설정하면 해당 제어 항목이 그 값으로 고정(pin)되며 비활성화됩니다. 비어 있거나 설정되지 않은 경우 = 사용자 선택 사항입니다.

환경 변수 (Env var)	고정 항목 (Pins)
NBI_CHAT_MODEL_PROVIDER	General → Chat model → Provider
NBI_CHAT_MODEL_ID	General → Chat model → Model
NBI_INLINE_COMPLETION_MODEL_PROVIDER	General → Auto-complete model → Provider
NBI_INLINE_COMPLETION_MODEL_ID	General → Auto-complete model → Model
NBI_CLAUDE_CHAT_MODEL	Claude → Chat model
NBI_CLAUDE_INLINE_COMPLETION_MODEL	Claude → Auto-complete model
ANTHROPIC_API_KEY	Claude → API Key (입력창이 잠기고 공백 처리됨; SDK가 환경 변수를 직접 읽음)
ANTHROPIC_BASE_URL	Claude → Base URL

Provider ID: github-copilot, openai-compatible, litellm-compatible, ollama, none.

*_MODEL_ID 값은 선택한 제공자 (provider)가 노출하는 값입니다 (예: gpt-4o, llama3:latest). Claude 모델 ID는 Anthropic API의 실제 ID입니다 (예: claude-opus-4-7, claude-sonnet-4-6). 빈 문자열은 "Default (recommended)"를 의미합니다. NBI_CLAUDE_INLINE_COMPLETION_MODEL은 none (Claude 모드에서 인라인 완성 사용 안 함) 또는 inherit (General 탭의 Auto-complete model 사용)도 허용합니다.

**업로드 조절 항목 (Upload tunables)**은 채팅 사이드바 파일 첨부와 터미널 드래그 앤 드롭 모두에서 사용되는 공유 업로드 엔드포인트 (endpoint)를 제어합니다: