# relay-baton v0.2.0 Release Notes

Date: 2026-05-27

## Summary

v0.2.0 adds a project/workspace layer and a more practical Ink TUI dashboard.

This release makes relay-baton easier to use across multiple repositories. Users can register projects once, switch the active project, and run handoff/status/budget commands without manually changing directories every time.

## Major Changes

### Project Registry

Added a local project registry at:

```text
~/.relay-baton/projects.json
```

The registry stores multiple repositories so relay-baton can switch between them without requiring the user to start every command from the target repo directory.

Project shape:

```ts
interface BatonProject {
  id: string;
  name: string;
  path: string;
  createdAt: string;
  updatedAt: string;
  lastUsedAt?: string;
  defaultDiet?: "off" | "lite" | "balanced" | "caveman" | "ultra";
  primaryAgent?: "codex" | "claude" | "opencode" | "gemini" | "aider";
  fallbackAgent?: "codex" | "claude" | "opencode" | "gemini" | "aider";
}
```

Core modules added:

- `packages/core/src/projects/ProjectRegistry.ts`
- `packages/core/src/projects/ProjectManager.ts`
- `packages/core/src/projects/ProjectResolver.ts`

Responsibilities:

- `ProjectRegistry`: read/write `projects.json`, create it when missing, reject invalid JSON/shape, prevent duplicate ids/paths.
- `ProjectManager`: add, remove, list, switch, resolve, and update last-used timestamps.
- `ProjectResolver`: choose the effective repo root from CLI options, active project, or cwd.

### Project CLI Commands

Added:

```bash
relay-baton project add <path> --name <name> --diet <profile> --primary <agent> --fallback <agent>
relay-baton project list
relay-baton project switch <name-or-id>
relay-baton project current
relay-baton project remove <name-or-id>
relay-baton project doctor
```

Behavior:

- `project add` requires the path to exist.
- `project add` requires the path to be a git repository.
- Duplicate paths are reported and not added twice.
- Missing `--name` defaults to the folder name.
- Project id is generated from the project name as a slug.
- Removing the active project clears `activeProjectId`.

### Project-Aware Existing Commands

Added shared project resolution to:

- `init`
- `doctor`
- `status`
- `run`
- `handoff`
- `compact`
- `squeeze`
- `budget`
- `tui`

Common options:

```bash
--project <name-or-id>
--path <repoPath>
```

Resolution priority:

```text
--path > --project > active project > cwd
```

Important compatibility note:

- If no project is registered, commands still behave like v0.1 and use `process.cwd()`.
- `compress <file>` remains cwd-based in v0.2 because it is a file-level utility.

Diet behavior:

- `run`, `compact`, and `handoff` use explicit `--diet` first.
- If `--diet` is omitted and a project is resolved, the project `defaultDiet` is used.
- If neither is available, config/default token diet is used.

### TUI Dashboard

The Ink TUI was changed from a mostly read-only session view into a project/session dashboard.

New component layout:

- `packages/tui/src/components/Sidebar.tsx`
- `packages/tui/src/components/SessionPanel.tsx`
- `packages/tui/src/components/ChangedFilesPanel.tsx`
- `packages/tui/src/components/BudgetPanel.tsx`
- `packages/tui/src/components/LogTailPanel.tsx`
- `packages/tui/src/components/StatusBar.tsx`

Dashboard content:

- Active project
- Registered projects
- Selected diet profile
- Primary/fallback agents
- Session task/status/active agent/fallback reason
- Repo path
- Changed files snapshot
- Compact state preview
- Token budget summary
- `commands.log` tail
- Recent errors

Supported keys:

- `q`: quit
- `r`: reload current project/session files
- `p`: switch to the next registered project
- `d`: cycle diet profile in memory only
- `b`: refresh displayed budget/session files
- `h`: generate handoff in no-run mode

The `h` key generates a fresh `.ai-session/handoff.md` for the selected project and diet profile.

### Line Ending Policy

Added `.gitattributes`:

```text
* text=auto
*.md text eol=lf
*.ts text eol=lf
*.tsx text eol=lf
*.json text eol=lf
*.yml text eol=lf
*.yaml text eol=lf
*.ps1 text eol=crlf
```

This sets the expected line-ending policy for future edits.

### Documentation

Updated:

- `README.md`
- `AGENTS.md`
- `CLAUDE.md`
- `.claude/skills/relay-baton-harness/SKILL.md`

Documentation now covers:

- Project management
- Project-aware command options
- TUI v0.2 dashboard behavior
- Planned mode design
- Codex default invocation: `codex exec --sandbox workspace-write "<task>"`
- Claude default invocation: `claude --permission-mode acceptEdits -p "<prompt>"`
- Codex and Claude default command examples
- Claude login guidance

## Compatibility Notes

Existing v0.1 usage still works:

```bash
relay-baton doctor
relay-baton status
relay-baton run "task"
relay-baton handoff --to claude --no-run
relay-baton budget
```

If no active project exists, commands fall back to cwd.

## Recommended Next Work

Good v0.3 candidates:

- Fuzzy project switcher in TUI.
- Project-specific session list and recent handoff history.
- CLI smoke tests for `project` commands.
- Better registry recovery: backup invalid `projects.json` before rewriting.
- TUI command palette.
- Additional agent adapter scaffolding.
- Review and diagnose modes.