relay-baton

Portable continuation infrastructure for coding agents.

Pass compressed coding state between Codex CLI, Claude Code, and whatever ships next — without re-pasting the chat log, the diff, or the repo.

English · 한국어 · 日本語 · 简体中文 · 繁體中文 · Español · Français · Deutsch · Português · Русский

# Codex hits a quota wall mid-task. relay-baton notices, builds a compact
# handoff from the repository's actual state, and resumes the work in Claude.
$ relay-baton run "refactor the upload pipeline" --diet caveman
● relay chain: codex → claude

Starting with codex  (hop 1/2)
→ codex exec --sandbox workspace-write "refactor the upload pipeline"
▲ codex hit a limit — fallback pattern detected: "rate limit exceeded"
→ building a compact handoff for claude…
✓ handoff ready — passing the baton: codex → claude
✓ claude finished the task.
  ↳ see what changed: relay-baton review · session state: relay-baton status

Download

Prebuilt, single-file executables are attached to every release — no Node install required to run them.

One-line CLI install (verifies SHA256SUMS, no admin required):

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/dgl1231/relay-baton/main/install/install.sh | sh

# Windows PowerShell
iwr https://raw.githubusercontent.com/dgl1231/relay-baton/main/install/install.ps1 -UseB | iex

OS	Binary	Get it
macOS (Apple Silicon)	`relay-baton-macos-arm64`	Latest release
Linux (x64)	`relay-baton-linux-x64`	Latest release
Windows (x64)	`relay-baton-windows-x64.exe`	Latest release

# macOS / Linux
chmod +x relay-baton-macos-arm64
./relay-baton-macos-arm64 --version

# Windows
.\relay-baton-windows-x64.exe --version

Via npm (needs Node ≥ 20):

npm i -g @relay-baton/cli      # installs the `relay-baton` command
npx @relay-baton/cli doctor    # or one-off without installing

Via a package manager — manifests live in homebrew/, scoop/, and winget/. Each folder's README has the publish steps (Homebrew needs a tap repo, Scoop a bucket repo, Winget a PR to microsoft/winget-pkgs):

brew tap dgl1231/relay-baton &amp;&amp; brew install relay-baton          # macOS / Linux
scoop bucket add relay-baton https://github.com/dgl1231/scoop-relay-baton; scoop install relay-baton  # Windows
winget install dgl1231.relay-baton                                # Windows (after the winget-pkgs PR lands)

Desktop app (Tauri shell over the same CLI — see desktop/):

OS	Installer	Get it
macOS (Apple Silicon)	`relay-baton_…_aarch64.dmg`	Latest release
Linux (x64)	`relay-baton_…_amd64.AppImage`	Latest release
Windows (x64)	`relay-baton_…_x64-setup.exe`	Latest release

> Desktop installers are signed/notarized only when release signing secrets are > configured. Unsigned fallback builds still ship, so expect Gatekeeper / > SmartScreen prompts on unsigned releases. SHA256SUMS is attached to new > releases for CLI installer verification. > Desktop update checks are opt-in and manual. Signed updater artifacts and > latest.json are published only when Tauri updater signing secrets are > configured for a release. > > Older versions: pick any tag on the releases page. Prefer to build from source instead? See Install below.

Why this exists

AI coding work is fragmenting across tools. A real session looks like this:

Codex CLI for one batch of edits.
Claude Code for another.
A laptop in the morning, a different machine in the evening.
A context window that fills up, falls over, or quietly truncates.

The default way to move work between agents today is copy-paste the chat log — or worse, the whole repo dumped into a prompt. That approach has three problems:

Tokens. Chat logs are mostly noise. You pay for that noise every turn.
Continuity. The next agent doesn't get intent; it gets transcripts.
Fragility. One missed file, one stale diff, and the agent restarts from a wrong premise.

relay-baton is a local harness that sits underneath the agents and carries the minimum sufficient state across the handoff: a compact summary, a repo map, and file references — not a transcript.

