Skip to content

English · 日本語

What uses Claude, and what doesn't

The canonical answer to "which parts of Bajutsu reach a model, and which run with nothing configured at all". The split is a first-class, tested property of the tool (BE-0101). It is the developer-experience companion to the "your AI, your key, your data" guarantee on the other side of the line (self-hosting, BE-0047).

Related: cli · concepts · recording · self-hosting


The one line that matters

Bajutsu draws a hard architectural line. The deterministic run / CI gate calls no model, and only the Tier-1 authoring / investigation paths reach Claude. The axis is whether a path invokes Claude at all, not whether a particular credential is present.

Claude can be reached four ways:

  • the Anthropic API
  • Amazon Bedrock
  • the Anthropic CLI ant under a browser-based OAuth/SSO sign-in
  • the Claude Code CLI claude, billing a Claude Pro/Max/Console seat

"Needs an API key" is the wrong unit. "Uses Claude" is the accurate one, and it stays correct when providers join the list.

Everything on the Claude-free side runs with zero configuration: no credential, no .env, no login, no AI runtime. Clone the repo and it works immediately.

The split

Command / path What it does
Claude-free (zero-config) run run scenarios deterministically — pass/fail is machine-only, never a model
doctor check the environment is runnable and score the current screen
repl open a manual shell against the running app: read the element tree, act on an id
codegen generate native XCUITest source from a scenario
runner build the generic XCUITest runner, signed for a real iPhone or iPad
trace print a text timeline over a saved run
lint / schema validate scenarios / emit the JSON Schema, without running
approve promote a run's screenshots to visual baselines
audit / coverage / impact / flakiness score a scenario's determinism / map id-namespace coverage / flag the steps a source change likely affects / rank scenarios by verdict flips (all advisory)
report / export / stats re-render a finished run / archive it / aggregate a run directory into the whole-suite trend
mcp / worker serve run/doctor as MCP tools / run a background job worker
serve the local web UI — boots with nothing configured; its Claude tabs degrade gracefully
triage diagnose a failed run with the rule-based agent (no --ai)
Uses Claude record author a scenario by driving the app with Claude
crawl explore an app autonomously with Claude to build a screen map
triage --ai diagnose a failed run with Claude instead of the rule-based agent

The classification applies to the path, not the command name. triage is Claude-free, and a single --ai flag moves it onto the Claude path.

Since BE-0402, run is Claude-free with no flag-gated exception at all. Its alert guard (--system-alert-handling, on by default) used to be one: where the native SpringBoard path could not name a prompt, the guard read a screenshot with a model and tapped where the model directed. That fallback is gone from run, so the guard needs no credential and consults none. It leaves a prompt it cannot name alone, and names the prompt in the blocked step's own failure instead.

The split makes the Tier-1 / Tier-2 boundary visible. Nothing here puts a model on the run / CI gate.

Where you see it

The classification is defined once, in bajutsu/common/capability/capabilities.py, and every surface consumes that definition, so the surfaces cannot disagree:

  • bajutsu --help groups every top-level command under Claude-free (zero-config) or Uses Claude.
  • doctor reports Claude readiness as a separate, clearly optional section. A host with no AI setup is still graded Ready for the deterministic path. Claude appears on a distinct "not configured (optional)" line, never conflated with a blocking problem.
  • serve shows the Claude tabs (record / crawl). When Claude is unreachable, it disables them with an inline explanation that points at the in-UI key field. The tabs re-enable the moment a key is set, Bedrock is configured, or the ant / claude CLI is signed in.

Installing the Claude paths

The split is a packaging boundary as well as a runtime one (BE-0111). The AI software development kit (SDK) is an opt-in extra, so the base install carries no AI dependency at all.

  • pip install bajutsu installs the deterministic authoring / running paths (run, doctor, lint, codegen, trace, approve, and the rest of the Claude-free column above). The install adds no AI SDK, and nothing here reaches a model.
  • pip install bajutsu[ai] adds the Anthropic SDK for the Claude paths (record, crawl, triage --ai) under the API-key, Bedrock, or ant provider. For the Amazon Bedrock provider, use bajutsu[bedrock] instead; it layers the Bedrock variant onto the same SDK. The claude-code provider needs neither extra, because it shells out to the external claude CLI rather than the SDK.

Contributors get every extra at once through uv sync --group dev, so the gate keeps testing the Claude paths. The AI-free guarantee is about the base install, not about dropping test coverage.

Reaching Claude, when you want it

Any one of these mechanisms satisfies the "uses Claude" paths. Details are in self-hosting and recording.

  • Anthropic API: set ANTHROPIC_API_KEY (or the env var named by ai.keyEnv).
  • Amazon Bedrock: provide the standard AWS credential chain plus a provider-prefixed model id (ai.model or $BAJUTSU_BEDROCK_MODEL).
  • Anthropic CLI (ant): set ai.provider: ant and run ant auth login. The CLI draws on a Claude Pro/Max/Console seat instead of a key (BE-0163).
  • Claude Code CLI (claude): set ai.provider: claude-code and sign in with claude setup-token or an interactive login. A headless host sets CLAUDE_CODE_OAUTH_TOKEN instead. This CLI also draws on a Claude Pro/Max/Console seat rather than a key (BE-0176).

Config decides which mechanism authenticates (per BE-0047 / BE-0053 / BE-0163 / BE-0176). The classification above is the same whichever mechanism you pick.

Turning every Claude path off, in one line

The mechanisms above are opt-in, so a project that configures none of them reaches no model. That silence is still an accident of the environment, not a statement in the repository. Nothing a reviewer reads records the intent, and a key exported to author one scenario with record is enough to put record and crawl on a model in every later shell. Setting the provider to none states the policy instead (BE-0394):

defaults:
  ai:
    provider: none      # no AI path may run in this repository

With that line committed, the three authoring and investigation commands (record, crawl, and triage --ai) exit with a message naming the setting rather than starting, and no code path can construct an AI backend at all. run is unaffected either way. BE-0402 removed the one path of its own that ever reached a model, so run neither needs the switch nor notices it.

A configured ai.provider outranks $BAJUTSU_AI_PROVIDER, so the setting also holds on a continuous-integration runner whose environment nobody controls. The configuration guide covers the precedence rules and the one exception: serve's Settings dropdown, which never offers none.