AI integration: Claude Studio and the Anthropic client
ORIX DJ can ask an Anthropic model to write, explain, fix or improve an ORIX Script automation, design an effect, plan a performance or draft a MIDI mapping. The feature is optional, uses the user's own API key, and is the only part of the application that opens a network connection. This document describes exactly what is sent, how the answer is handled, how the key is stored, and what has and has not been tested.
One fact first, because it qualifies everything below: no request has ever been sent to the real Anthropic API from this code. No API key was available during development. The client was exercised only against local stub transports (a URLProtocol in the tests and a debug-only one in the application). Wire-format details are implemented from the API documentation and verified against those stubs, not against the service.
Related documents: automation (compiler, runtime, simulator), overview, persistence, security report, testing, and the user-facing security chapter.
Components
| Component | File | Responsibility |
|---|---|---|
AnthropicClient |
Packages/ORIXDJCore/Sources/ORIXDJEngine/Anthropic/AnthropicClient.swift |
Raw HTTPS client for two endpoints (Models, Messages), streaming, typed errors, bounded retries, hourly request budget. The file header notes that there is no official Swift SDK. |
APIKeyStore |
same file | Keychain storage of the key and the masked display form. |
AnthropicSettings |
same file | Model, effort, maximum output tokens, requests per hour, confirm-before-sending, refusal fallback. Stored in preferences; the key is not part of it. |
ScriptAssistant, AssistantContext, AssistantProposal |
Anthropic/ScriptAssistant.swift |
Builds the request, extracts the script or mapping from the answer, validates it locally, computes the list of risks and the diff. |
ClaudeStudioModel |
App/Sources/Features/ClaudeStudio/ClaudeStudioModel.swift |
Conversation state, sharing switches, streaming, cancellation, validation off the main thread. |
ClaudeStudioView, ClaudeContextPanel, confirmation sheet |
ClaudeStudio/ClaudeStudioView.swift |
Task picker, prompt, context preview, "Send this to Anthropic?" sheet. |
ClaudeProposalCard |
ClaudeStudio/ClaudeProposalCard.swift |
Shows a validated proposal and the user actions on it. |
ClaudeAccess |
ClaudeStudio/ClaudeAccess.swift |
The only application code that reads the key; exposes the masked form to views. |
AISettingsTab |
App/Sources/Features/Settings/AISettingsTab.swift |
Key entry, validation, model picker, limits. |
ClaudeStub |
ClaudeStudio/ClaudeStub.swift |
Debug-only local transport. |
Script generation workflow
sequenceDiagram
actor User
participant Studio as ClaudeStudio
participant Assistant as ScriptAssistant
participant Client as AnthropicClient
participant API as Anthropic API
User->>Studio: choose task, type prompt, set sharing switches
Studio->>Assistant: request(task, prompt, context, history)
Assistant-->>Studio: AnthropicRequest (system prompt and messages)
Studio->>User: confirmation sheet with the exact message text
User->>Studio: Send
Studio->>Client: send(request, settings, apiKey from Keychain)
Client->>API: POST /v1/messages with stream true
API-->>Client: server-sent events
Client-->>Studio: text deltas as they arrive
Client-->>Studio: AnthropicResult after the stop reason is checked
Studio->>Assistant: evaluate(answer, task)
Assistant->>Assistant: extract code block, compile, simulate, list risks
Assistant-->>Studio: AssistantProposal
Studio->>User: proposal card (script, validation, simulation, risks, diff)
User->>Studio: Save, Edit, Test, Copy or Run after a second confirmation
The confirmation sheet appears when AnthropicSettings.confirmBeforeSending is true, which is the default. With it switched off in Settings, send goes straight to the client; the context preview in the side panel still shows the shared text continuously.
What is sent
Endpoints and headers
| Item | Value in the code |
|---|---|
| Base URL | https://api.anthropic.com (default argument of AnthropicClient.init) |
| Messages | POST /v1/messages |
| Models | GET /v1/models?limit=100, then &after_id=<last_id> while has_more is true, at most 10 pages |
x-api-key |
the user's key |
anthropic-version |
2026-10-21 (AnthropicClient.apiVersion) |
content-type |
application/json |
anthropic-beta |
server-side-fallback-2026-07-01, only on Messages requests that include fallbacks |
No other header is set by the application. The session is URLSessionConfiguration.ephemeral (the code comment: "No cookies, no cache, no credential storage: nothing about a request is kept on disk"), with timeoutIntervalForRequest = 120 seconds, timeoutIntervalForResource = 900 seconds and waitsForConnectivity = false.
Request body (AnthropicClient.body)
| Field | Value |
|---|---|
model |
settings.model |
max_tokens |
settings.maxOutputTokens (default 16000; the Settings screen clamps it to 256…128000) |
stream |
true, always |
system |
one text block containing the system prompt, with cache_control: {"type": "ephemeral"} |
messages |
array of {"role", "content"} with plain string content: earlier turns of the conversation, then the new user message |
output_config |
{"effort": <value>}, only when an effort is chosen in Settings (low, medium, high, xhigh, max; "Model default" omits the field) |
fallbacks |
"default", only when the refusal fallback is on and the model is in fallbackModels |
Not sent: temperature, top_p, top_k, thinking, budget_tokens, tools, images, files, metadata. AnthropicTests.streamsTextAndSendsTheDocumentedRequest asserts the URL, the three headers, model, stream, fallbacks, output_config.effort, the cache_control on the system block, the absence of the five sampling and thinking fields, and that the key does not appear in the body.
Models
The application does not ship a list of models to choose from. The picker in Settings is built only from the list returned by the Models endpoint for the stored key (AppSettings.verifiedModels); a stored model that is not in that list is shown as "not available" with a warning. Identifiers that do appear in the code:
AnthropicSettings.defaultModel = "claude-opus-5-5": the initial setting, and the model selected after validation when the stored one is not offered and this one is.AnthropicClient.fallbackModels = ["claude-fable-5-2", "claude-fable-5-1", "claude-opus-5-5", "claude-opus-5", "claude-sonnet-5-5"]: the models for which thefallbacksparameter and its beta header are sent.
System prompt (ScriptAssistant.systemPrompt)
A constant string, identical on every request so that it can be served from the prompt cache:
- a paragraph stating the role and that scripts are compiled, type-checked and simulated before the user decides, so "a path or statement that is not in the reference is a compile error the user will see";
ReferenceGenerator.languageBrief: structure, types and literals, statements, every deck, mixer, master and effect path with its type and range, actions, events, builtins and limits, generated from the sameScriptSchemathe compiler uses (see automation);- one example automation ("Eight Bar Transition");
- the output contract: a complete script in one
orixdjcode block, a short bar-by-bar explanation, what to check before running live, restore what is changed, say so when the request cannot be expressed, do not rewrite when only asked to explain.
The system prompt contains nothing about the user, the library or the machine.
User message (ScriptAssistant.request)
<instruction for the task>
Request: <the user's prompt, when not empty>
Context from the application:
<AssistantContext.rendered()>There are seven tasks (AssistantTask): generate, explain, fix, improve, effect, midi, plan, each with one fixed instruction sentence or paragraph. For midi, the list of mappable control targets (ControlTargets.all, identifier and kind) is appended to the context, and the instruction asks for a JSON object in a json code block.
AssistantContext.rendered() produces the context text. Each part is controlled by a switch in the Claude Studio side panel:
| Part | Content | Switch and default in ClaudeStudioModel |
|---|---|---|
| Language version, deck letters | ORIX Script version: 1.0, Decks available: A, B, C, D |
always |
| Deck states | master clock tempo; per deck: empty, loaded and paused, or playing; tempo; Camelot key | includeDecks, on |
| Track titles | title of each loaded track | includeTitles, off; the code comment calls titles "private library data" |
| Active effects | names of effect units that are switched on, per rack | includeEffects, on |
| MIDI controller | names of online MIDI sources, midi task only |
includeController, on |
| Current script | source of the chosen editor document in an orixdj block |
includeScript, off initially; set automatically to on for explain, fix, improve and off for the other tasks when the task changes |
| Compiler messages, simulator output | diagnostics with line, column and code; a short simulation summary | includeDiagnostics, on, effective only with the script |
The diagnostics come from ScriptCheck.run, which compiles and simulates the shared script locally 250 ms after it changes.
History: every earlier turn of the conversation that did not end in an error is resent as a user message (the exact text sent then) and an assistant message (the full answer). "New Conversation" clears it.
Not part of any request: audio, file paths, file contents other than the shared script, library contents, crates, playlists, play history, MIDI mappings, settings.
What the user sees before sending
- The side panel (
ClaudeContextPanel) shows, under "Exact text that will be sent", the output ofstudio.context(model).rendered(), refreshed every second, with the statement "Audio is never uploaded. Your request, the ORIX Script language reference and the text above are all that is sent." - The confirmation sheet shows the complete user message exactly as sent (
pending.request.messages.last?.content), the number of earlier messages that are resent, the length of the language reference with a disclosure that shows its full text, the destination ("To api.anthropic.com over HTTPS, with your API key") and the model identifier. - After sending, each turn in the conversation keeps
sentText, the exact user message.
Streaming
The response is read with URLSession.bytes(for:) and iterated line by line. Only lines starting with data: are considered; each payload is parsed as JSON and dispatched on its type:
| Event type | What is read |
|---|---|
message_start |
message.model (the model that actually answers), usage.input_tokens, usage.cache_read_input_tokens, usage.cache_creation_input_tokens |
content_block_delta |
only when delta.type is text_delta: delta.text is appended to the result and passed to onText. Other delta types, including thinking deltas, are ignored |
message_delta |
delta.stop_reason, delta.stop_details.category, usage.output_tokens |
error |
overloaded_error becomes .overloaded; anything else becomes .server(500, message) |
anything else (content_block_start, content_block_stop, message_stop, ping, …) |
ignored |
The request-id response header is kept in AnthropicResult.requestID. Text deltas arrive on a network thread; ClaudeStudioModel forwards them through an AsyncStream to the main actor so that they are appended in order.
After the stream ends the stop reason is checked before the text is used (code comment: "Always look at the stop reason before trusting the text"): refusal throws .refusal(category:), max_tokens throws .truncated, an empty stop reason throws .invalidResponse.
Errors, retries, cancellation, budget
AnthropicClient.error(status:body:headers:model:) maps HTTP status codes to AnthropicError. The message is taken from the error.message field of the response body when present (the first 65536 bytes are read).
| Condition | AnthropicError |
Retried |
|---|---|---|
| Empty key | .noKey |
no; nothing is sent |
| Hourly budget reached | .requestLimit(n) |
no; nothing is sent |
| HTTP 400, 413, 422 | .badRequest(message) |
once without fallbacks and the beta header, only when the message mentions fallback or anthropic-beta |
| HTTP 401 | .unauthorized |
no |
| HTTP 402 | .billing |
no |
| HTTP 403 | .forbidden(message) |
no |
| HTTP 404 | .modelNotFound(model) |
no |
| HTTP 429 | .rateLimited(retryAfter:) from the retry-after header |
no |
HTTP 529, or overloaded_error in the stream |
.overloaded |
yes |
| Other status | .server(code, message) |
yes when the code is 500 or above |
| Transport failure | .network(description) |
yes |
Stop reason refusal |
.refusal(category:) |
no |
Stop reason max_tokens |
.truncated |
no |
| Unparseable response, missing stop reason | .invalidResponse |
no |
Task cancelled or URLError.cancelled |
.cancelled |
no |
Retries are bounded: at most two retries after the first attempt, with pauses of 1.5 s and 3 s (pow(2, attempt) * 0.75 seconds). AnthropicTests.errorsAreTypedAndRetriesAreBounded checks the mapping of 400, 401, 402, 403, 404, 429 and 529, counts exactly three requests for a persistent 529, and checks the refusal, truncation, fallback-rejection, missing-key and budget cases. The models call has no retry.
The hourly budget (maxRequestsPerHour, default 60, 1…600 in Settings) is counted in memory per AnthropicClient instance, once per send call regardless of retries, and starts from zero at each launch (the Settings row says "Counted since ORIX DJ started").
Cancellation: the Stop button cancels the task that awaits send. The turn is recorded with the text received so far and the error "Cancelled."; a failed or cancelled request puts the prompt back in the field so that it can be sent again.
Refusals: when refusalFallback is on (default) and the model is in fallbackModels, the request opts into the server-side fallback, and the result's model field, taken from message_start, names the model that wrote the answer. Otherwise a refusal is shown as an error ("Claude declined this request", with the category when given). An answer with no code block is not an error: the proposal simply has no script and only the explanation is shown.
Each error has a user-readable description (errorDescription) that says what to do next, for example "Anthropic rejected the API key. Check it in Settings → AI → Anthropic."
Validation of the answer
flowchart TD
A["Answer text"] --> T{"Task is midi?"}
T -->|"yes"| J["First json or untagged code block"]
J --> JP["Decode MIDIMappingProfile"]
JP -->|"fails"| JE["Issue: the mapping could not be read"]
JP -->|"ok"| JF["Drop entries with unknown targets, run profile.validate"]
JF --> MC["MIDI proposal card with issues; Save Mapping asks for confirmation"]
T -->|"no"| B["First orixdj, orix, orixscript or untagged block containing the word automation"]
B -->|"none"| N["Explanation only, no script"]
B -->|"found"| C["ScriptCompiler.compile with default capabilities and limits"]
C -->|"errors"| X["Not valid: show diagnostics; no simulation"]
C -->|"program"| S["Simulator.run in the simulated rig"]
S --> R["Compute risks from requirements, simulation and source"]
R --> V{"Compiled and simulation did not fail?"}
V -->|"no"| X2["Not valid: Run is disabled"]
V -->|"yes"| OK["Validated: Run is enabled, behind a confirmation"]
ScriptAssistant.evaluate(answer:task:simulation:) is the whole validation. It treats the answer as untrusted text:
- The first fenced block tagged
orixdj,orixororixscript(or untagged) that contains the wordautomationis extracted. Everything else is the explanation. - The script is compiled with
ScriptCompiler.compile, the same entry point and the sameCompileLimitsas a script typed in the editor. - If it compiles,
Simulator.runexecutes the first automation in aSimulatedRigwith the defaultSimulationConfig(deck A playing, deck B loaded, 128 BPM, at most 256 beats, defaultRuntimeLimits). risks(...)computes a list locally from the compiled requirements, the simulated trace and the source text, not from the model's description: waits for events; longer than 256 beats; uses seconds; which decks it stops; loads or ejects tracks; which effects are still on at the end; simulation timed out; clamped values; up to three simulator warnings; a failed simulated run; changesmixer.master.volume; up to three compiler warnings.AssistantProposal.isValidiscompile.succeeded && simulation.error == nil.
For Fix and Improve, the card also shows a line diff (ScriptAssistant.diff, longest common subsequence) between the script that was shared and the proposed one.
Model output is never run automatically
Verified by reading every call site:
ClaudeStudioModel.performends by storing the proposal in the turn. Its file header states: "A proposal is never run from here: running is a user action." The model has no reference toAutomationHost.ScriptAssistant.evaluatecalls only the compiler and the simulator. The simulator's target is aSimulatedRig; it has no path toDJEngine.- The proposal card offers Save (to the script library, origin
.ai), Edit (open in the editor), Test (simulate again), Copy, and Run…. Run is disabled unless the proposal is valid, and opens an alert, "Run this automation live?", whose text names the decks the script addresses, says which of them are playing now, quotes the first risk and mentions the emergency stop. Only the alert's "Run Live" button callsAppModel.run(source:origin: "claude"), which compiles the text again and starts it on the automation host like any other script. - A MIDI mapping proposal is saved only after a confirmation dialog ("Save and Activate", "Save Without Activating", "Cancel").
One launch option exists for screenshots: when the application is started with ORIXClaudePrompt, Claude Studio fills the prompt and calls send; with ORIXClaudeAutoConfirm it also confirms the sheet, but only when the debug stub transport is active. Neither option runs a proposal.
AnthropicTests.proposalsAreValidatedLocally covers: a valid script (requirements, static length 32 beats, the "stops deck A" and "fx.echo switched on" risks); invented syntax (deck.A.scratch(4beats) and system("rm -rf") give two compile errors and no simulation); a script that compiles but fails in the simulator (deck.D.play() on an empty deck is not valid); an answer without a script; a MIDI proposal with an unknown target (deck.A.launchMissiles is removed and reported); the title switch of the context; and the diff.
API key handling
| Aspect | Implementation |
|---|---|
| Storage | macOS Keychain, kSecClassGenericPassword |
| Service | ai.spboucher.orix.dj.anthropic (APIKeyStore.defaultService); isolated instances started with their own data directory (tests, screenshots) use the same name with the suffix .test |
| Account | api-key |
| Accessibility | kSecAttrAccessibleWhenUnlockedThisDeviceOnly |
| Label | ORIX DJ – Anthropic API key |
| Save | whitespace trimmed; the existing item is deleted, then the new one added; saving an empty string only deletes |
| Display | APIKeyStore.masked: the first 7 characters, an ellipsis and the last 4 (sk-ant-…abcd); a key of 12 characters or fewer is shown as bullets |
| Entry | a SecureField; the field is cleared as soon as Save is pressed |
| Validation | a call to the Models endpoint; success stores the returned list, 401 clears it |
| Removal | confirmation dialog, then SecItemDelete; the verified model list is cleared |
The key is read from the Keychain at the moment of a request (ClaudeAccess.keyForRequest()), passed as a parameter to AnthropicClient, and placed in the x-api-key header. It is not held in a stored property of any view or model object; views only ever receive maskedKey. It is not part of AnthropicSettings (which is what is written to preferences under ai.anthropic), not part of projects, and not part of the request body. No code in the client or in Claude Studio writes to a log; Scripts/check.sh fails the repository check if a line calls print, NSLog, os_log or Logger with apiKey or api_key on it, and scans the repository for strings shaped like a real key (sk-ant- followed by 24 or more characters, the test placeholder excepted). Error messages shown to the user are built from the HTTP status and the server's error.message, never from the request.
AnthropicTests.keychainStoresAndMasksTheKey saves, replaces, loads and deletes a key under a unique service name in the real Keychain and checks the masked form. See the security report for the limits of these checks.
The local stub
ClaudeStub.swift is compiled only in Debug builds (#if DEBUG). When the application is launched with the default ORIXClaudeStub set to true, ClaudeAccess replaces the client with one whose URLSession uses StubURLProtocol:
GET …/v1/modelsreturns three canned models (claude-fable-5-2,claude-opus-5-5,claude-sonnet-5-5);- any other request is answered as a Messages stream in the server-sent-event format (
message_start,content_block_start,content_block_deltachunks of about 14 characters every 18 ms,content_block_stop,message_deltawithend_turn,message_stop); - the answer depends on the first words of the user message: a canned script for most tasks, a canned mapping for MIDI (which deliberately contains one unknown target,
deck.A.sparkle), canned prose for Explain, and for Fix and Improve a modified copy of the script that was shared, so that the diff view has something real to show.
In stub mode the header carries the placeholder stub-transport-no-key instead of a key, no Keychain item is read, Settings shows a "Debug stub transport" row, and Claude Studio shows a badge. The request never leaves the process. The stub exists so that the request, streaming, validation and presentation path can be exercised and captured in screenshots without a key; it is not present in a Release build.
What was tested and what was not
Tested (suite AnthropicTests in Tests/ORIXDJEngineTests/SessionTests.swift, five tests, all passing in the run used for this document; the transport is a URLProtocol stub, so no packet leaves the machine):
- the request: URL, headers, body fields, absence of rejected parameters, prompt caching marker, key only in the header;
- streaming: text deltas delivered in order, thinking deltas ignored, token counts and request id read;
- error mapping, bounded retries, refusal and truncation handling, retry without the fallback parameter, missing key and request budget refused before any request;
- pagination of the model list and the
401case; - Keychain save, replace, load, delete and masking;
- local validation of proposals, the context switches and the diff.
Not tested, and not verified in any other way:
- any exchange with the real Anthropic API. It is therefore unverified that the service accepts the
anthropic-versionvalue, thefallbacksparameter with its beta header, theoutput_config.effortvalues offered in Settings, or the default model identifier, and that the real event stream is parsed correctly in all cases (for example anerrorevent after partial text, or a fallback answer); - prompt caching actually taking effect (the system prompt must exceed the model's minimum cacheable length);
- the quality of generated scripts. No model has ever produced a script for this application; the system prompt has not been evaluated;
- behaviour on slow or interrupted networks, proxies, and TLS failures;
- the Claude Studio views themselves beyond what the stub transport and screenshots exercise; there is no automated test of the confirmation sheet or of the Run confirmation.
Known behaviours worth stating:
- When a streamed request fails part-way with a retryable error, the retry starts a new stream and its deltas are appended after the text already shown; the displayed text is replaced by the correct final text only when the request completes.
- A
429is reported to the user with the retry delay and is not retried automatically. - The hourly request count is not persisted, so restarting the application resets it.