> Spend as few tokens as possible while merging Codex CLI and Claude Code CLI into a single workflow. > > When one agent hits a quota / context limit, the next one resumes from the exact repository state — without re-pasting the whole log, diff, or repo.

The idea

┌─────────┐   ┌──────────────┐   ┌──────────────┐   ┌────────┐
│ Codex   │ → │ Fallback     │ → │ Token Diet   │ → │ Claude │
│ exec    │   │ Detector     │   │ Handoff      │   │ Code   │
└─────────┘   └──────────────┘   └──────────────┘   └────────┘
                        ↓                ↓
                  .ai-session/handoff.md, compact-state.md,
                  repo-map.md, full-diff.patch, commands.log

A baton-pass for coding agents:

Detect when the current agent stops being useful (quota, context, rate, errors).
Capture what matters — repo state, changed files, decisions, next step.
Compact it under a budget the next agent can actually consume.
Hand off with quality gates so the receiver isn't fed broken context.

The handoff is a small file (.ai-session/handoff.md) plus references. Everything heavy — the full diff, the full log, the full repo map — stays on disk and is loaded on demand.

Workflow

$ relay-baton init                  # create .ai-session/ in the current repo
$ relay-baton doctor                # check git, codex, claude, env, config

$ relay-baton run "fix flaky upload test" --diet balanced
● relay chain: codex → claude

Starting with codex  (hop 1/2)
→ codex exec --sandbox workspace-write "fix flaky upload test"
... codex output streams here ...
▲ codex hit a limit — fallback pattern detected: "maximum context length"
→ building a compact handoff for claude…
✓ handoff ready — passing the baton: codex → claude

Continuing with claude  (hop 2/2)
→ claude --permission-mode acceptEdits -p ""
... claude resumes, edits files, finishes ...

$ relay-baton status                # what state is the session in?
$ relay-baton budget                # how much of the diet budget did we use?

Manual handoff, no auto-fallback:

$ relay-baton handoff --to claude --no-run --diet caveman

Across multiple repos:

$ relay-baton project add /path/to/repo-a --diet caveman
$ relay-baton project add /path/to/repo-b --diet balanced
$ relay-baton project switch repo-b
$ relay-baton run "wire up the new metrics endpoint"

Plan-execute mode

A proactive alternative to reactive fallback: have a planner write a structured plan, gate it for completeness, then have an executor implement it.

# 1) Planner (default: Claude) writes .ai-session/plan.md, gated by PlanQualityGate.
$ relay-baton plan "add rate limiting to the upload endpoint" --with claude

# 2) Inspect / edit the plan if you want.
$ cat .ai-session/plan.md

# 3) Executor (default: Codex) implements the plan.
$ relay-baton execute --with codex

# Or do both in one shot once the plan passes its gate:
$ relay-baton plan "add rate limiting" --then-execute

# Scaffold an empty plan template without launching an agent:
$ relay-baton plan "explore options" --no-run

Context-compression mode

Deterministic mid-session compaction of state.md / commands.log so an agent runs longer before hitting a context wall. No model call, fully reversible (raw artifacts are rotated to commands.log.full.).

# See what would change without writing anything.
$ relay-baton compress-context --dry-run

# Compress when weight/budget exceeds the threshold (default 0.8).
$ relay-baton compress-context --threshold 0.8

# Force compression regardless of threshold.
$ relay-baton compress-context --force

Verify the harness (no model calls)

# Simulated end-to-end check: resolution, fallback detection, handoff no-run,
# token budget, API-key env block. Exits non-zero on failure.
$ relay-baton verify

# Extended environment diagnostics (OK/WARN/FAIL checklist).
$ relay-baton doctor --deep

Neither verify nor doctor --deep makes any network or model call, and verify writes nothing into your repo (it uses a throwaway temp dir).

Quick start

Fastest path (no clone, no build). The package is @relay-baton/cli; the command it installs is relay-baton:

