Assistant

Lightfall embeds a Claude-based agent that understands the application and the beamline it is running on. It answers questions, but it can also act: open panels, read and move devices, run plans, inspect data — and build new panels and plans on request (covered separately in Customizing Lightfall with the Agent). Every action goes through an approval prompt unless you have allowed it.

Setup

With the Claude Code backend (the default), the assistant needs Claude credentials. In File → Settings → Assistant:

  • API key — paste an Anthropic API key, or set the ANTHROPIC_API_KEY environment variable before launching.

  • OAuth — if you have authenticated the Claude Code CLI on this machine (claude auth login), the settings page shows your OAuth status and the assistant can use that instead of an API key.

The same page selects the model, the maximum turns per request, and the permission mode (see below).

Using the assistant

Open the Assistant panel from the sidebar (lower section). Type in the input field and press Enter to send (Shift+Enter inserts a newline). The broom button clears the conversation and starts fresh.

🖼️ Image placeholder — Screenshot: Assistant panel with a short conversation and the input field at the bottom

Things you can ask, with the simulated devices as examples:

Questions and help

  • “How do I run a 2D grid scan?”

  • “What’s the difference between an absolute and a relative scan?”

  • “Why did my last scan fail?”

Application control

  • “Open the Devices panel”

  • “What panels are available?”

Device operations

  • “What motors are available?”

  • “Read the temperature sensor”

  • “Move motor to 2.5”

Acquisition and data

  • “Run a 1D scan of motor from -5 to 5 with det, 21 points”

  • “What’s the RunEngine doing right now?”

  • “Show me the last run in the visualization panel”

The assistant sees the same application state you do — the panel registry, the device catalog, the plan registry, run history — so its answers are about your session, not generic Bluesky advice.

Approval prompts

The assistant’s tools follow a whitelist design: read-only tools run without asking (listing panels and devices, reading values, checking run status), and everything that changes state requires your approval — moving a motor, running a plan, opening or closing panels, writing files.

When the assistant wants to use a tool that is not auto-approved, a prompt appears in the chat showing the tool name and its exact input, with three choices:

  • ✓ Allow — permit this one call

  • ✗ Deny — refuse it (the assistant is told, and can try something else)

  • ∞ Always — permit this tool for the rest of the session without asking again

🖼️ Image placeholder — Screenshot: an approval prompt in the chat for lightfall_move_motor showing the motor name and target position, with Allow / Deny / Always buttons

Note

Plans the assistant submits go through the same path as plans you run yourself — including the Sample Metadata dialog and the RunEngine queue. You keep the toolbar pause/stop/abort controls regardless of who started the run.

Permission modes

File → Settings → Assistant → Permission Mode adjusts the gate:

Mode

Behavior

default

Confirmation required for all non-read-only actions

acceptEdits

File-edit tools are also auto-approved

bypassPermissions

No confirmations (for unattended automation — use deliberately)

Skills and tools

The assistant’s capabilities come from agent plugins — bundles of domain prompts and tools. Built-in ones cover device operations, plan management, engine control, panel building, beamline alignment, scan planning, and adaptive (gpCAM/Tsuchinoko) experiment design; beamline deployments and user plugins can add more.

File → Settings → Assistant Tools lists every agent plugin with a checkbox to enable or disable it. Disabling a plugin removes its prompts and tools from the assistant entirely.

Tips

  • Be specific. “Run a 1D scan of motor1 from -2 to 2 with det1, 41 points” beats “run a scan”.

  • Use it to learn. “What plans are available?” or “explain what the adaptive scan parameters mean” are fast ways into the system.

  • Watch the prompts. The approval dialog shows exactly what the assistant is about to do, with real parameter values — read them before allowing, especially for motor moves on real hardware.

  • Reset when switching topics. Long conversations slow responses; the broom button starts a clean one.

Using Gemini Enterprise (agy)

Instead of the Anthropic API, the assistant can run on Gemini Enterprise through the Antigravity CLI (agy). Lightfall’s tools, permission prompts, skills and session history work the same way; only the model backend changes.

Choosing a backend

The assistant runs on Claude Code (default) or Gemini Enterprise through the Antigravity CLI (agy).

  1. Open File → Settings → Assistant.

  2. Under Backend, pick Gemini (agy). The status line checks your sign-in.

  3. If it says Not signed in, click Sign in…. A console window opens with agy’s Google sign-in; finish it in the browser, then close the console. The status turns to Signed in within a few seconds.

  4. Pick a Model (or leave Default (agy)) and an Effort, check the GCP project and location, and press OK.

Open assistant tabs switch to the new backend straight away; a tab that is mid-reply switches when the reply ends. Each backend keeps its own session history.

Notes for Gemini:

  • Costs are not shown (the cockpit shows tokens and context only).

  • A model change applies from the next message.

  • Reasoning effort is per model: the Effort list (in Settings and in the input row’s tune menu) shows only the levels the selected model offers. A change in the tune menu applies from the next message and keeps the conversation (on Claude it starts a fresh one). A change in Settings restarts the assistant, as a model change in Settings does.

  • Background subagents (“Agent tool”) are not available yet.

Preference keys

Preference

Default

Meaning

agent_backend

claude-code

Set to agy to use Gemini Enterprise.

agy_path

empty

Path to the agy executable. Empty means PATH, then the default install location.

agy_gcp_project

lbl-gemini-enterprise-access

GCP project that Gemini Enterprise usage is billed to.

agy_gcp_location

global

GCP location for agy.

agy_model

empty

agy base model id (for example gemini-4-argon). Empty means agy’s default.

agy_effort

empty

Reasoning effort for that model (low, medium, high, …). Empty means the model’s default.

Signing in

Sign in once with the agy CLI or the Antigravity app (your Gemini Enterprise licence is used); Lightfall reuses that sign-in and never changes it. Lightfall keeps its own agy configuration separate from your personal agy settings, so your own agy setup is not touched.

The agy home lives under %APPDATA%\ncs\agy-home (the roaming profile). Profiles redirected to a UNC path are not supported, because the per-session homes need directory junctions, which cannot point across network shares.

Known limitations

  • agy streams no thinking text, so there are no thinking bubbles.

Troubleshooting

The assistant doesn’t respond

  • Check credentials in File → Settings → Assistant (the page has a connection test).

  • Check network access to the Anthropic API (or your configured custom endpoint), and the Logging panel for errors.

The assistant can’t perform an action

  • Device- and engine-control tools check your permissions — in a guest session the assistant cannot move motors or control the RunEngine.

  • The tool’s plugin may be disabled under Assistant Tools.

Responses are slow

  • Reset the conversation to clear accumulated history.

  • Large tool results (long device lists, big scans) take time to process; narrower questions help.