코딩 에이전트의 컨텍스트 윈도우를 비워내는 로컬 플러그인
에이전트가 파일을 읽거나 명령을 실행할 때 나오는 방대한 결과물이 컨텍스트를 가득 채우는 상황을 막습니다. 이 플러그인은 도구 출력을 로컬 샌드박스에 저장하고, 에이전트가 필요한 부분만 검색해 가져오게 만듭니다. 모든 데이터는 내 컴퓨터에 머물며, 텔레메트리는 전혀 수집하지 않습니다.
출력을 컨텍스트 밖으로 밀어내는 원리
코딩 에이전트는 파일을 읽고 명령을 실행하며 웹 페이지를 가져오는데, 이 모든 결과가 컨텍스트 윈도우에 쌓입니다. Context Mode는 이 과정을 로컬 샌드박스에서 처리하고, 전체 출력을 SQLite 인덱스에 저장합니다. 에이전트는 전체 데이터를 읽지 않고, 짧은 스크립트를 작성해 필요한 정보만 출력받습니다. 이렇게 컨텍스트에 도달하는 바이트 수는 크게 줄어듭니다. 10KB 이상의 원본 출력을 가진 36개 벤치마크 행에서, 이 플러그인의 중앙값 응답은 원본 출력보다 99.4% 작았습니다.
실제 도구에서 확인한 절감 효과
공개 프로젝트의 실제 도구 출력을 통해 절감 효과를 측정했습니다.
- 샌드박스 실행 파일이나 명령을 샌드박스에서 실행할 때 중앙값 99.5%의 출력을 컨텍스트 밖으로 유지합니다.
- 로컬 인덱스 검색 로컬 인덱스에서 검색할 때 매칭 텍스트를 포함하므로 77.2%의 절감률을 보입니다.
- 호스트 도구 출력 한도 초과한 호스트 도구 출력을 전체 인덱싱할 때 98.3%를 절감합니다.
장기 세션과 컴팩션 대응
오래된 세션에서 컨텍스트가 가득 차면 호스트가 이를 압축하고, 에이전트는 짧은 요약만 보게 됩니다. Context Mode는 각 대형 도구 호출의 전체 출력을 로컬의 context.db에 유지합니다. 컴팩션 시 최대 2,048바이트의 스냅샷으로 세션 상태를 보존합니다. 이후 에이전트는 ctx_resume을 호출해 스냅샷을 읽고, ctx_search로 이전 출력을 키워드로 찾을 수 있습니다. 40개의 도구 출력을 가진 스크립트 세션에서, 에이전트를 복귀시킨 ctx_resume 블록은 2,019바이트였습니다.
설치와 요구 사항
이 플러그인은 Node 24.15.0 이상을 요구합니다. Windows에서는 Git for Windows가 필요하며, 셸 도구가 Git Bash에서 실행됩니다. npm 패키지 context-mode로 설치되며, 현재 2.0 릴리스 태그는 @next를 사용합니다. Claude Code, Codex, Gemini CLI, Qwen Code는 GitHub에서 설치하고, 다른 에이전트는 npm 명령으로 설치합니다. 설치 후 에이전트를 재시작하고 /ctx-doctor를 실행해 상태를 확인합니다.
사용 전 확인 사항
이 플러그인은 10가지 코딩 에이전트와 호환되며, 모든 에이전트에 훅, MCP 서버, 플러그인 스킬을 제공합니다. 데이터는 ~/.context-mode에 저장되며, 프로젝트마다 context.db가 생성됩니다. 오프라인에서도 샌드박스 실행, 파일 인덱싱, 검색이 가능합니다. 라이선스는 소스 공개 라이선스로, 개인 및 업무 사용 모두 무료입니다. Context Mode Gateway는 별도의 호스팅 서비스로, 이 플러그인과는 독립적입니다.