npm i -g @relay-baton/cli       # installs the `relay-baton` command
relay-baton doctor              # check codex/claude + environment
relay-baton login               # log in to both CLIs
relay-baton run "Fix the mail attachment upload flow" --diet balanced
# one-off without installing: npx @relay-baton/cli doctor

From source (for development):

# 1) Install &amp; build
pnpm install
pnpm build

# 2) Log in to both CLIs in one go
pnpm relay-baton login

# 3) Sanity check
pnpm relay-baton doctor

# 4) Start a task on Codex; auto-handoff to Claude on quota/context limit
pnpm relay-baton run "Fix the mail attachment upload flow" --diet balanced

> pnpm relay-baton is an alias for node packages/cli/dist/index.js. For a global binary, link it with pnpm -F @relay-baton/cli link --global (optional). Published as @relay-baton/cli, so npm i -g @relay-baton/cli (command: relay-baton) or npx @relay-baton/cli works without a build.

One-line install via an agent

install/install.md is both a human install guide and an instruction surface that coding agents can execute as-is:

# Codex CLI
codex exec --sandbox workspace-write "Read https://github.com/dgl1231/relay-baton/blob/main/install/install.md and install relay-baton on this machine. Do not print or store API keys. Finish by running 'pnpm relay-baton doctor'."

# Claude Code (headless)
claude --permission-mode acceptEdits -p "Read https://github.com/dgl1231/relay-baton/blob/main/install/install.md and follow it step by step. Do not print or store API keys. End by running 'pnpm relay-baton doctor'."

Features

Automatic fallback. Detects quota exceeded, rate limit exceeded, maximum context length and similar in agent output and hands off to the fallback agent. False-positive guards skip grep results and prose about the patterns themselves.
Token diet. Five deterministic compaction profiles (off · lite · balanced · caveman · ultra). Lock files, build output, minified bundles, and binary blobs are excluded; logs are tailed; repo maps replace source.
Plan-execute mode. A proactive alternative to reactive fallback: a planner agent (default Claude) writes a structured .ai-session/plan.md, gated for completeness, then an executor agent (default Codex) implements it. relay-baton plan "" --then-execute.
Context compression. Proactive, deterministic mid-session compression of state.md / commands.log so an agent runs longer before hitting a context wall. relay-baton compress-context, plus an auto-pass inside run.
Quality gates. A handoff is verified before the fallback agent is launched — required sections present, budget respected, no inlined manifests.
Auth-safe by default. OPENAI_API_KEY / ANTHROPIC_API_KEY are stripped from child processes. Opt-in only via --allow-api-key-env. No keys are ever stored, printed, or logged.
Project registry. Register multiple repos once, switch the active project, run commands against any of them with --project or --path.
Ink TUI. Project / session dashboard with diet cycling, budget refresh, and no-run handoff generation. Never launches agents.
No API of its own. relay-baton never calls the OpenAI / Anthropic API directly. It only spawns the local codex / claude CLIs as subprocesses.

Architecture

packages/
  shared/    # types, constants
  core/      # UI-independent business logic
    agents/        # AgentAdapter, CodexAdapter, ClaudeCodeAdapter, FallbackDetector
    git/           # GitService, RepoMapGenerator
    session/       # SessionManager (.ai-session/ lifecycle)
    token-diet/    # BudgetManager, DiffCompactor, LogCompactor, HandoffCompactor, ...
    handoff/       # HandoffGenerator, HandoffQualityGate, TokenDietQualityGate, PromptBuilder
    workflow/      # BatonWorkflow — the orchestration
    projects/      # ProjectRegistry, ProjectManager, ProjectResolver
  cli/       # commander entrypoints — thin shells over core
  tui/       # Ink dashboard — read-only over core

Design rules:

core knows nothing about UI.
cli and tui hold no business logic — they wire user input to core.
Each agent is an AgentAdapter. Adding opencode, gemini, aider means adding an adapter, not patching core.
Everything written to disk lives under .ai-session/. relay-baton never edits your source files.

Usage

Single-repository flow:

