context-mode 쓰는 법

코딩 에이전트를 쓰다 보면 컨텍스트 창이 금세 꽉 찹니다. Playwright 스냅샷 한 번, GitHub 이슈 묶음, 로그 파일 한 줄도 수만 토큰을 먹을 수 있어요. context-mode는 그 원문을 대화에 직접 넣지 않고, MCP 샌드박스에서 돌린 뒤 stdout(결과)만 남기는 쪽에 가깝습니다.

핵심 요약 (TL;DR)

• 무엇: AI 코딩 에이전트용 MCP 플러그인. 도구 출력을 샌드박스에 가두고, 세션 메모리를 SQLite에 남기며, 훅으로 라우팅을 강제합니다.
• 버전: npm [email protected] (GitHub 릴리스 v1.0.169, 2026-06-29 UTC / 2026-06-30 KST 전후).
• 라이선스: Elastic License 2.0 (ELv2, source-available). 호스팅형 관리형 서비스로 제공하거나 라이선스 고지를 지우는 건 제한됩니다.
• 절감 수치: README·패키지 설명은 “컨텍스트 창의 약 98%를 아낀다”고 적습니다. 예: 315 KB → 5.4 KB. 이건 README 벤치/클레임이지, TWMS가 직접 재측정한 값은 아닙니다.
• 지원 하네스: Claude Code, Cursor, Codex CLI, Gemini CLI, VS Code/JetBrains Copilot, OpenCode 등 README 기준 17개 클라이언트(+ OpenClaw).
• 설치 핵심: 대부분 Node.js >= 22.5(또는 Bun) + npm install -g context-mode, Claude Code는 플러그인 마켓플레이스가 가장 쉽습니다.

할 수 있는 일

한 줄로 말하면 “에이전트가 데이터를 통째로 읽게 하지 말고, 코드로 분석하게 만든다”입니다.

• 샌드박스 실행: ctx_execute / ctx_execute_file / ctx_batch_execute로 스크립트를 돌리고, 원문은 샌드박스에 남기고 stdout만 대화에 넣습니다.
• 지식 베이스: ctx_index · ctx_search · ctx_fetch_and_index로 문서를 FTS5에 넣고 BM25로 필요한 조각만 꺼냅니다.
• 세션 연속성: 파일 편집·깃·태스크·에러·유저 결정을 SQLite에 추적해, 컴팩션 후에도 관련 맥락만 다시 가져옵니다.
• 라우팅 강제: 훅이 있는 플랫폼에서는 큰 출력을 내는 도구를 가로채 “샌드박스로 가라”고 밀어줍니다. 훅 없이 MCP만 쓰면 모델이 쓸 수는 있지만 강제력은 약합니다(README 표: 훅 ~98% vs MCP-only ~60% 절감).
• 진단·대시보드: ctx doctor, ctx stats, 호스팅 Insight(context-mode.com/insight).

MCP가 낯설다면: Model Context Protocol은 에이전트에 “외부 도구 서버”를 붙이는 표준입니다. context-mode는 그중에서도 도구 출력이 컨텍스트를 잡아먹는 문제를 겨냥한 서버예요.

필요한 것

• 런타임: Node.js >= 22.5 또는 Bun. Linux에서 Node 22.5 미만은 공식 미지원.
• 패키지: npm의 context-mode (글로벌 설치가 흔한 경로).
• 쓰는 코딩 에이전트 하네스 하나 이상: Claude Code, Cursor, Codex CLI, Gemini CLI, Copilot 계열, OpenCode 등.
• 네트워크: 최초 설치·업그레이드 시 npm/GitHub 접근. Insight 대시보드는 브라우저가 필요합니다.
• 주의 (라이선스): ELv2라서 “그대로 호스팅 SaaS로 팔기”는 안 됩니다. 개인·팀 로컬/에이전트 하네스에 붙이는 용도가 맞습니다.

단계

0) 버전부터 확인

node -v
# v22.5.0 이상인지 확인

npm view context-mode version
# 글 작성 시점 최신: 1.0.169

1) Claude Code — 플러그인이 제일 편함

전제: Claude Code v1.0.33+ (claude --version). /plugin이 안 보이면 먼저 업데이트하세요.

/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

재시작(또는 /reload-plugins) 후:

/context-mode:ctx-doctor

체크가 전부 [x]면 런타임·훅·FTS5·플러그인 등록이 산 겁니다. 라우팅은 SessionStart 훅이 주입해서, 프로젝트에 파일을 안 써도 됩니다.

가볍게 MCP만 써보려면:

