Context Mode는 원시 도구 출력을 대화 컨텍스트에 그대로 넣지 않고 샌드박스에서 처리하는 오픈소스 MCP 서버다. 제작자는 315KB의 원시 출력이 5.4KB로 줄어든다고 설명하며, 대화 압축 뒤 작업 상태를 복원하는 기능과 여러 코딩 도구에서의 설치 방법도 제공한다. 수치는 프로젝트가 제시한 벤치마크이며, 플랫폼마다 훅 지원과 설정 방식이 다르다.
컨텍스트를 줄이고 세션을 잇는 방식
MCP 도구는 큰 응답을 그대로 컨텍스트에 넣을 수 있다. 프로젝트 문서는 Playwright 스냅샷 56KB, GitHub 이슈 20개 59KB, 접근 로그 하나 45KB를 예로 든다. 대화가 길어져 모델이 공간을 확보하려고 기록을 압축하면 편집 중인 파일이나 진행 중인 작업, 사용자의 마지막 요청을 잊을 수 있다는 것이 제작자의 문제 제기다.
Context Mode는 원시 데이터를 격리된 하위 프로세스에서 처리하고, ctx_execute가 만든 결과 가운데 표준 출력만 대화에 보낸다. 여러 파일을 읽어 분석할 때는 모델이 분석용 코드를 작성하고 필요한 결과만 출력하도록 하는 방식도 제안한다. 프로젝트 예시에서는 47 × Read()로 700KB를 보내는 대신 1 × ctx_execute()로 3.6KB를 보내도록 안내한다. 도구는 JavaScript, TypeScript, Python, Shell, Ruby, Go, Rust, PHP, Perl, R, Elixir, C# 등 12개 언어 런타임을 지원하며, Bun이 있으면 JavaScript·TypeScript 실행에 자동 감지해 사용한다.
ctx_execute 호출마다 격리된 하위 프로세스를 실행하므로 각 호출은 서로의 메모리나 상태를 공유하지 않는다. gh, aws, gcloud, kubectl, docker 같은 인증된 CLI는 환경 변수와 설정 경로를 전달받아 쓸 수 있다고 문서는 설명한다. 출력이 5KB를 넘고 intent가 지정되면 전체 출력을 지식 베이스에 색인한 뒤 의도와 맞는 부분만 검색해 반환한다.
ctx_index는 마크다운을 제목 단위로 나누되 코드 블록은 유지해 SQLite FTS5에 저장한다. 검색은 BM25 순위를 쓰며, 제목과 소제목의 가중치를 5배로 둔다. Porter 어간 검색과 부분 문자열 검색을 함께 수행하고 Reciprocal Rank Fusion으로 결과를 합친다. 여러 검색어가 가까이 등장하는 결과를 높이는 재정렬, Levenshtein 거리 기반 오타 보정, 검색어 주변 내용을 뽑는 스니펫 추출도 포함한다. ctx_fetch_and_index는 URL을 가져와 마크다운으로 변환·색인하며 원문 페이지를 컨텍스트에 넣지 않는다.
기본 캐시 유효 기간(TTL)은 24시간이다. 유효 기간 안에 이미 색인한 URL을 다시 요청하면 재수집 대신 약 0.3KB의 캐시 안내를 돌려주며, ctx_search로 기존 색인을 검색하도록 한다. ttl: <ms>로 기간을 바꾸거나 ttl: 0, force: true로 캐시를 우회할 수 있다. 시작 시 14일보다 오래된 콘텐츠 데이터베이스와 출처를 정리한다. 검색 호출은 1~3회까지 질의당 결과 2개, 4~8회에는 결과 1개와 경고를 제공하고, 9회째부터는 차단해 ctx_batch_execute 사용으로 돌린다.
대화 압축이나 --continue, --resume, /resume으로 재개할 때는 SQLite에 저장한 파일 편집, 작업, 오류, 결정 등을 바탕으로 상태를 복원한다. 이전 세션의 이벤트를 컨텍스트에 통째로 되돌려 넣는 대신 FTS5 색인과 BM25 검색으로 필요한 정보를 가져온다. 우선순위를 둔 최대 2KB 스냅샷에서는 공간이 부족하면 낮은 우선순위 항목부터 제외하고, 활성 파일·작업·규칙·결정은 보존한다고 설명한다. 복원 안내에는 마지막 요청, 작업 상태, 계획, 결정, 수정 파일, 미해결 오류, 제약, 차단 요인, Git 작업, 프로젝트 규칙, 사용한 도구와 하위 에이전트 결과 등이 포함될 수 있다. --continue를 지정하지 않으면 이전 세션 데이터는 즉시 삭제된다.
도구와 수치
주요 도구는 다음과 같다.
ctx_batch_execute: 여러 명령 실행과 여러 검색을 한 번에 수행한다. I/O 작업에는concurrency: 1-8을 선택할 수 있다.ctx_execute: 12개 언어로 코드를 실행하고 표준 출력만 컨텍스트에 보낸다.ctx_execute_file: 샌드박스에서 파일을 처리한다.ctx_index,ctx_search: 콘텐츠를 색인하고 검색한다.ctx_fetch_and_index: URL을 가져와 색인하며 캐시와 병렬 수집을 지원한다.ctx_stats,ctx_doctor,ctx_upgrade,ctx_purge: 절감 통계, 설치 진단, 업데이트, 색인 콘텐츠 삭제를 담당한다.
프로젝트 벤치마크에서 Playwright 스냅샷은 56.2KB에서 299B(99% 절감), GitHub 이슈 20개는 58.9KB에서 1.1KB(98%), 요청 500건의 접근 로그는 45.1KB에서 155B(100%), Context7 React 문서는 5.9KB에서 261B(96%), 500행 분석 CSV는 85.5KB에서 222B(100%), 153개 커밋의 Git 로그는 11.6KB에서 107B(99%), 테스트 30개 묶음 출력은 6.0KB에서 337B(95%)로 제시됐다. 하위 에이전트를 이용한 저장소 조사 사례는 986KB에서 62KB(94%)다. 프로젝트는 전체 세션에서 원시 출력 315KB가 5.4KB가 되고 세션 시간이 약 30분에서 약 3시간으로 늘어난다고 주장한다. 21개 시나리오의 전체 벤치마크를 제공하지만, 자료에는 독립 검증 여부가 제시돼 있지 않다.
설치와 플랫폼별 조건
설치 안내는 훅을 지원해 자동으로 도구 호출을 중재하는 플랫폼과, 안내 파일을 수동으로 복사해야 하는 플랫폼을 구분한다. 지원 플랫폼에는 Claude Code, Gemini CLI, VS Code Copilot, JetBrains Copilot, GitHub Copilot CLI, Cursor, OpenCode, KiloCode, OpenClaw/Pi Agent, Codex CLI, Kimi Code, Qwen Code, Antigravity IDE와 CLI(agy), Kiro, Zed, Pi Coding Agent, OMP가 포함된다. 대부분의 CLI·IDE 연동은 Node.js 22.5 이상 또는 Bun을 요구한다. 각 플랫폼의 설정과 기능 차이는 플랫폼 지원 문서에 정리돼 있다.
Claude Code 플러그인은 Claude Code v1.0.33 이상에서 다음 명령으로 설치한다. /plugin을 인식하지 못하면 Claude Code를 먼저 업데이트해야 한다.
/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode
재시작하거나 /reload-plugins를 실행한 뒤 /context-mode:ctx-doctor로 런타임, 훅, FTS5, 플러그인 등록을 확인한다. 이 플러그인은 세션 시작 훅으로 라우팅 지침을 주입하고, 훅 6종과 MCP 도구 11개를 등록한다. 훅 없이 MCP 도구만 시험하려면 claude mcp add context-mode -- npx -y context-mode를 사용할 수 있다. 선택 사항인 상태 표시줄은 ~/.claude/settings.json에 설정하며, 플러그인 매니페스트가 이를 선언하지 못하므로 직접 추가해야 한다.
Gemini CLI는 Node.js 22.5 이상 또는 Bun이 필요하다. npm install -g context-mode로 설치하고 ~/.gemini/settings.json에 MCP 서버와 BeforeTool, AfterTool, PreCompress, SessionStart 훅을 등록한다. 재시작 후 /mcp list에서 연결 상태를 확인한다. 전체 모델 지침이 필요하면 node_modules/context-mode/configs/gemini-cli/GEMINI.md를 프로젝트의 GEMINI.md로 복사할 수 있다. BeforeTool 매처는 큰 출력을 만들 수 있는 도구와 context-mode 도구에 한정돼 가벼운 도구에서 불필요한 훅 실행을 피한다. 설정 예시가 있다.
VS Code Copilot은 Copilot Chat v0.32 이상, JetBrains Copilot은 플러그인 v1.5.57 이상이 필요하다. 두 경우 모두 전역 설치 후 프로젝트에 MCP 설정과 .github/hooks/context-mode.json을 만들고 에디터를 재시작한다. VS Code 설정은 .vscode/mcp.json, JetBrains는 IDE의 Settings > Tools > AI Assistant > Model Context Protocol (MCP)에서 서버를 추가한다. 채팅에 ctx stats를 입력해 확인한다. 두 플랫폼 모두 세션 시작 훅으로 라우팅하며, 선택적으로 각각 copilot-instructions.md를 복사할 수 있다. VS Code 훅 설정과 JetBrains 안내를 제공한다.
GitHub Copilot CLI는 플러그인 설치를 권장한다. npm install -g context-mode 뒤 copilot plugin install mksglu/context-mode:configs/copilot-cli를 실행하면 MCP, 훅, 라우팅 스킬이 등록된다. 수동 설치는 같은 전역 설치 후 copilot mcp add context-mode -- context-mode로 MCP를 추가하고 ~/.copilot/hooks/context-mode.json 또는 $COPILOT_HOME/hooks/context-mode.json에 훅을 설정하는 방식이다. 훅은 전역 context-mode 실행 파일을 사용하므로 Copilot CLI 지원 버전이 필요하다. 오래된 버전에서는 훅이 라우팅이나 기록을 하지 않지만 도구 실행을 막지는 않는다. npm install -g context-mode@latest로 업데이트한다. 자세한 내용은 플랫폼 문서와 추적 이슈 #775를 참고한다.
Cursor는 Node.js 22.5 이상 또는 Bun이 필요하다. 마켓플레이스 플러그인은 Cursor 팀의 검토를 기다리는 중이어서, 게시 전에는 저장소를 복제해 로컬 플러그인으로 설치하거나 수동 설정을 사용한다. Windows에서는 심볼릭 링크 대신 robocopy를 사용한다. 수동 설치는 npm install -g context-mode 후 .cursor/mcp.json과 .cursor/hooks.json을 만들고, node_modules/context-mode/configs/cursor/context-mode.mdc를 .cursor/rules/context-mode.mdc로 복사한다. Cursor는 현재 sessionStart 훅을 거부하며 훅 응답의 additional_context도 모델에 전달하지 않는다는 한계가 있다. 따라서 라우팅 안내는 규칙 파일에 의존한다. 마켓플레이스 진행 상황은 #485와 #489에 기록돼 있다.
OpenCode와 KiloCode는 설정 파일에 plugin: ["context-mode"]를 추가해 TypeScript 플러그인을 등록한다. 각각 opencode.json과 kilo.json을 사용하며, 플러그인은 MCP 도구 11개와 훅을 프로세스 안에서 등록한다. 선택 사항으로 AGENTS.md를 복사해 모델에 라우팅 지침을 제공한다. 기존 설정에 플러그인과 mcp.context-mode를 함께 두면 도구가 하나도 등록되지 않을 수 있으므로 context-mode upgrade로 중복된 레거시 항목을 제거한다. 다른 MCP 서버 설정은 보존된다. OpenCode는 실제 SessionStart 훅 대신 experimental.chat.system.transform을 사용하고, 사용자 메시지는 chat.message로 수집한다. 두 플랫폼의 안내 파일은 OpenCode 설정과 AGENTS.md에서 볼 수 있다.
OpenClaw/Pi Agent 연동은 별도 MCP 서버가 아니라 OpenClaw 게이트웨이 플러그인으로 작동한다. OpenClaw가 2026.1.29보다 높은 버전이어야 하며 Node.js 22 이상이 필요하다. 저장소를 복제한 뒤 npm run install:openclaw를 실행한다. 기본 설치 경로는 /openclaw이며 $OPENCLAW_STATE_DIR로 바꿀 수 있다. 설치기는 의존성 설치, 빌드, 네이티브 모듈 재빌드, 확장 등록과 게이트웨이 재시작을 처리한다. 이전 버전에서는 생명주기 훅이 작동하지 않을 수 있으며 DB 스냅샷 재구성으로 대체한다. 어댑터 문서가 있다.
Codex CLI는 플러그인 마켓플레이스에서 mksglu/context-mode를 추가해 설치한다. 플러그인 훅이 기능 플래그로 보호되는 동안 [features].plugin_hooks = true와 [features].hooks = true를 켜고, 훅 승인을 요청받으면 플러그인 훅을 검토해 허용해야 한다. ctx stats는 MCP 연결을 확인할 뿐 훅이 신뢰돼 실행 중인지는 증명하지 않는다. Node.js가 Codex 프로세스의 PATH에 있어야 한다. 훅을 지원하지 않는 빌드에서는 npm install -g context-mode 후 ~/.codex/config.toml에 MCP 서버와 hooks = true를 설정하고 $CODEX_HOME/hooks.json 또는 ~/.codex/hooks.json을 구성하는 수동 대체 방법을 쓴다. PreCompact는 이벤트를 내보내는 Codex CLI 0.130.0에서 지원되며 이전 빌드에서는 압축 전 스냅샷이 생성되지 않는다. PreToolUse는 현재 거부 규칙만 지원해 입력 수정은 상위 프로젝트의 updatedInput 지원을 기다린다(이슈). 저장 경로를 바꾸려면 실행 환경에 절대 경로로 CONTEXT_MODE_DIR을 지정한다.
Kimi Code는 전역 설치 후 ~/.kimi-code/mcp.json에 MCP 서버를, ~/.kimi-code/config.toml에 PreToolUse, PostToolUse, SessionStart, PreCompact, UserPromptSubmit, Stop 훅을 설정한다. Codex와 같은 JSON 입출력 프로토콜을 쓰지만 PreToolUse 응답에서 Codex가 거부하는 additionalContext, updatedInput, permissionDecision: "ask"를 지원한다. Kimi Code 안내를 제공한다.
Qwen Code는 npm install -g @qwen-code/qwen-code로 Qwen Code를 설치한 뒤 context-mode를 전역 설치하고 ~/.qwen/settings.json에 MCP 서버와 훅을 추가한다. 라우팅 안내는 node_modules/context-mode/configs/qwen-code/QWEN.md를 프로젝트의 QWEN.md로 복사한다. Claude Code와 같은 훅 프로토콜을 사용한다.
Antigravity 데스크톱 IDE는 훅을 지원하지 않는다. 전역 설치 후 ~/.gemini/antigravity/mcp_config.json에 서버를 등록하고 GEMINI.md를 프로젝트에 복사한다. 이 파일이 유일한 라우팅 방법이며 문서는 준수율을 약 60%로 제시한다. 반면 Antigravity CLI인 agy는 1.0.7 이상에서 플러그인 설치를 지원한다. npm install -g context-mode와 agy plugin install https://github.com/mksglu/context-mode/tree/main/configs/antigravity-cli를 실행한 뒤 재시작한다. MCP 도구만 원하면 ~/.gemini/config/mcp_config.json에 서버를 추가한다. 제거 명령은 agy plugin uninstall context-mode다.
Kiro는 MCP 설정과 .kiro/hooks/context-mode.json을 추가하고, KIRO.md를 프로젝트에 복사한 뒤 재시작한다. agentSpawn에 해당하는 세션 시작 기능이 아직 연결되지 않아 압축 뒤 세션 복원은 지원되지 않는다. Zed는 ~/.config/zed/settings.json(Windows는 %APPDATA%\Zed\settings.json)의 context_servers에 서버를 등록하고 AGENTS.md를 복사한다. 두 IDE 모두 훅이 없으므로 세션 추적을 제공하지 않으며, 문서 파일에 의존하는 라우팅 준수율은 약 60%로 제시된다.
Pi Coding Agent는 전역 설치 후 pi install npm:context-mode로 패키지를 설치한다. 대안으로 ~/.pi/agent/settings.json에 패키지를 등록하고 MCP 설정을 추가할 수 있다. OMP(Oh My Pi)는 omp plugin install context-mode를 권장하며, 플러그인이 첫 로드 때 MCP 서버를 등록한다. 수동 플러그인 설치는 cd ~/.omp/plugins 후 bun add context-mode 또는 npm install context-mode다. MCP만 쓰려면 ~/.omp/agent/mcp.json에 서버를 추가하고 SYSTEM.md를 복사한다. Pi와 OMP는 저장 경로를 분리한다.
설치 환경·보안·개인정보
Node.js에서 SQLite 저장소는 환경에 따라 달라진다. Linux에서 Node.js 22.5 이상은 내장 node:sqlite를 쓰고, Bun은 bun:sqlite를 자동 사용해 네이티브 컴파일을 피한다. 그 밖에는 better-sqlite3를 사용한다. glibc 2.31 이상에서는 대부분 사전 빌드된 바이너리를 쓸 수 있다. CentOS 7/8, RHEL 8, Debian 10 등 오래된 glibc 환경은 C++20 컴파일러(GCC 10 이상), Make, setuptools가 필요할 수 있다. 문서는 CentOS 8/RHEL 8에서 gcc-toolset-10을, CentOS 7/RHEL 7에서 devtoolset-10을 설치하는 명령과 Alpine의 build-base, Python, setuptools 설치 명령을 안내한다. Windows에서 네이티브 바인딩이 빠진 경우 설치 후 스크립트와 런타임 훅이 이를 다시 가져오도록 한다고 설명한다.
프로젝트 권한 규칙은 MCP 샌드박스에도 적용된다. 권한이 따로 설정되지 않았다면 동작은 바뀌지 않는다. deny가 allow보다 우선하며, &&, ;, |로 연결한 명령은 각 부분을 따로 검사한다. 보안 정책은 Claude Code 형식의 .claude/settings.json 또는 ~/.claude/settings.json에서 읽는다. Codex CLI는 Codex 훅을 별도로 구성해야 한다. ctx_execute_file은 기본적으로 프로젝트 바깥 파일 읽기를 거부하며, 필요한 경로는 기존 permissions.allow 규칙으로 허용한다. 다만 ctx_execute와 ctx_batch_execute는 임의 코드를 실행하고 프로세스의 파일 접근 권한을 상속하므로, 문서는 이를 완전한 OS 샌드박스로 보지 말고 호스트 수준 샌드박스를 유지하라고 경고한다.
ctx_fetch_and_index는 HTTP와 HTTPS만 허용한다. 클라우드 메타데이터 주소와 링크 로컬, 멀티캐스트, 예약 주소는 차단한다. 기본 설정에서는 로컬호스트와 사설 네트워크 주소는 개발 서버와 내부 네트워크 사용을 위해 허용한다. 공유 서비스나 CI에서 이를 차단하려면 CTX_FETCH_STRICT=1을 설정한다. MCP 도구 호출의 입력은 세션 데이터베이스에 저장되기 전에 토큰, 비밀번호, 쿠키, API 키, 비밀 키 등으로 보이는 값을 [REDACTED]로 바꾼다.
제작자는 텔레메트리, 클라우드 동기화, 사용량 추적, 계정이 없고 코드·프롬프트·세션 데이터가 로컬에 저장된다고 설명한다. 저장소는 사용자의 홈 디렉터리에 있는 SQLite 데이터베이스를 이용한다. 라이선스는 MIT가 아니라 소스 공개형 Elastic License 2.0이다. 사용, 포크, 수정, 배포는 허용하지만 호스팅·관리형 서비스로 제공하거나 라이선스 고지를 제거하는 것은 금지한다. 저장소와 라이선스에서 전체 내용을 확인할 수 있다.
댓글 (0)
로그인하면 이 기사에 내 생각을 남길 수 있어요