안녕하세요, 여러 AI 코딩 에이전트를 번갈아 쓰면서 작업 맥락을 옮기는 과정을 자동화하려고 직접 만든 오픈소스 도구 Vicem을 소개합니다.
무엇을 하는 도구인가요?
Claude Code, OpenAI Codex, Cursor, Antigravity, Gemini CLI 등 로컬에서 사용하는 AI 코딩 에이전트를 전환할 때, 현재 프로젝트의 작업 상태(.vicem/BATON.md
)를 추출해 다음 에이전트의 규칙 파일에 연결해 주는 Node.js 기반 로컬 CLI 및 웹 GUI 도구입니다.
왜 만들었으며, 기존 방식과 무엇이 다른가요?
한 에이전트를 쓰다가 사용량 한도에 도달하거나 특정 문제에서 진전이 없을 때 다른 에이전트로 넘어가곤 합니다. 이때 새 에이전트에게 지금까지 한 작업과 남은 과제를 다시 설명하거나 수동으로 인수인계 문서를 정리하는 과정이 번거로워 만들게 되었습니다.
로컬 상태 기반 컨텍스트 추출 (LLM 요약 호출 없음)- 별도의 API 키나 외부 LLM 호출 없이, 현재 Git 상태(브랜치, 변경 파일, diff 요약), 최근 실행 명령어와 실패 로그, 그리고 직전 에이전트의 로컬 세션 로그(
~/.claude
,~/.codex
등)에서 작업 목표를 읽어.vicem/BATON.md
파일로 정리합니다. - 민감한 토큰이나 API 키 패턴은 로컬에서 정규식으로 마스킹 처리됩니다.
- 별도의 API 키나 외부 LLM 호출 없이, 현재 Git 상태(브랜치, 변경 파일, diff 요약), 최근 실행 명령어와 실패 로그, 그리고 직전 에이전트의 로컬 세션 로그(
기존 규칙 파일을 해치지 않는 마운트 및 복원 (--undo
)- 타겟 에이전트가 시작할 때 바통을 읽도록
CLAUDE.md
,AGENTS.md
,.cursor/rules/vicem-baton.mdc
,GEMINI.md
등에<!-- VICEM-BATON-START/END -->
마커 블록만 추가합니다. - 기존에 작성해 둔 사용자 규칙은 수정하지 않으며, 인계가 끝난 뒤
--undo
옵션으로 마운트된 블록만 제거하고.vicem/history/
에 보관할 수 있습니다.
코드 스켈레톤화 및 MCP 심볼 조회 (--diet
/--mcp
)- 파일 전체를 컨텍스트에 넣기 부담스러울 때 함수·클래스 시그니처만 남기고 본문을 축약한 뒤, 에이전트가 필요한 함수만 내장 MCP 서버(
vicem_expand_symbol
)로 원본을 조회할 수 있는 기능을 포함하고 있습니다.
- 파일 전체를 컨텍스트에 넣기 부담스러울 때 함수·클래스 시그니처만 남기고 본문을 축약한 뒤, 에이전트가 필요한 함수만 내장 MCP 서버(
바로 사용해 보는 방법
외부 패키지 의존성 없이 Node.js(v18 이상)만 설치되어 있으면 별도 가입이나 설정 없이 로컬에서 바로 실행해 볼 수 있습니다.
# 로컬 웹 GUI 실행 (브라우저에서 현재 에이전트 → 다음 에이전트 선택 및 미리보기)
npx @rakkunn/vicem@latest
# CLI에서 바로 바통 생성 및 전달 (예: Codex로 전환)
npx @rakkunn/vicem@latest --to codex --goal "인증 미들웨어 실패 테스트 수정"
# 작업 인계 확인 후 규칙 파일에서 바통 블록 제거
npx @rakkunn/vicem@latest --undo
받고 싶은 피드백
- 여러 코딩 에이전트를 병행해서 쓰시는 분들이 실제로 에이전트를 전환할 때 가장 불편했던 점이나, 바통(
.vicem/BATON.md
)에 추가로 포함되면 좋을 정보가 무엇인지 궁금합니다. - macOS 중심으로 먼저 검증하고 Windows/Linux 호환성을 보완하고 있는데, 각 OS나 에이전트 환경에서 실행 시 의도대로 동작하지 않는 부분이 있다면 편하게 피드백 부탁드립니다.