Troubleshoot Brief in your coding agent

Start with one connection check

Run the check from the coding-agent session that will edit the repository. The result should name the exact repo, a usable connector, and a current or compatible pinned runtime.

Call brief.install_status with my current task. Confirm that the connector is ready, the repo root is this workspace, and the connector is fresh. Do not edit anything. If a check fails, give me the exact recovery action and stop.

• connector.status is ready, or the readiness result says update_available and remains usable for the active task.
• repo.root is the repository you intend to change—not a parent folder or another checkout.
• connector.fresh is true and the runtime identity is present.
• The team connection is available after sign-in; local repo work can still be diagnosed separately.

Brief does not appear in the agent

• Confirm the Brief MCP entry exists in the same coding agent you are using.
• If it is missing, rerun the setup command and select that agent.
• Quit and reopen the coding agent. Opening another chat is not always enough to reload MCP configuration.
• Open the target repository, then run the connection check again.

npx -y runbrief@stable setup

npx -y runbrief@stable setup --reconnect

Restart a stale or incompatible connector

A running connector is pinned for the active task. An update_available result can finish that task; an incompatible runtime or source mismatch requires recovery before repo-bound work continues.

Use Brief's connector recovery guidance. If restart is required, show me the confirmation string returned by Brief, then call brief.restart_connector with that exact confirmation. After the host reconnects, call brief.install_status again and verify the repo root and connector freshness before editing.

• Let the current task finish when the status is only update_available.
• For incompatible or source-mismatched states, use brief.restart_connector with the confirmation Brief returns.
• If the host does not reconnect automatically, reload or restart the coding agent once.
• Run brief.install_status again. Do not assume the restart selected the right repo.

Brief is connected to the wrong repository

• Stop before editing; a healthy connector pointed at the wrong repo is still unsafe.
• Open the intended repository as the coding agent's workspace or launch the agent from that repo root.
• Start a new session if the host captured its working directory at launch.
• Run brief.install_status with the real task and compare repo.root with the workspace path.

Do not make changes. Re-check Brief for this task and print the resolved repo.root. If it does not match the current workspace exactly, explain how this coding agent chooses its workspace and stop.

Sign in to the right team

• Run setup in each distinct laptop, SSH host, WSL instance, or container you use.
• When Brief opens browser authorization, sign in or create an account and approve the intended workspace.
• Return to the terminal and let setup complete before closing it.
• Run the connection check and confirm the team connection is available.

Collect a useful support report

Prepare a redacted Brief support report. Include the coding agent and version, operating system, install command without credentials, resolved repo root, connector status and freshness, runtime version, the failed tool name, and the exact error with secrets removed. Do not include source code, tokens, pairing codes, or raw credentials.

• Say what you expected, what happened, and whether it fails in a new session.
• Include the smallest safe reproduction and the recovery steps already tried.
• Rotate the connector credential if it appeared in a prompt, ticket, log, or committed file.