relay-baton init
relay-baton doctor
relay-baton run "Fix the failing upload flow" --diet balanced
relay-baton status
relay-baton budget

Generate a handoff without launching the next agent:

relay-baton handoff --to claude --no-run --diet caveman

relay-baton project add /path/to/relay-baton --name relay-baton --diet caveman --primary codex --fallback claude
relay-baton project list
relay-baton project switch relay-baton
relay-baton status --project relay-baton
relay-baton handoff --to claude --no-run --project relay-baton --diet caveman

Direct path without registering:

relay-baton status --path /path/to/repo
relay-baton budget --path /path/to/repo

Open the TUI dashboard:

relay-baton tui --project relay-baton

Commands

Command	Description
`relay-baton init`	Create `.ai-session/` in the current repo
`relay-baton doctor`	Check git / codex / claude / env / config (`--deep` for extended diagnostics)
`relay-baton verify`	Simulated end-to-end check — no real model calls (`--diet`, `--verbose`, `--keep-temp`)
`relay-baton login [agent]`	Run Codex / Claude auth flows (`codex` / `claude` / `all`)
`relay-baton run ""`	Run primary agent, detect fallback, hand off
`relay-baton route ""`	Preview the advisory routing hint (read-only, `--json`)
`relay-baton handoff --to claude`	Manual handoff (`--diet`, `--no-run`, `--force`)
`relay-baton handoff history`	List the current + backed-up handoff documents (metadata only)
`relay-baton plan ""`	Plan-execute mode: planner writes `plan.md` (`--with`, `--no-run`, `--then-execute`)
`relay-baton execute`	Plan-execute mode: executor implements `plan.md` (`--with`, `--from`)
`relay-baton review`	Deterministically review the diff against `plan.md` Steps — no model call (`--json`)
`relay-baton receipt done/skip/list`	Append-only execution receipts for plan steps (`--note`, `--json`)
`relay-baton compact` / `squeeze`	Rebuild compact-state, repo-map, full-diff
`relay-baton compress-context`	Compress running state.md / commands.log when over budget (`--dry-run`, `--threshold`)
`relay-baton budget`	Show context-budget usage

Project-aware commands accept --project and --path .

Resolution priority: --path > --project > active project > current working directory. compress stays cwd-based — it's a file-level utility.

Project registry

Projects are stored at ~/.relay-baton/projects.json. Set RELAY_BATON_PROJECTS_FILE to use a different path (CI, sandboxing, tests).

relay-baton project add /path/to/relay-baton --name relay-baton --diet caveman --primary codex --fallback claude
relay-baton project list
relay-baton project switch relay-baton

project add requires the path to exist and be a directory. It may be a plain, non-git project folder; git-backed commands such as run and handoff still require a git repository when executed. Duplicate paths are not added twice. A corrupt projects.json is backed up to projects.json.corrupt-.bak and reset to an empty registry — commands keep working. Read-only commands (status, budget, doctor) do not write the registry; only run and handoff update lastUsedAt.

Handoff flow

relay-baton run "..." spawns the primary CLI as a subprocess.
stdout / stderr stream live and append to .ai-session/commands.log.
Output is scanned for fallback phrases. Grep-style result lines and prose explaining the patterns are skipped to avoid false positives.
On fallback, relay-baton collects git state, builds a repo map, compacts the state, and writes the handoff document.
HandoffQualityGate + TokenDietQualityGate run before the fallback agent launches.
The fallback agent resumes from .ai-session/handoff.md and the referenced files.

Token diet

Principles:

Don't paste the whole thing.
Prefer log tail + known errors over raw logs.
Prefer repo map over full source.
Prefer focused diff (lock / build / *.min.js excluded) over full diff.
Delegate large content to file references.

Profiles

Profile	Intent	Notes
`off`	Minimal truncation	Mostly pass-through
`lite`	Light cleanup	Strip blank lines, duplicate instructions
`balanced` (default)	Day-to-day	Compact state + diff summary + log tail + repo map
`caveman`	Aggressive minimal	Short direct bullets; no full diff/log inline
`ultra`	Extreme	Almost everything via reference