claude mcp add context-mode -- npx -y context-mode

이 경로는 11개 MCP 도구는 주지만, 자동 라우팅 훅·슬래시 커맨드는 없습니다.

2) Cursor — 마켓 대기 중, 지금은 로컬/수동

README 기준 마켓플레이스 플러그인은 Cursor 팀 리뷰 대기입니다. 그전까지:

Option A (로컬 플러그인 폴더, macOS/Linux):

git clone https://github.com/mksglu/context-mode.git
ln -s "$PWD/context-mode" ~/.cursor/plugins/local/context-mode

Cursor를 재시작하면 Settings → Plugins에 “Context Mode (Local)”이 뜹니다.

Option B (수동 MCP + hooks):

npm install -g context-mode

프로젝트(또는 글로벌)에 .cursor/mcp.json:

{
  "mcpServers": {
    "context-mode": {
      "command": "context-mode"
    }
  }
}

.cursor/hooks.json 예시(README 그대로):

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "command": "context-mode hook cursor pretooluse",
        "matcher": "Shell|Read|Grep|WebFetch|Task|MCP:ctx_execute|MCP:ctx_execute_file|MCP:ctx_batch_execute"
      }
    ],
    "postToolUse": [
      { "command": "context-mode hook cursor posttooluse" }
    ],
    "stop": [
      { "command": "context-mode hook cursor stop" }
    ]
  }
}

Cursor는 SessionStart 훅이 거절되는 이슈가 있어, 라우팅 안내를 위해 rules 파일을 복사합니다:

mkdir -p .cursor/rules
cp node_modules/context-mode/configs/cursor/context-mode.mdc .cursor/rules/context-mode.mdc

확인: Settings → MCP에서 connected, 에이전트 채팅에 ctx stats.

3) Codex CLI — 플러그인 + feature flag

codex plugin marketplace add mksglu/context-mode

아직 게이트된 훅을 켜려면 config에:

[features]
plugin_hooks = true
hooks = true

재시작 후 ctx stats로 MCP 연결을 확인하고, Codex가 훅 승인(trust)을 물으면 허용하세요. ctx stats만으로는 “훅이 돌고 있다”까지는 증명되지 않는다고 README가 분명히 적습니다.

플러그인 훅이 없는 구빌드용 수동 폴백은 npm install -g context-mode 후 ~/.codex/config.toml에 [mcp_servers.context-mode]와 hooks.json을 넣는 경로입니다(상세는 README Codex 절).

4) 그 외 빠르게

• Gemini CLI / VS Code Copilot: npm install -g context-mode → settings/mcp.json + hooks 등록 → 재시작 → ctx stats.
• OpenCode: opencode.json에 "plugin": ["context-mode"]. 예전 mcp.context-mode와 같이 두면 도구가 0개가 될 수 있어, 그땐 context-mode upgrade로 legacy MCP 항목을 정리합니다.

5) 설치 후 바로 해볼 것

ctx doctor
ctx stats

터미널에서는:

context-mode doctor
npm list -g context-mode

Claude Code에서는 슬래시 커맨드(/context-mode:ctx-stats 등)도 됩니다. 다른 하네스에서는 채팅에 ctx stats처럼 치면 모델이 MCP 도구를 호출합니다.

막히는 지점

버전 확인

• npm latest: 1.0.169 (npm view context-mode version)
• GitHub release: v1.0.169 — context-savings 리포팅·FinOps 정확도 개선(로컬 stats와 Insight 정렬 등).
• 엔진: "node": ">=22.5.0"
• 라이선스 필드: Elastic-2.0
• 저장소: github.com/mksglu/context-mode · 패키지: npmjs.com/package/context-mode

업그레이드:

npm install -g context-mode@latest
# 세션 안에서는
ctx upgrade
# 또는
context-mode upgrade

마치며

컨텍스트 창이 빨리 닳는 건 모델이 약해서가 아니라, 도구가 원문을 그대로 뱉기 때문인 경우가 많아요. context-mode는 그 원문을 샌드박스에 두고 결과만 가져오게 만드는 MCP+훅 하네스입니다. Claude Code면 플러그인 두 줄, Cursor/Codex는 지금 시점엔 수동 설정이 조금 더 필요합니다. 설치 후엔 무조건 ctx doctor → ctx stats 순으로 확인해 보세요.

공식 숫자(98% 등)는 README 벤치 클레임으로 두고, 본인 워크플로에서 stats로 한 번 재는 게 제일 안전합니다.

이 글은 AI가 작성하여 자동 발행된 콘텐츠입니다.