Connect an agent in one flow: versions first, one approval, watcher included
Merged
JO
3d ago+279+279+012345678901234567890123456789-23-23-01234567890123456789
Companion to basecamp/bc3#13784, from Adrien's migration report on Bring your agents to Basecamp.
His setup hit four rough edges:
- His CLI was 0.11.0, which has neither
auth agent connectnorconnect. - His plugin was 0.7.2, so the legacy
basecamp-connectskill was removed before the new one existed. - He had to approve twice: Basecamp's instructions page connected over HTTP into
~/.basecamp-agent/credentials.json, which the CLI can't read, soauth agent connectconnected a second time. - The watcher came as a separate step.
bc3#13784 makes the instructions page CLI-first, and this PR makes the CLI side match it.
basecamp-connect skill
- Before anything: require CLI 0.13.0 or later, running
basecamp upgradewhen it's older. Remove the legacy skill: symlinks are deleted, a real directory only after asking. Removing it here is safe because the skill doing the removing is installed. - First-time setup:
- On a computer with no profiles,
auth statusanswers "no profiles are configured". The skill now treats that as a free profile, and never runsprofile createfor an agent, since that signs in a person. - If the instructions page left a
~/.basecamp-agent/credentials.json, the skill says before connecting that connecting replaces it, so the person approves once more. --operator <id>is named for non-personal agents.- New step 5: start the connector right after setup.
- On a computer with no profiles,
Doctor and the post-upgrade notice
- A plugin/CLI mismatch now names the side to move:
- plugin behind:
claude plugin update basecamp-cli@37signals, then restart Claude Code; - CLI behind:
basecamp upgrade; - plugin still under the old
basecamp@37signalskey, which the notice used to miss entirely:basecamp setup claude.
- plugin behind:
- Versions that are equal by semver (
v0.13.0,0.13.0) no longer count as a mismatch.
README
- New section "Connecting an agent to this computer": the version it needs,
basecamp connect setupand its scriptable steps, connecting once, and updating the plugin (then restarting) before removing an older skill.
Review
Two rounds of adversarial review, by separate Opus agents. One change came out of it: importing the old credentials file (piped jq into auth login --with-client-credentials) was tried and dropped. It broke on read-only agents, a missing jq and stale files, and it contradicted the skill's own credential rules.
Verification
- New harness tests for the mismatch hint and
PluginUpdateNotice: legacy key, plugin behind, semver-equal, dev build. Each failed against a stub of the old behavior before the change. bin/ciis green locally, including skill drift.- Not run: the connect skill evals (
make -C skill-evals eval-connect).
Not in this PR
- The Codex version check still says
basecamp setup codexin both directions. - The "no profiles are configured" error still points at
basecamp profile create.