> caveman is not a silly tone — it means aggressive minimal-context. Technical accuracy is preserved.

`.ai-session/` files

File	Role
`task.md`	The user's task
`state.md`	Current state (Goal / Done / In Progress / Remaining / Decisions / Risks / Next Step)
`compact-state.md`	Deterministic compaction of `state.md`
`handoff.md`	Handoff document for the next agent
`decisions.md`	Decision log
`changed-files.md`	List of changed files
`repo-map.md`	Directory tree + key files
`commands.log`	Codex / Claude execution log (append-only)
`errors.md`	Error notes
`test-results.md`	Test / build results
`full-diff.patch`	`git diff HEAD` snapshot
`context-budget.json`	Token-diet usage snapshot
`session.json`	Session metadata

Configuration — `relay-baton.config.json`

{
  "primaryAgent": "codex",
  "fallbackAgent": "claude",
  "agents": {
    "codex":  { "command": "codex",  "args": ["exec", "--sandbox", "workspace-write"] },
    "claude": { "command": "claude", "args": ["--permission-mode", "acceptEdits", "-p"] }
  },
  "fallbackPatterns": [
    "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"
  ],
  "authPolicy": {
    "mode": "cli-session",
    "allowApiKeyEnv": false,
    "warnIfApiKeyEnvDetected": true,
    "blockedEnvVars": ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"]
  },
  "tokenDiet": {
    "enabled": true,
    "profile": "balanced",
    "outputCompression": true
  },
  "handoffTriggers": {
    "budgetRatio": 0.8,
    "changedFiles": 30,
    "usageTokensProxy": 100000
  }
}

If no config file exists, defaults are used. handoffTriggers (v1.2.0) is optional — when any threshold is reached after a clean agent exit, run suggests handing off to the next agent (y/N confirm, or --yes); leave it out to keep detection error-pattern-only. Other optional blocks: guardrails (stop-condition caps for guard/--until) and hooks (preHandoff/postExecute local commands) — see docs/COMMANDS.md.

TUI

relay-baton tui opens an Ink dashboard for the active project, or relay-baton tui --project for a specific one.

Sidebar: active project, registered projects, selected diet, primary / fallback agents, key hints.
Main panels: task, session status, active agent, fallback reason, repo path, changed files, compact-state preview, token budget, log tail, recent errors.
Keys: q quit · r refresh · p next project · d cycle diet (in memory) · b reload budget · h generate handoff with no agent run.

The TUI never launches Codex or Claude. It reads session files and can generate a no-run handoff.

Quality gates

Handoff Quality Gate — runs before fallback launch:

Required files exist and are non-empty.
handoff.md contains the sections Goal, Previous Agent, Next Agent, Changed Files, Known Errors, Next Steps.
Fails the launch if anything is missing. --force overrides.

Token Diet Quality Gate:

handoff.md ≤ maxHandoffChars for the active profile.
Token Diet Summary section present.
Truncate marker present when content was actually truncated.
commands.log / AGENTS.md / CLAUDE.md bodies must not be inlined.
For caveman / ultra, the Important Diff block stays within maxDiffChars.

Auth & safety

Never stores, prints, or logs API keys.
OPENAI_API_KEY / ANTHROPIC_API_KEY stripped from child processes by default.
Only --allow-api-key-env or authPolicy.allowApiKeyEnv: true lets them through.
doctor reports whether each variable is set — but never prints its value.
Refuses to run run / handoff outside a git repo.
Backs up an existing handoff.md with a timestamp suffix.
commands.log is append-only.
relay-baton never modifies your source files directly — only .ai-session/.
compress does not overwrite the input file unless --write is passed.

vs the alternatives

