Device enrollment walkthrough
Check the shared connection before adding another native agent.
Open this resource →Claude Code handbook
Connect the team to Claude Code
Install the Betterloop plugin, retain native account access, and inspect the controls available through supported Claude Code hooks.
Your Claude Code account and permissions remain native. The Betterloop plugin brings reviewed resources and configuration to supported events in your sessions.
01 / Claude Code handbook
Establish the connection in an assigned repository
Check Node.js 22 or later and npm. Obtain your personal enrollment command. Confirm the approved setup distribution with the administrator.
An installed Claude Code copy is reused. Setup asks before installing a missing copy. This connection has no Mimir dependency.
npx @betterloop/setup setup --harness claude-codeSign in through Claude Code itself. The provider account remains separate from Betterloop team enrollment. Betterloop does not import native credential files.
The Betterloop-owned plugin uses user scope. Repository sessions can therefore use the existing device connection without repeated repository enrollment.
Open a new Claude Code session in an assigned working repository. Reload the plugin if the host supports reload. Inspect that same repository with doctor.
npx @betterloop/setup doctor --harness claude-code --project /path/to/repositoryCheck what has actually happened
Read native authentication and installation first. Inspect the signed cache next. Then read activation and the support result for every required control.
An installed plugin may still await activation. A supported hook invocation must occur. Native managed settings can prevent either installation or execution.
Record any host restriction before requesting help. The presence of plugin files does not establish that the plugin has handled a real session event.
02 / Claude Code handbook
Match a rule to its execution event
A trusted enabled hook can evaluate supported tool actions. The available checks depend on action type, lifecycle event, catalog version, and installed Claude Code version.
Tool permissions are evaluated at covered tool-call events. Shell program restrictions apply to literal approved programs before covered Bash actions.
Supported quoting is accepted. Ambiguous shell syntax is rejected. An approved executable can still launch other code. Its approval is not a process sandbox.
An existing shell session or hosted tool is outside this gate. Identify the actual invocation path before attributing an action to a policy check.
rg -g '*.md' docs
rg -n "params|searchParams" src/appMake distinct supported tool calls when a task would otherwise require chained programs. Changing punctuation does not make ambiguous shell syntax supported.
Check the model-selection route
With Claude Code 2.1.251 or later, PreModelSwitch can reject explicit switches to unapproved models. The Betterloop plugin must be enabled.
Startup, resume, automatic fallback, and subagent model selection need native managed model settings. The adapter does not integrate maximum reasoning limits.
Ask the administrator to inspect those managed settings when the requirement covers every model-selection route. Explicit switch coverage alone cannot satisfy that wider requirement.
Read skills as reviewed instructions
A skill supplies guidance to the agent. The skill’s approval does not establish that the model followed it. Unmanaged local skills can remain discoverable.
Diagnostics count detectable unmanaged sources. Their paths and content are not uploaded. This count remains client evidence rather than independent device attestation.
03 / Claude Code handbook
Use this control checklist
| Configured control | Claude Code interpretation |
|---|---|
| Allowed tools | A supported tool event needs an enabled trusted hook before the conditional check can run. |
| Allowed shell programs | The gate evaluates literal programs and rejects ambiguous syntax. Approval cannot prevent a permitted program from launching code. |
| Approved models | Explicit unapproved switches can be rejected with the enabled plugin on Claude Code 2.1.251 or later. |
| Maximum reasoning level | This adapter does not integrate a check for this setting. |
| Approved skills | Reviewed guidance remains advisory. Other locally discoverable skills are not excluded. |
| Resource usage | Setup 0.8.0 supports conditional reporting of skill names, MCP server names, and subagent names. |
Use native managed model settings for startup, resumed sessions, fallback, and subagents. Check the actual deployed combination before declaring a mandatory control satisfied.
Host hook failures and timeouts can permit execution. Ordinary self-service hooks have incomplete execution coverage. Record those conditions in the rollout assessment.
04 / Claude Code handbook
Select an additional reviewed resource
After device setup, inspect the connected catalog. Your organization approves particular resource versions. Team-required selections remain part of the reviewed configuration.
betterloop library list
betterloop library show org.review
betterloop library install org.review --version 1.0.0 --harness claude-codeRead the instructions and supporting files. For an executable hook, examine the real script and its reviewed lifecycle event before installation.
An optional selection applies across repositories for Claude Code on this device. Its version remains pinned. Catalog approval alone does not install it for developers.
An installed MCP definition may still need external account authorization. That sign-in establishes account access. Tool permission and successful discovery require their own checks.
A successful library status result describes the local selection. It cannot establish that a resource ran later in a session. Inspect the relevant evidence separately.
05 / Claude Code handbook
Work from the diagnostic category
| Reported problem | Where to look | Repair path |
|---|---|---|
| Missing authentication | The native Claude Code account connection | Complete provider sign-in inside Claude Code. Inspect doctor after authentication. |
| Activation pending despite files | Plugin enablement and session events | Reload if supported. Open a fresh session. Check for an observed supported invocation. |
| Denied tool action | The applicable rule and its bounded reason | Have the configuration owner review the intended permission and matching rule. |
| Old signed content | Cache validity and compatible release availability | Refresh with sync. Recheck the original working repository. |
| Explicit model switching has no check | Plugin enablement and the host version | Verify the 2.1.251 minimum. Review native managed model settings for other selection routes. |
| Installation blocked by the host | Host version and managed configuration | Resolve the restriction identified by the native host. Retry the supported installation afterward. |
betterloop sync --harness claude-code --project /path/to/repository
betterloop doctor --harness claude-code --project /path/to/repositoryIllustrative session: a Harbor search change
A Harbor developer opens search-api in a fresh Claude Code session. Doctor shows provider access and observed activation. The developer reviews the required tool controls.
The team permits a literal search program. A covered tool call evaluates that program against verified local policy. The developer then runs a meaningful repository check separately.
A finished response does not establish a learning outcome. For an entry actually exposed in this session, explicit verification can supply evidence for a later outcome report.
During a temporary outage, a valid unexpired cache can continue. Invalid or expired policy reduces coverage. Required policy failure can deny supported tool actions.
To remove only this connection, run betterloop uninstall --harness claude-code. Owned integration state and restricted credentials are removed or revoked.
The native agent, native credentials, and unrelated plugins remain. Use this narrower operation when your intent is to stop Betterloop management of Claude Code.