dotbabel

Migrating to v1.0

Last updated: v1.0.0

This guide covers the breaking changes introduced in @dotclaude/dotclaude v1.0. The changes are concentrated in the dotclaude handoff surface — a verb-rename redesign (#87) that locks the public CLI shape for v1 and beyond. Other surfaces (bootstrap, sync, doctor, index, validate-specs) are unchanged.

If you are on v0.11.0 or earlier, this is the only breaking change you need to follow. If you are on a 0.x branch older than 0.10, walk the intermediate CHANGELOG.md entries first — this guide assumes you already track the v0.10/0.11 surface.

TL;DR

Three things change:

The verb that fetches from the remote transport is now fetch, not pull.
The verb name pull now means render a local session (the new verb introduced for #87).
The --to <cli> flag is gone. The consumer CLI is implicit — it’s the one running the binary. --from <cli> is still around and is mandatory when the verb cannot infer the producing CLI from the input.

If your scripts call dotclaude handoff pull <id> --to claude, change them to dotclaude handoff fetch <id> and you are done.

Verb rename mapping

Per spec §6.5, every pre-v1 invocation has a one-line replacement:

Before (≤0.10.x)	After (v1.0)	Notes
`dotclaude handoff pull <id>`	`dotclaude handoff fetch <id>`	Remote fetch is now `fetch`; old `pull` was the same.
`dotclaude handoff pull <id> --to claude`	`dotclaude handoff fetch <id>`	`--to` is removed; consumer CLI is implicit.
`dotclaude handoff pull <id> --to copilot`	`dotclaude handoff fetch <id>` (run from Copilot)	Consumer CLI = the one running the binary.
`dotclaude handoff pull latest --to codex`	`dotclaude handoff fetch latest` (run from Codex)	`latest` semantics unchanged.
`dotclaude handoff push <id>`	`dotclaude handoff push <id>`	Unchanged when `<id>` is supplied.
`dotclaude handoff push --to <cli>`	`dotclaude handoff push --from <cli>`	`--to` is renamed to `--from` on push (and is the same).
`dotclaude handoff push` (no `<id>`)	`dotclaude handoff push --from <cli>`	`--from` is required when `<id>` is omitted.
(no equivalent in 0.x)	`dotclaude handoff pull <id>`	New: render a local session as `<handoff>` block.
(no equivalent in 0.x)	`dotclaude handoff pull <id> --summary`	New: render local session as inline summary markdown.
(no equivalent in 0.x)	`dotclaude handoff pull <id> -o <path\\|auto\\|->`	New: write rendered output to disk or stdout.

`--to` removal: rationale

In v0.x, --to <cli> selected the consumer CLI for fetch-and-render. This was redundant because the binary always ran inside one of the three supported CLIs (claude, copilot, codex), and that CLI is by definition the consumer. The flag survived as a no-op on the consumer side and as a synonym for --from on the push side, which was confusing.

In v1.0:

The consumer CLI is implicit — it is the one executing the binary. The next-step hint in the rendered <handoff> block adapts to the producer CLI (the one that wrote the session), not the consumer.
The producer CLI is explicit when needed: --from <cli> narrows resolution. It is mandatory on push when <id> is not given (because the binary cannot guess which local CLI’s “latest” session to push). It is optional everywhere else, where it acts as a disambiguator.

`--from` mandatory rule

--from <cli> is required only in one specific case:

# v1.0: required (no <id> means the binary needs to know which CLI's
# `latest` session to push)
dotclaude handoff push --from claude

It is optional on every other call:

# v1.0: optional — `latest` is host-scoped and resolves the most
# recently modified session across all three CLIs
dotclaude handoff fetch latest

# v1.0: optional but useful — narrows resolution to the codex root
# and produces a clearer "no codex session matches: <q>" error if the
# query is bogus
dotclaude handoff pull deadbeef --from codex

Omitting --from on push without <id> exits 64 with a usage hint:

$ dotclaude handoff push
dotclaude-handoff: push: --from required when no <query> is given
Usage: …

Local-render verbs (`pull`, new in v1.0)

pull <id> is the new local-render verb. It does not touch the remote transport. It renders a local session in one of three modes:

# Default: <handoff> block on stdout, ready to paste.
dotclaude handoff pull deadbeef

# --summary: inline markdown block (origin, short-uuid, cwd,
# timestamp), useful for chat handoff between agents.
dotclaude handoff pull deadbeef --summary

# -o <path>: write to a file. -o auto picks a default path under the
# current dir; -o - writes to stdout (same as default minus the
# stream-isolation niceties).
dotclaude handoff pull deadbeef -o handoff.md
dotclaude handoff pull deadbeef -o auto

For remote sessions, use fetch first, then pull:

dotclaude handoff fetch deadbeef     # downloads from transport
dotclaude handoff pull deadbeef      # renders the now-local session

Stream isolation (spec §5.5.1 OPS-2)

pull separates stream content per spec:

stdout: the <handoff> block, summary markdown, or -o-target path. Always machine-parseable.
stderr: progress messages (latest <cli> session: <short-uuid>, using --from <cli> override, …).

If you are scripting around pull and capturing the first line of output, redirect stderr to keep the capture clean — especially when running inside the Codex !-shell, which displays the interleaved combined stream:

# Robust: stdout-only capture
dotclaude handoff pull latest 2>/dev/null | head -1

Known surface gaps in v1.0

These are documented in the v1.0 release notes and will be revisited in a future minor release:

CP-1 — Copilot’s slash-handler strips --summary / -o. /handoff pull latest --summary exits 64 inside the Copilot CLI before the binary is invoked. Workaround: call the bare binary — !dotclaude handoff pull latest --summary — which bypasses Copilot’s slash parser. The Claude Code and Codex slash paths are unaffected.
CX-1 — Codex !-shell displays the interleaved combined stream. Stderr lines may appear before stdout when capturing the output visually. The streams themselves are correctly separated; this is a display-only artifact of the Codex shell wrapper. See the stream isolation section above for the redirect that works around it.

This site is open source. Improve this page.