# relay-baton v0.1.0 릴리즈 노트

날짜: 2026-05-27

## 요약

v0.1.0은 relay-baton의 초기 MVP다. Codex CLI에서 시작한 작업을 Claude Code CLI로 이어받기 위한 token-aware handoff 앱의 기본 흐름을 구현했다.

핵심 목표:

1. Codex CLI로 작업을 시작한다.
2. usage/rate/token/context/quota 계열 한계 상황을 감지한다.
3. 현재 repository 상태를 `.ai-session/`에 정리한다.
4. 전체 로그와 전체 diff를 붙여넣지 않고 compact handoff를 만든다.
5. Claude Code가 이어서 작업할 수 있는 continuation prompt를 만든다.

이 버전에서 compact handoff, file reference, session artifact 기반의 기본 사용 흐름이 만들어졌다.

## 아키텍처

TypeScript / Node.js / pnpm monorepo로 구성했다.

```text
packages/
  shared/
  core/
  cli/
  tui/
```

역할:

- `packages/shared`: 공통 타입과 상수.
- `packages/core`: config, session, git, agent adapter, fallback detector, token diet, handoff, quality gate, workflow.
- `packages/cli`: Commander 기반 CLI.
- `packages/tui`: Ink 기반 터미널 UI.

중요한 설계 원칙:

- 핵심 business logic은 `core`에 둔다.
- CLI와 TUI는 얇은 wrapper로 유지한다.
- agent별 실행 로직은 adapter로 분리한다.

## 주요 구현

### Codex / Claude CLI Adapter

로컬 CLI subprocess 실행을 위한 adapter 계층을 추가했다.

Codex 기본 실행:

```bash
codex exec --sandbox workspace-write "<task>"
```

Claude Code 기본 실행:

```bash
claude --permission-mode acceptEdits -p "<prompt>"
```

기본 실행 방식은 README에 문서화했고, 필요하면 `relay-baton.config.json`에서 override할 수 있다.

### CLI 명령어

구현된 명령어:

```bash
relay-baton init
relay-baton doctor
relay-baton status
relay-baton run "<task>"
relay-baton handoff --to claude
relay-baton compact
relay-baton squeeze
relay-baton budget
relay-baton compress <file>
relay-baton tui
relay-baton login [agent]
```

주요 옵션:

```bash
relay-baton run "<task>" --diet caveman
relay-baton run "<task>" --allow-api-key-env
relay-baton handoff --to claude --diet caveman
relay-baton handoff --to claude --no-run
relay-baton handoff --to claude --force
relay-baton compress <file> --write
relay-baton compress <file> --out <path>
```

### `.ai-session/` 파일 구조

repository root 아래에 `.ai-session/`을 만들고 작업 상태를 저장한다.

```text
.ai-session/task.md
.ai-session/state.md
.ai-session/compact-state.md
.ai-session/handoff.md
.ai-session/decisions.md
.ai-session/changed-files.md
.ai-session/repo-map.md
.ai-session/commands.log
.ai-session/errors.md
.ai-session/test-results.md
.ai-session/full-diff.patch
.ai-session/context-budget.json
.ai-session/session.json
```

설계 의도:

- `handoff.md`는 짧게 유지한다.
- 큰 정보는 파일로 저장하고 handoff에서 참조한다.
- 전체 diff와 전체 log는 별도 artifact 파일로 분리한다.

### Token Diet

5개 profile을 추가했다.

- `off`
- `lite`
- `balanced`
- `caveman`
- `ultra`

기본 profile:

- `balanced`

특징:

- character budget 기반으로 예측 가능한 local compaction을 수행한다.
- `caveman`은 장난스러운 말투가 아니라 aggressive minimal-context profile이다.

주요 모듈:

- `BudgetManager`
- `ContextSelector`
- `DiffCompactor`
- `LogCompactor`
- `StateCompactor`
- `HandoffCompactor`
- `ReferenceResolver`
- `DeterministicCompress`

파일 분리:

- full diff: `.ai-session/full-diff.patch`
- full logs: `.ai-session/commands.log`
- compact state: `.ai-session/compact-state.md`
- repo map: `.ai-session/repo-map.md`
- budget snapshot: `.ai-session/context-budget.json`

### Handoff Workflow

구현 모듈:

- `HandoffGenerator`
- `PromptBuilder`
- `BatonWorkflow`
- `HandoffQualityGate`
- `TokenDietQualityGate`

Quality gate 동작:

- 필수 파일 존재 여부 확인.
- `handoff.md` 필수 section 확인.
- token diet budget 초과 여부 확인.
- full logs, AGENTS.md, CLAUDE.md 같은 큰 instruction body가 handoff에 inline되지 않았는지 확인.
- 실패 시 기본적으로 fallback 실행을 막고, `--force`로만 override할 수 있다.

### Fallback Detection

단어 하나만 보는 방식 대신 phrase 중심 감지를 구현했다.

감지 phrase 예:

- `usage limit reached`
- `rate limit exceeded`
- `context length exceeded`
- `context limit exceeded`
- `token limit exceeded`
- `quota exceeded`
- `quota limit`
- `insufficient quota`
- `maximum context length`
- `too many requests`

오탐 방지:

- `README.md:10:` 같은 grep 결과 라인은 제외한다.
- fallback/quota/token/context 패턴을 설명하는 문서 라인은 제외한다.
- `usage limit reached`처럼 실제 한계 상황을 나타내는 phrase 중심으로 fallback을 감지한다.

### Git / Repo Map

추가 모듈:

- `GitService`
- `RepoMapGenerator`

용도:

- git repository 여부 확인.
- changed files 수집.
- full diff snapshot 생성.
- compact repo map 생성.

기본 제외 디렉터리:

- `node_modules`
- `.git`
- `dist`
- `build`
- `.next`
- `.turbo`
- `coverage`
- `bin`
- `obj`
- `.ai-session`

### Auth / Billing

기본 실행 방식은 사용자의 local CLI session을 활용한다.

- local `codex` subprocess
- local `claude` subprocess

기본적으로 child process에 전달하지 않는 env:

- `OPENAI_API_KEY`
- `ANTHROPIC_API_KEY`

명시적으로 허용하는 경우에만 전달한다.

```bash
--allow-api-key-env
```

또는:

```json
{
  "authPolicy": {
    "allowApiKeyEnv": true
  }
}
```

정책:

- `doctor`는 set/not-set 여부만 표시한다.

### TUI

초기 Ink TUI를 추가했다.

v0.1 범위:

- read-only session dashboard.
- session status, agent availability, budget, task, compact state, changed files, command log tail 표시.
- `q` 종료.
- `r` refresh.

relay-baton의 첫 번째 시각적 session dashboard 역할을 한다.

## 호환성

v0.1은 현재 cwd를 target repository로 가정한다.

project registry와 `--project` / `--path`는 v0.2에서 추가됐다.

## v0.2로 이어진 추천 작업

- project/workspace 관리 추가.
- 기존 명령어에 `--project` / `--path` 추가.
- TUI를 project/session dashboard로 개선.
- `.gitattributes` 추가.
- Codex/Claude 혼합 작업을 위한 release notes와 문서 강화.