From an instrumented onboarding test (Claude Code session, 2026-08-26): the plugin installed cleanly at 10:31, but when the first Brain task ran at 10:36 the agent hit claude mcp list → "Needs authentication", had to read claude mcp --help twice to discover the login subcommand, ran claude mcp login plugin:byterover:byterover-brain, handed off to the browser, and abandoned the task once ("I cannot produce the brief yet — the sign-in step needs you") before the user returned ~2 minutes later with "signed in". Total: ~3.5 minutes of friction plus one dead-end response, on the very first Brain interaction.
Proposed fixes (in leverage order)
- Auth at install, not first use. The install flow should immediately trigger — or print verbatim — the per-tool login command. Install time is when the user is present and expecting setup; first tool use is when an agent is mid-task and blocks on them.
- Exact remediation in the skill. Add a first-run checklist to
skills/byterover-company-brain/SKILL.md: "If claude mcp list shows Needs authentication, run exactly claude mcp login plugin:byterover:byterover-brain, expect a browser window, then re-verify with claude mcp list." The agent burned two help-page reads discovering this on its own.
- Structured auth errors from the server. An unauthenticated
brain__query/brain__learn call should return an error object carrying the exact login command, so any agent self-remediates without mcp list spelunking.
- Device-code OAuth grant on
dev-mcp.byterover.dev for headless/CI contexts where a browser handoff is impossible.
Items 1–2 are one-sentence/one-block changes and remove most of the observed friction.
From an instrumented onboarding test (Claude Code session, 2026-08-26): the plugin installed cleanly at 10:31, but when the first Brain task ran at 10:36 the agent hit
claude mcp list→ "Needs authentication", had to readclaude mcp --helptwice to discover the login subcommand, ranclaude mcp login plugin:byterover:byterover-brain, handed off to the browser, and abandoned the task once ("I cannot produce the brief yet — the sign-in step needs you") before the user returned ~2 minutes later with "signed in". Total: ~3.5 minutes of friction plus one dead-end response, on the very first Brain interaction.Proposed fixes (in leverage order)
skills/byterover-company-brain/SKILL.md: "Ifclaude mcp listshows Needs authentication, run exactlyclaude mcp login plugin:byterover:byterover-brain, expect a browser window, then re-verify withclaude mcp list." The agent burned two help-page reads discovering this on its own.brain__query/brain__learncall should return an error object carrying the exact login command, so any agent self-remediates withoutmcp listspelunking.dev-mcp.byterover.devfor headless/CI contexts where a browser handoff is impossible.Items 1–2 are one-sentence/one-block changes and remove most of the observed friction.