basecamp-doctor · diff
git:20260831.76d3f2e to git:20260909.ac62cdf
5 added, 1 removed. Audit A to A.
---
name: basecamp-doctor
description: Diagnose Basecamp CLI, authentication, and agent-plugin health.
---
# Basecamp Doctor
Run the structured diagnostic:
```bash
basecamp doctor --json
```
Interpret every check by status:
- `pass`: working correctly.
- `warn`: usable, but follow-up is recommended.
- `skip`: not run because it is unauthenticated or not applicable.
- `fail`: broken and needs attention.
Report failures and warnings with their `hint` fields. Also inspect the top-level `breadcrumbs` array and preserve its structured `cmd` next steps, because a breadcrumb can provide a more specific action than a check hint. Use these common remediations when relevant:
- - Basecamp authentication: `basecamp auth login`
+ - Basecamp authentication: `basecamp auth login`. Guard a replacement login
+ with `--expect-identity <id>` so a browser signed in as someone else cannot
+ become the profile. A bot or CI profile that must never sign in interactively
+ imports a personal access token instead:
+ `op read "op://<vault>/<item>/credential" | basecamp auth login --with-token -P <profile> --account <id> --expect-identity <id>`
- Agent plugin installation or version: `basecamp setup agents` (honors `BASECAMP_SETUP_AGENT`)
- Codex plugin specifically: `basecamp setup codex`
- Claude Code plugin specifically: `basecamp setup claude`
Every remediation above runs without a terminal. Bare `basecamp setup` is the
human first-time flow and is **not** one of them: it opens browser OAuth and
refuses with a usage error in machine-output modes or unless stdin, stdout, and
stderr are all terminals. `basecamp setup --customize` additionally asks the user to
choose each default. Suggest either to a human at a terminal if useful, but
never run them yourself — use the subcommands above.
Do not read, print, or request credential files. If every check passes, say that Basecamp and its agent integration are ready.