# relay-baton v0.1.0 Release Notes

Date: 2026-05-27

## Summary

v0.1.0 is the initial MVP of relay-baton: a token-aware handoff app for moving coding-agent work from Codex CLI to Claude Code.

The main goal was to prove the core workflow:

1. Start work with Codex CLI.
2. Detect usage/rate/token/context/quota fallback conditions.
3. Capture the current repository state.
4. Generate a compact handoff packet.
5. Continue with Claude Code using local CLI subprocesses.

The result is a working baseline for compact, file-reference-based handoff between two local coding-agent CLIs.

## Architecture

Implemented as a TypeScript / Node.js / pnpm monorepo:

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

Package responsibilities:

- `packages/shared`: shared types and constants.
- `packages/core`: configuration, sessions, git inspection, agent adapters, fallback detection, token diet, handoff generation, quality gates, workflow orchestration.
- `packages/cli`: Commander-based CLI commands.
- `packages/tui`: Ink-based terminal UI.

This split is important for future work: CLI and TUI should remain thin shells over `core`.

## Major Features

### Codex And Claude CLI Adapters

Added agent adapter layer for local CLI subprocess execution.

Default Codex invocation:

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

Default Claude Code invocation:

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

The defaults are documented in the README and can be overridden through `relay-baton.config.json`.

### CLI Commands

Implemented:

```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]
```

Key options:

```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>
```

### Session Files

Created `.ai-session/` as the local state surface:

```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
```

Design rule:

- `handoff.md` should stay compact.
- Large content is written to referenced files instead of being pasted inline.

### Token Diet

Added five token diet profiles:

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

Default profile:

- `balanced`

Important behavior:

- Uses character budgets for predictable local compaction.
- `caveman` means aggressive minimal-context, not a joke tone.

Core token diet modules:

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

Token diet output strategy:

- Full diff goes to `.ai-session/full-diff.patch`.
- Full logs go to `.ai-session/commands.log`.
- Compact state goes to `.ai-session/compact-state.md`.
- Repo map goes to `.ai-session/repo-map.md`.
- Budget snapshot goes to `.ai-session/context-budget.json`.

### Handoff Workflow

Implemented handoff generation through:

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

Handoff quality gate checks:

- Required files exist and are non-empty.
- `handoff.md` includes required sections.
- Launch is blocked unless `--force` is used when required content is missing.

Token diet quality gate checks:

- `handoff.md` stays under the selected profile budget.
- Token Diet Summary is present.
- Truncate marker is present when truncation happened.
- Full logs, full instruction files, and large raw content are not inlined.

### Fallback Detection

Added phrase-based fallback detection to avoid keyword-only false positives.

Detection phrases include:

- `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`

False-positive protections:

- Grep-style result lines such as `README.md:10:` or `src/file.ts:12:` are ignored.
- Documentation lines that merely describe fallback/quota/token/context patterns are ignored.
- Bare keywords like `quota` alone are not enough.

### Git And Repo Map

Added:

- `GitService`
- `RepoMapGenerator`

Used for:

- Checking whether commands are running inside a git repository.
- Capturing changed files.
- Creating `full-diff.patch`.
- Creating compact repository maps.

Default excluded directories:

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

### Auth And Billing

Default execution uses the user's local CLI sessions:

- `codex`
- `claude`

API key env vars are stripped from child processes by default:

- `OPENAI_API_KEY`
- `ANTHROPIC_API_KEY`

They are only passed when explicitly allowed by:

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

or config:

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

`doctor` reports whether relevant env vars are set without printing their values.

### TUI

Initial Ink TUI added.

v0.1 scope:

- Read-only session dashboard.
- Shows session status, agents, token budget snapshot, task, compact state, changed files, and command log tail.
- Supports `q` to quit and `r` to refresh.

This gave the first visible session dashboard for relay-baton.

## Compatibility Notes

v0.1 assumes the current working directory is the target repository.

Project registry and `--project` / `--path` arrived in v0.2.

## Recommended Next Work From v0.1

These items became the v0.2 target:

- Add project/workspace management.
- Add `--project` and `--path` to existing commands.
- Improve TUI toward a project/session dashboard.
- Add `.gitattributes`.
- Add release notes and stronger docs for multi-agent handoff.