Approach	What carries over	Token cost	Continuity	Failure mode
Raw chat export	Entire transcript	High (most of it is noise)	Brittle — agent re-reads its own thinking	Context window overflow
Copy-paste prompting	What the human remembered	Variable	Fragile — depends on memory	Silent drift from real state
Whole-repo dump	Everything	Very high	Strong but expensive	Truncated mid-file by the model
relay-baton	Compact summary + repo map + file references	Low, bounded by profile	Strong — driven by actual repo state	Fails loudly via quality gates

Philosophy

relay-baton is small sharp tooling for AI-native development workflows.

Local-first. Everything lives on your disk. No cloud, no daemon, no telemetry, no account.
Composability. A .ai-session/ directory is just files. Read them, grep them, diff them, ship them in a PR.
Lightweight state transfer. A handoff is a markdown file, not a database.
Deterministic over clever. No LLM-driven summarization in the harness itself — if the model gets summarization wrong, the handoff lies. relay-baton uses character budgets, structural rules, and explicit references.
Repo state is the source of truth. The conversation is interpretation; the repo is fact.
Token efficiency is the feature, not a knob hidden in a menu. Every design decision is measured against "does this bloat the handoff?"

Design principles

It's work handoff, not chat relay.
The current repository state beats any conversation history.
The handoff must be readable by a human.
Every UI is just a thin shell over core.
Token diet is not a side feature — it's the core feature.

Demo

> GIF / asciinema recording placeholder — coming with v0.4. > > A 30-second clip will show a Codex run hitting a quota wall, relay-baton emitting a compact handoff, and Claude Code resuming the task from the exact same repo state.

Requirements

Item	Version / Note
Node.js	≥ 20
pnpm	≥ 9
git	required
`codex`	primary agent — ChatGPT Plus or higher subscription required
`claude`	fallback agent — Claude Pro or higher subscription required

> ### Subscription notice > > relay-baton never calls the OpenAI / Anthropic API directly. It uses the subscription auth of the local codex / claude CLIs. > > - Codex CLI — sign in with ChatGPT Plus / Pro / Team / Enterprise. > - Claude Code CLI — sign in with Anthropic Claude Pro / Max / Team / Enterprise. > - Free-tier accounts will not work reliably for either CLI. > - API-key auth is technically possible but blocked by default behind --allow-api-key-env, to prevent accidental usage-based billing.

Default agent invocations:

Codex: codex exec --sandbox workspace-write ""
Claude Code: claude --permission-mode acceptEdits -p ""

--full-auto, --ask-for-approval, and bypassPermissions are intentionally not used (deprecated / unsupported / unsafe). Power users can override agents..args in relay-baton.config.json.

Logging in

relay-baton login launches each CLI's native auth flow.

relay-baton login           # both
relay-baton login codex     # codex only
relay-baton login claude    # claude only

Under the hood:

Codex → runs codex login. Complete browser auth and you return automatically.
Claude → opens an interactive claude session. Type /login, complete browser auth, then /exit.

claude --version succeeding does not mean you're logged in. If you see "Not logged in", re-run the command above.

> relay-baton does not store, print, or log credentials during the auth process. All credentials are managed by each CLI itself.

Limitations (MVP)

No LLM / tokenizer calls of its own — runs on character budgets.
No semantic summarization — deterministic compaction only.
Agent adapters: Codex / Claude only.
TUI does not run agents; v0.2+ allows no-run handoff generation only.

Future direction

relay-baton starts as a two-agent fallback harness. The same primitive scales further:

Multi-agent relay chains. Codex → Claude → OpenCode → back to Codex, each leg carrying a compact handoff.
Branching session trees. Fork a task into parallel agent attempts; reconcile via diffs.
Remote relay state. Push .ai-session/ to a shared remote so the next machine picks up where the last one stopped.
Orchestrated workflows. review, diagnose, continue modes — bounded autopilot loops with explicit checkpoints.
More adapters. OpenCode, Gemini CLI, Aider, anything else with a sane local subprocess interface.

The harness stays the same shape: detect, capture, compact, hand off.

Roadmap

The full roadmap lives in docs/ROADMAP.md:

