GUPPI Operator guide
This page is for two readers: you, deciding how far to trust an agent with your rig, and the agent itself. Every agent that connects to GUPPI receives the short version of this guide in the connection’s instructions, so it knows how to behave before it has read anything else. The lines in bold below are those instructions, word for word.
Start by asking
Section titled “Start by asking”The first call an agent makes should be explain_rig. It names the rig, its gear, what is running right now, and the agent’s own trust level on this rig, so the agent never has to guess what it may do.
Verify, don’t assume: read the rig’s state before you act and again after.
A tool’s answer is the rig’s word. An empty field means the rig does not know, never zero. After an action, read the state again: an autofocus that started is not an autofocus that finished, and a filter change is done when the wheel reports the slot.
When the rig says no
Section titled “When the rig says no”A refused call says why and where the owner changes it. Relay that to the human; never look for a way around it.
A refusal is an answer, not an error to retry. It may come from the trust dial (“Request denied: Claude Code is set to Watch only”) or from the rig itself (a sequence owns the filter wheel; the camera is busy with autofocus). The right move is to tell the human what was refused and why, and let them decide.
A running sequence belongs to the human
Section titled “A running sequence belongs to the human”A running sequence is the human’s plan: don’t change it mid-run.
Pause or stop a sequence when the human asks, or when a reading clearly calls for it, and say why in the reason field: it lands in the activity log next to the action. Prefer pausing to stopping; a stopped sequence cannot be resumed. While a sequence runs, it owns the filter wheel, and GUPPI refuses filter changes.
Never restart guiding or the guiding software on your own initiative; report guiding trouble instead.
Guiding problems have causes an agent cannot see from the numbers alone: clouds, wind, a cable, a dew-covered guide scope. Restarting the guiding software mid-sequence throws away calibration and can cost the rest of the night. Report what you see (the RMS, the star’s signal, how long it has been lost) and let the human or Guardian decide.
Starting a saved sequence
Section titled “Starting a saved sequence”Start only a saved sequence the human asked for, named as list_saved_sequences lists it; the rig runs it exactly as saved.
start_sequence starts a sequence from your Library on the rig the way the ARIS app’s Start button starts it right after you load it: the targets, frames and pre- and post-commands as you saved them, with nothing changed by the agent. An agent cannot edit a sequence through GUPPI; when the plan needs a change, you make it in the app and save it. list_saved_sequences gives each saved sequence’s name, id, targets and frames, so the agent names the one you meant.
Starting a sequence moves the mount, so it is motion: at Ask before motion you approve it first, on a card that says what the run will do. Approving builds the start again from your Library and the rig’s settings at that moment, and if the saved sequence changed since the agent asked, nothing starts and the agent is told why. A start is refused while a sequence runs, and while one waits at its checkpoint: the agent can resume that one with resume_sequence, and only you decide to start over.
At night, Guardian is in charge
Section titled “At night, Guardian is in charge”Overnight, Guardian, the rig’s own watchdog, outranks you: check in and report, and leave recovery to it.
Guardian watches the sky, the guiding and the mount around the clock and has recovery steps of its own. An agent’s best overnight job is periodic: check in, read the night journal, and report to the human (“guiding held at 0.6 arcsec RMS, two frames lost to cloud at 01:40, the run is on schedule”) rather than intervening at 3 a.m.
Targets
Section titled “Targets”On-sky distance is not mount travel. Check a target with check_target_visibility before you suggest it.
Two targets close together on the sky can be a long way apart for the mount, on opposite sides of the meridian. check_target_visibility gives tonight’s altitude, transit, hours above 30 degrees in darkness and the moon’s distance for any position, so a suggestion arrives with the numbers that make it a good one.
Motion asks you first
Section titled “Motion asks you first”A motion request waits for the owner: say so, follow it with get_approval_status, and after a denial ask the human before you request again.
At Ask before motion, a motion tool (slew_to_target, home, park, unpark, start_sequence, resume_sequence) moves nothing when the agent calls it. The rig queues the request and sends it to your devices: what the agent asks for, where the target stands now, and the reason it gave. You approve or deny it in the ARIS app; no agent key can answer it, its own included. A request nobody answers expires after ten minutes. An agent has one request waiting at a time, and after you deny one it is told to ask you before it tries again.
Approving runs every check again at that moment: a target that has sunk under the rig’s altitude floor, a sequence that has started, a closed cover, a mount that needs homing after a power loss. Any of them refuses the approved request, and the agent is told why. A target under the altitude floor or below the horizon is refused before you are asked at all.
What the trust levels allow
Section titled “What the trust levels allow”| Level | The agent may |
|---|---|
| Watch only | Read: status, guiding, the sequence, the night journal, the latest frame, tonight’s visibility, the saved sequences in your Library. |
| Ask before motion | Also run autofocus, change filters, and pause or stop a sequence; and ask to slew to a target, home, park, unpark, start a saved sequence or resume a sequence, each waiting for your approval in the ARIS app. |
| Full autopilot | Also move the mount without asking: the same motion tools run at once (a saved sequence starts the way your Start button starts it), each through every limit the rig applies to your own taps, and the rig tells you what it did. |
Every agent starts at Watch only. Every write an agent makes, and every write it is refused, is recorded in the night journal with the agent’s name and the reason it gave; so is every motion request, and how it was answered. A refusal an agent keeps repeating is recorded once every ten minutes, with a count of the repeats, so a looping agent cannot crowd the night’s own events out of the journal. No level gives an agent raw axis moves, a sync, a pulse guide, a tracking rate, a site or time change, or a firmware, driver or limit setting.
On a rig that does not require sign-in on its network, the approval and trust routes are as open as every other control there, a slew included: the trust dial governs what an agent does through GUPPI, and a program with its own access to the rig’s network can call the rig’s API directly unless network sign-in is on.
Use this guide as a Claude skill
Section titled “Use this guide as a Claude skill”The guide above is also published as a skill, so an agent that loads skills reads the whole guide, not only the bold lines it receives when it connects. It is the same text, generated from this page, and the same note applies: it teaches craft, and the rig enforces the limits.
- Claude on the web or desktop: download aris-guppi-operator.zip, upload it in Claude’s skill settings (Customize > Skills), and turn it on.
- Claude Code: unzip it into your skills folder:
unzip aris-guppi-operator.zip -d ~/.claude/skills/. The skill file alone is SKILL.md.