relay-baton

자동 폴백 감지

에이전트 출력에서 “usage limit reached”, “rate limit exceeded”, “maximum context length”, “quota exceeded” 같은 패턴을 감지하면 다음 에이전트로 핸드오프를 시작합니다. grep 결과나 패턴 해설 같은 일반 문장은 false-positive 방어로 건너뜁니다.

토큰 다이어트

off · lite · balanced · caveman · ultra 다섯 가지 결정적 압축 프로파일을 제공합니다. 락 파일, 빌드 산출물, 경량화된 번들, 바이너리 블롭은 제외되고, 로그는 끝부분만 유지되며, 전체 소스 대신 repo map이 사용됩니다.

Plan-Execute 모드

반응형 폴백 대신 계획을 먼저 세우는 능동형 흐름입니다. 기본값으로 Claude가 플래너가 되어 .ai-session/plan.md를 작성하고 PlanQualityGate가 완결성을 검증한 뒤 Codex가 실행자로 구현을 담당합니다. relay-baton plan "..." --then-execute로 한 번에 실행할 수도 있습니다.

컨텍스트 압축

세션 중간에 state.md와 commands.log를 결정적으로 압축해 컨텍스트 한도에 도달하기 전까지 더 오래 동작하도록 합니다. 모델 호출 없이 완전히 가역적이며 원본은 commands.log.full.<ts>로 회전됩니다.

품질 게이트와 안전

핸드오프가 다음 에이전트를 실행하기 전에 HandoffQualityGate와 TokenDietQualityGate를 통과해야 합니다. OPENAI_API_KEY와 ANTHROPIC_API_KEY는 기본적으로 자식 프로세스에서 제거되며, 키는 저장·출력·기록되지 않습니다.

설치와 기본 사용

가장 빠른 경로는 npm 글로벌 설치입니다.

• npm i -g @relay-baton/cli로 relay-baton 명령을 등록합니다.
• relay-baton doctor로 git, Codex, Claude 환경과 설정을 점검합니다.
• relay-baton login으로 두 CLI의 인증 흐름을 모두 진행합니다.
• relay-baton run "작업 설명" --diet balanced로 Codex를 시작하고 필요 시 Claude로 자동 핸드오프합니다.

Windows에서는 winget을 통한 설치도 제공됩니다.

• winget install --id dgl1231.relay-baton --exact

소스에서 개발용으로 실행할 때는 저장소 루트에서 pnpm install → pnpm build → pnpm relay-baton doctor → pnpm relay-baton run "..." 순으로 진행합니다. TUI 대시보드는 relay-baton tui로 열 수 있으며 에이전트를 실행하지 않고 세션 상태를 확인할 때 유용합니다.

활용 예시

Codex가 컨텍스트 한도나 사용량 제한에 도달해 작업을 멈춘 경우, relay-baton이 저장소의 실제 상태를 기반으로 압축된 핸드오프 문서를 만들고 Claude Code가 이어받아 동일한 코드 상태에서 작업을 재개합니다. 여러 저장소를 relay-baton project add로 등록해 두면 project switch로 활성 프로젝트를 바꿔가며 동일한 핸드오프 흐름을 재사용할 수 있습니다.

제한과 라이선스

MIT 라이선스로 배포되며 npm, Homebrew, Scoop, winget 등 다양한 패키지 관리 채널을 통해 설치할 수 있습니다. relay-baton 자체는 LLM이나 토크나이저를 호출하지 않고 글자 수 기준으로 동작하며, 현재 지원 에이전트 어댑터는 Codex와 Claude뿐입니다. TUI는 에이전트를 실행하지 않으며 v0.2 이후로는 no-run 핸드오프 생성만 허용합니다.