v0.6 — Trust & Verify: verify, doctor --deep, TUI mode panel.
v0.7 — Review & Diagnose: review, plan execution receipts, plan diffing, --json outputs, conversation event schema.
v0.8 — Adapter Expansion + Agent Room (first cut): OpenCode / Gemini / Aider adapter scaffolds, project-level fallback overrides, OS CI matrix, and relay-baton chat/room (turn-based, confirmation-first REPL).
v0.9 — Automation & Runtime (current): bounded multi-turn loop (LoopController), /continue --max-steps N, /replan, session replay, adaptive per-agent compression thresholds.
v1.0 — Stable Local Release: frozen schema, full command reference, i18n parity.

Future: Agent Room / Conversation Mode

A planned direction (first cut in v0.8) to turn relay-baton into an interactive multi-agent workspace: talk to Claude and Codex by turns in one session, with per-agent messages clearly distinguished — Claude as planner/reviewer, Codex as executor. It keeps every existing safety rail (subprocess-only, no API keys, no auto commit/push/PR, confirmation-first with a prompt preview before any real run). Design only for now — not implemented yet. Full design: docs/AGENT_ROOM.md.

Documentation

docs/GUIDE.md — consolidated guide: install, quickstart, desktop/CLI workflows, safety (한국어)
docs/COMMANDS.md — full command reference (한국어)
docs/ARTIFACTS.md — .ai-session/ artifact stability contract (v1.0)
docs/AGENT_ROOM.md — Agent Room design
docs/ROADMAP.md — roadmap
docs/RELEASE.md — release & distribution runbook (how the per-OS binaries are built/shipped)
docs/HANDOFF.md — session handoff / current state (start here in a new session)

Release notes

Detailed notes live in release-notes/ (index). They are user-facing changelogs, not agent handoff material — that role belongs to .ai-session/handoff.md.

Latest: v1.6.1 — English · 한국어 · full history in CHANGELOG.md

> relay-baton reached general availability at v1.0.0 (MIT, published to npm / > Homebrew / Scoop / Winget). Pre-1.0 tags below used a perpetual -alpha.N > line; see CHANGELOG.md for the consolidated history.

Version	English	한국어	One-line summary
v1.6.1	Read →	읽기 →	One-click Windows install: NSIS setup skips the wizard pages (Welcome/Choose-Location) — double-click installs straight to a branded finish screen.
v1.6.0	Read →	읽기 →	Modern Windows installer: brand-styled NSIS `…-setup.exe`, per-user install, no UAC (replaces the MSI wizard).
v1.5.1	Read →	읽기 →	Honest run endings (failed chain exits `4` → red desktop chip) & quieter live card (claude `rate_limit_event` suppressed).
v1.5.0	Read →	읽기 →	Run agents from the desktop app, confirmation-first: `/run` + Run-here on plan/execute/handoff, live streaming card with cancel.
v1.4.1	Read →	읽기 →	Desktop timeline polish: result cards survive reloads; role-coded rows (user/relay-baton/agents) in both themes.
v1.4.0	Read →	읽기 →	Friendly agent stream (`--pretty` on run/plan/execute/handoff: structured JSONL → readable lines + token/cost receipt) & desktop Agent Room result cards.
v1.3.1	Read →

Smoke test

After any change:

pnpm build
pnpm test
pnpm relay-baton doctor
pnpm relay-baton project add /path/to/relay-baton --name relay-baton --diet caveman
pnpm relay-baton status --project relay-baton
pnpm relay-baton handoff --to claude --no-run --project relay-baton --diet caveman
pnpm relay-baton budget

Contributing

Issues and PRs welcome. For larger changes, open a short RFC issue first.

git clone https://github.com/dgl1231/relay-baton
cd relay-baton
pnpm install
pnpm build
pnpm test

License

MIT. See LICENSE.

Translations · 한국어 · 日本語 · 简体中文 · 繁體中文 · Español · Français · Deutsch · Português · Русский

relay-baton DongGeon Lee

README