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
antunder 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 --helpgroups every top-level command under Claude-free (zero-config) or Uses Claude.doctorreports Claude readiness as a separate, clearly optional section. A host with no AI setup is still gradedReadyfor the deterministic path. Claude appears on a distinct "not configured (optional)" line, never conflated with a blocking problem.serveshows 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 theant/claudeCLI 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 bajutsuinstalls 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, orantprovider. For the Amazon Bedrock provider, usebajutsu[bedrock]instead; it layers the Bedrock variant onto the same SDK. Theclaude-codeprovider needs neither extra, because it shells out to the externalclaudeCLI 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 byai.keyEnv). - Amazon Bedrock: provide the standard AWS credential chain plus a provider-prefixed model id
(
ai.modelor$BAJUTSU_BEDROCK_MODEL). - Anthropic CLI (
ant): setai.provider: antand runant auth login. The CLI draws on a Claude Pro/Max/Console seat instead of a key (BE-0163). - Claude Code CLI (
claude): setai.provider: claude-codeand sign in withclaude setup-tokenor an interactive login. A headless host setsCLAUDE_CODE_OAUTH_TOKENinstead. 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.