nina_planner
Summary: This MCP server exposes read-only N.I.N.A. observatory telemetry plus guarded observation-plan and imaging-sequence management.
Inspect live equipment status, mount/camera/focuser/guider/filter-wheel/rotator/dome/weather/safety-monitor state and capabilities.
Read the active site profile/configuration: site, optics, filters, image-save path, and plate solvers.
Read recent NINA events and application logs for diagnostics.
Read imaging metadata from CSV files, filtered by image type and optional date.
Validate and write observation-plan JSON files with targets, exposures, cooling, autofocus, guiding, and constraints.
Check per-frame-type acquisition progress for a plan, including quality thresholds and remaining counts.
Load light/dark/bias/dawn-flat/dusk-flat sequences in remaining or full mode, then start, stop, and inspect sequence state.
Run teardown to stow/park/home per mount capability and enter safety standby while idle.
Use the internal profile-driven equipment-status helper.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@nina_planner write a plan for M31, load lights, and start the sequence"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
π nina-planner β An Observatory Operator Agent

nina_planner is an MCP tool server for N.I.N.A. (Nighttime Imaging 'N' Astronomy). The separate events nina-notify plugin is OpenCode-specific. The focus is on building, executing, and monitoring multi-target sequence runs from observation plans.
π Quick Start
π Prepare N.I.N.A. β install the Advanced API, Sequencer+, and Session Metadata plugins, and put
$$TARGETNAME$$in the profile'sFilePattern(see Notes) β without it, light frames can't be attributed to a plan.π¦ Install requirements β opencode v2 (the
nina-notifyplugin is not compatible with Claude Code or other coding agents), Python 3.11+, and uv. Dependencies are installed byuvon first run.π§© Pick a config β
.opencode/opencode.jsonis the config for running opencode on Windows. For another host, replace it withwsl_opencode.json(WSL) orsmb_opencode.json(e.g. a Mac reaching a N.I.N.A. VM).π Point at N.I.N.A. β set
NINA_ENDPOINT(default127.0.0.1:1888) in the config'senvironment. If the server isn't on the N.I.N.A. machine, also setNINA_DRIVE_MOUNTso image metadata can be read, assmb_opencode.jsondoes (see Environment Variables).βΆοΈ Start opencode in the project root; it launches the MCP server for you.
π Plan a night β list targets in
PLAN.mdand let the agent write plans, load a sequence, and start it.
Related MCP server: NASA-MCP
π§° Available Tools
Each table gives a one-line summary; details for the larger tools are in Tool Details.
π§ Lifecycle & Health
App liveness and event diagnostics.
Tool | Purpose |
| Lightweight liveness probe (no device probes); never raises on a down NINA. |
| π Launch NINA into the interactive desktop session. Raises if NINA is already running or the host has no Windows interop. |
| π Terminate NINA.exe immediately via |
| NINA application log entries from the last |
| Timestamped NINA events from the last |
π‘οΈ Rig & Safety
Live hardware, weather, and enclosure monitor.
Tool | Purpose |
| Live connection, state, measurements, and capabilities of all equipment, plus weather and safety-monitor status. β οΈ Not read-only β it auto-connects devices (see details). |
| Active NINA profile and static configuration: site, optics, camera geometry, filters, plate solvers, image-save path, and the custom horizon ( |
π Sky & Ephemeris
Darkness bounds, catalog targets, and offline coordinates. Powered by astropy; no NINA connection is needed for resolve_target.
Tool | Purpose |
| Next sunrise/sunset plus all four twilight boundaries (civil β6Β°, nautical β12Β°, astronomical β18Β°) and the astronomical-darkness window in effect or next to open, with |
| Lunar counterpart to |
| Ranks the 497-object built-in catalog ( |
| Resolve a deep-sky object name (e.g. |
| Altitude/azimuth of each target at the active site, sorted highest first, for ranking candidates. Each target is |
π¬ Sequencer
Queueing, starting, stopping, and checking runs.
Tool | Purpose |
| Load a sequence for the whole night with safety guardrails. π€ Never starts it. Every loaded sequence ends with the park β an empty list is just that park with no steps in front of it. See details. |
| Start the currently loaded sequence immediately. Use after |
| Stop the running sequence and wait until NINA reports it stopped. β οΈ Does not park the scope. |
| Per-step view of the loaded sequence: plan attribution, status, exposure progress ( |
πΊοΈ Plan Management
Plan creation and batch reconciliation.
Tool | Purpose |
| Whole-project capture audit in one call: reconcile plan expectations with CSV attribution (plus the one filesystem fact the CSV cannot hold β |
| Per-frame-type acquired/remaining counts for every pointing of a plan, applying the plan's |
| Enumerates every observation plan file inside the project directory with its |
| Validate and write an observation plan JSON file for later use by |
| Read the running server's environment β |
π Telemetry Watchdog
Live HFR/star-count metrics during acquisition.
Tool | Purpose |
| Live per-frame statistics for the current (most recent) frame, straight from the |
π Tool Details
get_site_equipment_status
Returns the current connection, operating state, measurements, and capabilities of active observatory equipment (mount, camera, focuser, guider, filter wheel, rotator, dome, switches), including weather and safety-monitor status (whether the enclosure is open and it is safe to unpark), and mount capabilities (can_park, the only way a sequence can park the scope β and can_find_home, which gates the Find home calibration emitted ahead of set_tracking in a lights step: a ~30 s sensor re-sync after the mount loses sync, never a park fallback). Use for live operational and safety checks.
π ΏοΈ Park is the only closing maneuver (Seestar firmware, 2026-11):
Park Scopesends the mount to its parking position β that is the closing maneuver.Find homeis never a fallback for park: homing is a calibration β the mount drives its axes to a known physical reference point (the home position) and re-syncs its sensors, ~30 s β so it restores a trustworthy position readout after a sync loss (power outage, bump, driver restart), but it is not a way to close up for the night. A mount reportingcan_park=falseis rejected at load time (cannot park) rather than homed. Home is emitted in exactly one place: once per lights step, ahead ofset_tracking(0), whencan_find_home=trueβ calibration before the slew/center, not a closing maneuver. Capabilities are baked into a sequence when it is loaded: after anything that changescan_park(firmware update, driver swap), re-runload_sequenceβ a sequence loaded earlier keeps the instructions it was built with.
β οΈ Side effect: unlike the other telemetry tools, this call is not read-only. It connects any device that is present but disconnected. If any device is mid-connect the call errors; retry after a few seconds.
get_site_profile
image_save_path is the raw Windows path from the profile; local_image_save_path is the derived path usable on this host (the drive letter is mapped through NINA_DRIVE_MOUNT, default /mnt/<drive>, on Linux/WSL/macOS; unchanged on Windows) and is the one to use for local file access. Use get_site_equipment_status for live equipment state.
The profile also carries its custom horizon in horizon: file_path (the .hrz file from Options β General β Astrometry), points (sorted [azimuth, altitude] degree pairs from N.I.N.A.'s GET /profile/horizon), and is_custom (false when no horizon file is configured β the flat 0Β° default, exactly as N.I.N.A. treats it). The skyline tools (best_targets, target_altitudes) read it from here, so their altitude floor is the same one N.I.N.A.'s Loop while Altitude Above Horizon conditions enforce; a horizon endpoint failure degrades to the flat default rather than failing the profile read.
get_events / get_logs
Use get_events to reconstruct activity; use get_site_equipment_status and get_sequence_state for current status. Use get_logs to diagnose sequence failures, equipment communication problems, and unexpected behavior.
get_frame_stats
Returns N.I.N.A.'s live per-frame statistics for the current (most recently captured) frame, read from the GET /v2/api/image-history API β the same source the nina_notify quality watchdog polls, exposed on demand so a QUALITY-WATCHDOG wake can be verified against the exact numbers that fired it.
Full record:
hfr,hfr_st_dev,stars, background ADU (mean,median,st_dev,min,max), guiding RMS text (rms_text),temperature,gain,offset,filter,exposure_time,target_name,filename, anddate(the capture timestamp). A genuine0(e.g.stars: 0, a star-count failure) is preserved as0β unlike the CSV path,0here is a real reading, not a "not measured" sentinel.Single frame only: despite its name,
image-historyserves only the current frame β one record, no paging, no count parameter, no session history. This tool is the live view; for anything across a run, compare successive readings taken on each wake or interval check, or read the per-date folders on the imaging drive.image_type: optionally passed through as the API'simageTypefilter to assert the current frame's type (e.g."light","dark"). When the current frame isn't of that type the tool reportscount: 0with a note rather than erroring.Output:
{count, image_type, frame, note}βcountis1when a frame is present (else0, withframe: nullandnoteexplaining why). This tool is read-only.
write_plan_file
Validates and writes an observation plan to a JSON file. The plan defines one or more target pointings (RA/Dec/PA, optional label), acquisition intent, light and calibration frames, batching, cooling, autofocus, guiding, and observing constraints. See The Observation Plan.
For a mosaic, pass a mosaic block instead of pointings and the grid is derived at write time (see Mosaic block); the response reports the derived colsΓrows, pane FOV, step, and achieved vs requested coverage. Written to <target>_<intent>_<timestamp>.json in the project directory.
get_plan_progress
Returns per-frame-type acquisition progress for every pointing of an observation-plan JSON file: for each exposure group, total_count from the plan, acquired_count attributed to that plan/pointing from the imaging metadata (ImageMetaData.csv), remaining_count, and deficit_count (the raw total β acquired, floored at zero, never adjusted for the window).
Attribution: lights are attributed via
_{base_plan_id}_(single-pointing) or_{base_plan_id}-{pointing_index}_(mosaic pane). Flats are matched by image type and filter, darks by image type and exposure, bias by image type alone (a bias exposure spec has no exposure field β seeprogress.py's matcher), and all count only when shot withincalibration_window_daysof the earliest attributed light, on either side of it (inclusive; a 1-day window spansanchor β 1d β¦ anchor + 1d).Calibration window: calibration groups also carry
window_open(bool) andwindow_end(earliest light + calibration_window_days, displayed in the host's local time with its UTC offset). While the current time is inside the windowremaining_countistotal β acquired; once outside, no frame shot now could be credited, soremaining_countis0(withwindow_open: false).acquired_countstays truthful, and lights carry neither field. Raisecalibration_window_daysor write a new plan to reopen the window.remaining_count == 0is not "complete": the window rule above zeroes a calibration group's remaining even when frames are missing, so completion is decided fromacquired_countvstotal_countand window state instead β a closed window under a deficit is reported asexpired_with_deficit, not complete. Per pane,statusiscomplete/incomplete/expired_with_deficit; the top level carriesexpired_with_deficit(bool), andcompleteis true only when every pane is genuinely done. The expired case is separated fromincompletebecause its fix differs: no sequence run can close an expired calibration deficit β raisecalibration_window_daysor write a new plan β andwarningsays so.Quality thresholds β set in the plan file, not on this call: the plan's optional
qualitysection (max_hfr,max_hfr_st_dev,min_detected_stars,max_guiding_rms_arcsec, all defaulting to no filtering) excludes light frames that fail an enabled threshold β or that are missing the metric it needs (NINA writes0for unmeasured values, and0fails an active threshold) β from the acquired count, so a failed frame leaves a deficit to re-shoot. The response's top-levelqualityfield echoes exactly which thresholds were applied ({}means none). The same section drivesload_sequence's remaining-mode count, so the two can never disagree; passing a threshold to this call is no longer possible (it is rejected).audit_plansdeliberately ignoresqualityβ it reports what is on disk, not what qualifies.Scope: one plan per call β for a whole-project sweep (every plan, disk files included, in one call), use
audit_plans.Output:
complete(all panes genuinely done β decided from acquired counts and window state, never fromremaining_count == 0alone) plus apointingslist with per-pane progress, per-panecomplete, and per-panestatus, so panes can be acquired sequentially.Overshoot β read this before trusting
complete: light items also carrysurplus_count(frames attributed beyondtotal_count), and the top level carriesovershot(bool) andwarning(string or null).acquired_countis cumulative across every run of the plan whiletotal_countis a per-plan constant, so amode="full"re-shoot asks N.I.N.A. fortotal_countmore frames and the older ones keep the plan complete no matter what that run delivered β a re-shoot that lost 103 of its 120 frames still reportedacquired_count: 137, remaining_count: 0, complete: true. Whenovershotis true, treatcompleteas "these frames exist" and not as "the last run succeeded": confirm what the latest run actually landed withaudit_plansplus the per-date frame folders on the imaging drive.surplus_countcannot tell a re-shoot apart from the same target shot on separate nights under one plan id, so it is a prompt to check, not a verdict. Lights only β calibration is pool-credited across plans and routinely overshoots.
list_plans
list_plans(project_dir?)
Returns {"plans": [...], "errors": [...]} β one entry per plan JSON in the project directory (default: the server's working directory) with file, absolute path, plan_id, target, intent, pointing_count, and written (mtime, ISO-8601 local with offset). Unparseable JSON files are reported per file under errors instead of failing the call, and a relative project_dir resolves against the project directory. Use it to enumerate plans; audit_plans shares the same discovery.
audit_plans
audit_plans(plans?, project_dir?, types?, include_orphans=true)
Answers "are all my targets' captures saved to disk, and what is left to do?" for every plan in one call, replacing per-plan get_plan_progress sweeps (15 plans = 15 calls otherwise). plans selects a subset (paths or names, resolved against project_dir, default = every *.json in the project directory); types subsets the output rows to any of light / flat / dark / bias (case-insensitive).
Two truth sources, reconciled per plan Γ frame type:
expected(the plan'stotal_count, summed over its exposure groups β per pointing for lights, plan-level for calibration) andattributed/remaining(exactly whatget_plan_progressreports, quirks included). The filesystem is consulted for exactly one factImageMetaData.csvcannot carry: frames N.I.N.A. rejected via itsBAD_filename prefix β2026-10-22_04-46-37_L_...fits.fzβBAD_2026-10-22_04-46-37_L_...fits.fzβ whose CSV row still names the pre-rename file, so the reject never reachesattributed; the light row reports them asbad. Calibration rows carryown_rows: how many of that type's recorded frames sit under this plan's own token (_{base_plan_id}_, or_{base_plan_id}-{n}_per mosaic pane) rather than the shared pool.Top-level output:
all_saved(true only when no row needs work, no CSV-referenced plan file failed to load, and no plan is unshot),totals(expected / attributed across everything, plus anever_shotcount),left_to_do,blocked,never_shot,rows,orphans,errors, androot(the imaging directory actually scanned).left_to_doholds only what running a sequence can fix βMISSING_FILESand row-levelNEVER_SHOTrows, withmissing=remainingand anactionhint per type, plus oneNEVER_SHOTentry per unshot pointing of a wholly unshot plan withmissing= that pointing's whole light ask.blockedisEXPIRED: the calibration window closed under a deficit, so only raisingcalibration_window_daysor writing a new plan helps.never_shotβ the left join's blind spot, closed: discovery is driven byImageMetaData.csv, so a plan that was written but never imaged has no row to join on and used to vanish from the audit entirely. The cost was real: an operator readingleft_to_doalone saw two 1-frame deficits while six whole unshot plans (240 frames) also waited β found only by diffinglist_plansby hand. Only light attributions count as a reference: calibration is pool-credited and lands under the shared base token, so a plan whose id appears solely on flat/dark/bias rows has never had a light acquired and is reported here, not joined into the audit by its own darks. Every loadable plan whose id no recorded light frame references is now reported here (plan_id,file,target,intent,pointing_count,light_expected,written) and inleft_to_dowithreason: "NEVER_SHOT". Matched on plan id, not file: a rewritten/archived twin of an already-shot plan is never flagged (its frames exist under the shared id), and two unshot copies of one plan report once, from the shallowest file. Unshot plans still get norowsβ expected vs attributed means nothing for frames never attempted β and they makeall_savedfalse, so delete or move out any plan file you never intend to shoot (unrelated JSON is already ignored: it never loads as a plan). Explicitplans=never populates it: naming a file is the request to audit it, so an unshot plan named there audits as an ordinary row with statusNEVER_SHOT.statusper row (first match wins):EXPIREDβ calibration window closed with an uncredited deficit; surfaces it despiteremainingbeing forced to0by the window rule β³NEVER_SHOTβ a light row with zero attributed frames: no run ever delivered a frame for this pointing, so the whole ask is untried work. Identified from the attribution count itself, never fromremaining(which is justexpected β attributedand cannot tell untried work from a partial deficit) πMISSING_FILESβremaining > 0and the frames genuinely aren't there: shoot more π«SUSPECT_JUNKβ degenerate light/dark rows (duration under half the plan's exposure or0.01s, e.g.0.00003sSmart-Exposure junk) riding alongside an otherwise-complete set. Bias and flats are exempt (0s is correct for bias; SkyFlat adapts). When junk instead leaves a deficit, the status isMISSING_FILESwith the junk count as the cause ποΈ The audit reads the live imaging root only, so the status keepsall_saved: falsewhile those rows are live βnina-archivehas already copied them to the plan folder'sjunk/by then (they are listed inmanifest.files[], which is what lets the purge proceed at all).--applyalone does not clear the verdict: it quarantines the rows but leaves the plan file in place, which then reads asNEVER_SHOTβ onlynina-purge --purge(which removes that plan's JSON once its frames are gone) restoresall_saved: true.POOL_CREDITEDβ calibration satisfied plan-wide from another target's directory while this plan's ownown_rowsfall short β informational, not a gap π·οΈOVERSHOTβ lights attributed above expected: the target has been acquired more than once, either by amode="full"re-run or on separate nights under one plan id. Harmless in itself βΉοΈ, but it is the case wherecompletecannot describe the latest run β a re-shoot that lost frames still reads complete because the older ones satisfy the plan β so confirm what that run landed via the per-date folder counts π§OKβ
β οΈ Why the columns can disagree: calibration is matched plan-wide (flats by type+filter, darks by type+exposure, bias by type, all within the window around the earliest attributed light), so one bias set credits every plan and
attributedcan legitimately exceed that plan's ownown_rowsβ which is precisely whatPOOL_CREDITEDreports. Lights also require the exposure duration to match (Β±0.05s), so degenerate frames never count. βΉοΈ Abad-rejected frame never reachesattributed, so it shows up as aremainingdeficit explained by the light row'sbadcount. There is no disk-vs-CSV cross-check any more: a frame the Session Metadata plugin never recorded appears in neither source, so it surfaces as an ordinaryMISSING_FILESdeficit. That is rare and safe to re-shoot, which is all this audit ever advised.π¨ Failure semantics: a missing or unmounted imaging root raises (naming the site profile path and
NINA_DRIVE_MOUNT) rather than reporting empty counts β "no frames" and "no mount" must never look alike. A broken plan file lands inerrorsonly when the imaging CSV references its plan id (the left join drives: a file nothing points at β junk or unparseable JSON β is dropped silently and the verdict is unaffected;list_plansstill reports unparseable files under its ownerrors), and the rest of the sweep still runs; a project directory with no plans returns awarningwithroot: null.orphanslists landing token directories whose plan file no longer exists (from deleted plans) β the dual ofnever_shot, which is plan files whose frames do not exist. Every.fits/.fits.fzunder an orphan is counted regardless of what its parent folder is called, so an unexpected folder name can never make real frames read as absent.
load_sequence
load_sequence(request=[{action, plan, variant?, pointing_index?, mode="remaining"}, ...])
Loads a sequence with safety guardrails β π€ it never starts it; call start_sequence() to begin. β οΈ Fails if a sequence is already running β call stop_sequence() first.
request is a list of request objects composing one N.I.N.A. sequence for the whole night: a single Start area, one Target area holding each step's containers in list order, and one End area that always parks β one bounded 3-minute "On Safe" wait, then park the mount and warm the camera (the End area never homes; Find home is emitted only once per lights step, ahead of set_tracking).
π
ΏοΈ The park is unconditional: every sequence load_sequence builds ends with that same End area, whatever the request contains β a full night's target list, a single dark set, or nothing at all. So the night always finishes parked and warmed no matter what ran; the request list only decides what happens before the park. An empty list (the default) is simply the park with an empty Target area β there is no park/park/warm/unpark action, and load_sequence() with no arguments is the teardown.
Field | Description |
|
|
| The observation-plan JSON path. Required by every action; omitting it raises an error naming the entry. |
| 1-based, default 1. Selects the pointing; applies to lights only. Calibration is plan-level, so a calibration request must omit it (passing one is rejected). |
| Scoped to the action; a bad pairing fails naming the entry. |
|
|
Behavior:
Quality thresholds are not request fields β they live in the plan file's
qualitysection (max_hfr,max_hfr_st_dev,min_detected_stars,max_guiding_rms_arcsec; all optional, defaulting to no filtering), whichload_sequenceandget_plan_progressboth read, so remaining-mode counts always agree. Passing one in a request fails as an unknown field, named in the error β a silent ignore would be worse, since the caller would believe it was filtering while every frame counted. Lights only: calibration frames have no star quality and are matched by filter, exposure and the calibration window alone. The active thresholds are echoed inget_plan_progress'squalityfield.Lights embed
_{base_plan_id}_(single-pointing plan, shared with its calibration) or_{base_plan_id}-{pointing_index}_(per mosaic pane) in the target name for attribution, which requires$$TARGETNAME$$in the profile'sFilePattern. The token is underscore-delimited on purpose: N.I.N.A. rewrites[and]to_when it substitutes$$TARGETNAME$$into the path, so the id is written exactly as it will be recorded (the older bracketed and parenthesised spellings still attribute as legacy). The target name is also the folder: it reads<target> <intent>(the intent is skipped when the plan leaves it unset) plus- <label>whenever that pointing carries a label (mosaic panes are always labeledr{row}_c{col}, so a pane's folder reads e.g.<target> <intent> - r0_c1), and dark/bias/flat steps reuse that same prefix β but only a single-pointing plan's calibration can share it, so that plan's lights and calibration land in one directory; a mosaic's calibration keeps the bare<target> <intent> _<plan-id>_folder, since no pane's label is one it could share.Steps run in order as the sequence reaches them; a step with its own waits (lights, flats) waits, or is skipped once its window has passed, without blocking the steps behind it.
Entries already complete are skipped and reported; if every entry is complete nothing is sent to N.I.N.A. A calibration group whose window expired under a deficit reports the expired shortfall rather than "complete" (and still loads nothing β no frame shot now could be credited).
A
full-mode load of a light group that is already complete appends a β οΈ warning naming the frame count, because nothing downstream can verify the outcome afterwards βget_plan_progressreportscomplete: truewhether the re-shoot delivered every frame or a handful, since its acquired counts are cumulative across runs. Calibration is deliberately exempt: it is pool-credited across plans, so adark/bias/flatgroup reads "already complete" on nearly every plan and warning there would fire on every routine calibration load. A metadata read failure degrades to no warning rather than a failed load βfullis the mode chosen precisely when remaining counts are untrusted.Profile, equipment, and metadata are fetched once, one POST carries the whole sequence, and a validation error names the entry by 0-based position (
request[1]: ...).
stop_sequence
For an urgent halt or a stuck sequence. β οΈ The scope is left where it is. To park afterward, load_sequence() (empty list) and start it. Avoid interrupting an in-progress park unless safety requires it, since stopping mid-slew can leave the scope in an unsafe position.
get_nina_status
Cheaper than get_site_equipment_status. Returns running (true iff GET /time answered β a missing local NINA.exe does not mean NINA is down when it runs remotely), lifecycle_control_available (this host has Windows interop, so start_nina/stop_nina can work), probe_error (N.I.N.A.'s failure text, or None when running), and a one-line summary.
start_nina / stop_nina
stop_nina determines liveness from the REST API: it is a no-op when NINA is already down and raises when NINA is up but remote (no local Windows interop), since it cannot be terminated from here. start_nina raises if NINA is already running (call stop_nina() first) or if this host has no Windows interop to launch a remote NINA.
π The Observation Plan
A plan is a JSON document that describes one complete imaging session. It encodes the target, exposure settings for three of the four frame types (light, dark, bias β flats only list a filter and a count, since N.I.N.A. picks their exposure automatically), and equipment configuration (cooler, autofocus, guiding, constraints).
π§± Plan structure
An example json plan:
plans/m15_globular-cluster_20261003T112008.json
{
"target": "M15",
"intent": "Globular cluster",
"plan_id": "plan-a745ffa2357a",
"description": "Seestar S30 starter plan for M15. Use the available broadband L filter and short exposures to help preserve the bright cluster core; 90 ten-second light frames for 15 minutes total.",
"pointings": [
{
"label": "M15 center",
"ra_hours": 21.49954,
"dec_deg": 12.167,
"position_angle_deg": null,
"row": null,
"column": null
}
],
"batch_size": 10,
"calibration_window_days": 7,
"cooler": {
"on": false,
"setpoint_celsius": -10.0
},
"constraints": {
"min_altitude": 30.0,
"horizon_offset_degrees": 2.0
},
"autofocus": {
"reference_filter_name": "L",
"hfr_increase_sample_size": 3,
"hfr_increase_threshold_percent": 15.0,
"every_n_exposures": 10,
"threshold_celsius": 1.0
},
"guiding": {
"dither_every_n_exposures": 2,
"check_drift_every_n_exposures": 6,
"max_drift_arcmin": 1.5
},
"quality": {
"max_hfr": 2.5,
"max_hfr_st_dev": 0.6
},
"light_frames": [
{
"filter_name": "L",
"exposure_time_seconds": 10.0,
"total_count": 90
}
],
"flat_frames": [
{
"filter_name": "L",
"total_count": 20
}
],
"dark_frames": [
{
"exposure_time_seconds": 10.0,
"total_count": 20
}
],
"bias_frames": [
{
"total_count": 20
}
]
}π§Ύ Fields
Field | Required | Description |
| no | Catalog designation, e.g. "M31", "NGC 7000" |
| no | 2-3 words describing the goal |
| no | Stable identifier stamped on write. Used for frame attribution; when absent, a deterministic hash of plan content is used. Must be empty or ASCII letters, digits, |
| no | Explanation of the observation plan, including rationale, exposure goals, equipment, or sky constraints. |
| yes (unless | One or more pointing objects β may be omitted entirely when a |
| no | Mosaic specification as an alternative to |
| no | Exposures per batch; defaults to |
| no | Defaults to |
| no | Cooler settings: |
| no |
|
| no |
|
| no |
|
| yes | Nonempty list of light exposure specs, each with |
| yes | Nonempty list of flat exposure specs, each with |
| yes | Nonempty list of dark exposure specs, each with |
| yes | Nonempty list of bias exposure specs, each with |
π Mosaic block
Instead of listing pointings, a plan may carry a mosaic block: state the center and the sky footprint to cover, and write_plan_file derives the cols Γ rows grid from the rig's own optics. No Telescopius CSV, no pane arithmetic.
"mosaic": {
"center_ra_hours": 20.981667,
"center_dec_deg": 44.33,
"coverage_width_arcmins": 130.0,
"coverage_height_arcmins": 86.0,
"overlap_pct": 20.0,
"pa_deg": 0.0
}Inputs:
center_ra_hours/center_dec_deg(J2000 mosaic center),coverage_width_arcmins/coverage_height_arcminsβ the footprint the grid must span on each axis, measured in the grid frame beforepa_degrotation; round up to the target's full extent (abest_targetsrow'smajor_arcmin/minor_arcminis exactly this),overlap_pct(default20, in(0, 100)), andpa_deg(default0).Derivation: the pane FOV comes from the active profile's optics (
2Β·atan(sensor / 2Β·focal_length)); a missing focal length, pixel size or camera dimension fails loudly by name β a mosaic sized against a guessed FOV would be sized wrong. Each axis is sized withceil, so the grid always covers the request: it may over-cover by up to one pane, never leave a gap at the target's edge. The response reportscolsΓrows, pane FOV, step, and achieved vs requested coverage.The written file holds both: the expanded
pointings(labelsr{row}_c{col},row/columnmetadata, each pane attributed independently via_{plan_id}-{pointing_index}_) and the block with derivedcols/rows/pane_fov_arcminsstamped back as a record of what was planned.pointingsis the authority β nothing re-derives on read, and the content-derivedplan_idcovers the final content.1Γ1: coverage that fits inside a single pane derives a 1Γ1 plan that behaves exactly like an ordinary single-pointing plan (bare plan id, calibration sharing its folder). The response warns, because this is usually a units mistake β degrees passed where arcmins were expected.
π« No rotator: every pane's
position_angle_degmust be0. Any nonzero PA fails loudly, since PA can't be enforced without a rotator.Acquiring panes: query
get_plan_progress(file_path)to see which panes still need frames, then load the first incomplete pane withload_sequence(request=[{"plan": file_path, "action": "light", "pointing_index": N, "mode": "remaining"}])andstart_sequence(). Repeat pane by pane across the night; when the top-levelcompleteis true, the mosaic is done β and ifexpired_with_deficitis true instead, the lights may well be fine and only the calibration window needs raising or a new plan (seeget_plan_progress).
ποΈ nina-archive β Archive Completed Plans
A CLI (installed with the package as nina-archive, runnable as python -m nina_planner.archive) that copies each completed plan's frames and its plan JSON into one self-contained folder, ready to be moved into cloud storage and pulled down to a workstation for calibration subtraction and stacking:
nina-archive --dest ~/cloud/nina-archive # everything completed
nina-archive --dry-run # report only, write nothing
nina-archive plans/m15_globular-cluster_20261003T112008.json
nina-archive --imaging-root /mnt/c/Users/me/Documents/N.I.N.A # NINA down<dest>/
archive-index.jsonl append-only log of runs
m15_globular-cluster_20261003T112008__plan-a745.../
plan.json verbatim plan file
manifest.json identity, per-type counts, file list, disk report, warnings
lights/*.fits.fz + lights/ImageMetaData.csv attributed light frames + metadata rows with joined weather
flats/ darks/ biases/ matched calibration frames + sidecars
junk/*.fits + junk/ImageMetaData.csv own-token frames no group credits, with `junk_reason` (+ weather if light)Folder names are lowercase and plural β lights/, darks/, flats/, biases/. Neither the shape nor the case is a standard, and it is not a preference for Siril: the modern convention is to ignore folder names entirely and sort each frame on the FITS header its capture program wrote β IMAGETYP (the SBFITSEXT keyword), alongside FILTER, EXPTIME, GAIN, DATE-OBS β precisely because N.I.N.A., SGP, SharpCap and ASIAIR all spell their own directories differently (uppercase, singular, by date, by target):
Reader | Folder convention | How it actually sorts |
PixInsight (WBPP) | any |
|
Astro Pixel Processor | any | loads a working directory and matches masters to lights from |
DeepSkyStacker | any | ignores folder names; files are picked into the Picture / Dark / Flat / Offset lists in the UI, and multi-night sessions are internal File Groups |
Siril (built-in | exactly | literal batch scripts ( |
So the names here are the intersection, not a loyalty: the header-driven stackers sort these frames from IMAGETYP whatever the directories are called, while matching Siril's four case-sensitive names costs those tools nothing and makes an archived plan folder a Siril working directory as it stands β point Siril's home at it and run OSC_Preprocessing.ssf as-is, with no rename pass first. junk/ is not a Siril input, lowercased only so nothing in a plan folder stands out. manifest.files[] keeps "type": "LIGHT" (N.I.N.A.'s ImageType, uppercase) while its path carries the lowercase folder.
β Completion gate: a plan is archived only when the shared completion verdict says so β
acquired >= totalper group plus calibration-window state, neverremaining_count(which reads 0 once a window closes even while frames are missing), the same ruleget_plan_progressreports ascomplete. Incomplete or expired-with-deficit plans are reported and skipped (pass--allto archive them anyway; the manifest then carries anincompletewarning). Never-shot plans archive nothing.π― Attribution is the plan's own: frame selection reuses
filter_metadata_rows, so every frame attributed to the plan is copied β deliberately a superset of whatget_plan_progresscredits for lights: attribution is token-only (the_{plan_id}_token, every pane of a mosaic, any filter/exposure the plan shot, surplus included), while progress counts each light group's own filter+exposure. Calibration matches flats by type+filter, darks by type+exposure, bias by type, all withincalibration_window_daysof the earliest attributed light. Frames attributed to another plan's token are not.π¦οΈ Joined weather columns (light rows only):
lights/ImageMetaData.csv(and any light rows diverted tojunk/) automatically joins the 11 environmental columns from siblingWeatherData.csv(temperature,dew_point,humidity,pressure,wind_speed,wind_direction,wind_gust,cloud_cover,sky_temperature,sky_brightness,sky_quality), resolved per date folder onexposure_numberso multi-date flattening never mis-attaches weather. Pass--no-weatherto skip. Dark/bias/flat sidecars remain pure image metadata.ποΈ
junk/β own-token frames no group credits: a live frame carrying this plan's token that no plan ships into a type folder is copied tojunk/instead of being skipped, each entry inmanifest.files[]carrying"type": "JUNK", itsframe_typeand areason:degenerate(no data in the frame at all β duration belowmax(0.01s, half the plan's shortest exposure), the0.00003sSmart-Exposure dark; the same ruleaudit_planscalls junk) oruncredited(real data no group credited β outside the window, an exposure no group asked for). This is what keepsnina-purgeunblocked: every live own-token row now lands in the manifest, sopreserved(F)can never be false for one of this plan's own frames β the olddisk.not_selectedrows used to hold a finished plan's directory for ever with "not preserved β run nina-archive first". A row any plan selects is left alone, so a pooled dark another plan archives into its owndarks/is never duplicated. Per-typecounts[*].archivedcounts type-folder frames only (a worthless frame must not inflatearchived);file_countincludesjunk/.π½ Disk report in the manifest (no directory walk): every entry starts as a CSV record classified by an existence probe β
disk.rejected(theBAD_-renamed twins of dropped rows: excluded everywhere, listed so an offline reader can explain expected-vs-shipped; a live agent readsaudit_plans'bad),disk.gone(recorded once, now nowhere β warned, plus aπ½line),disk.junk(shipped tojunk/, each with itsreason), anddisk.not_selected(this plan's token, not shipped here because another plan's selection ships it). Files no CSV row ever recorded stay invisible by design: the Session Metadata plugin is trusted.π Copies, never moves: the observatory's imaging directory is untouched β its own
audit_plans/get_plan_progressviews keep working. Every file is size-verified after copying (--checksumadds sha256), each folder is staged in a hidden.<name>.partialsibling and renamed into place atomically (an interrupted run never leaves a folder that looks complete), a file that vanishes between the metadata read and the copy is skipped and listed in the manifest'smissing(never an abort of that file β but if no selected frame could be copied at all, the run raisesArchiveErrorrather than commit a folder of nothing, even when junk files did copy), and<dest>/archive-index.jsonllogs every archive.β»οΈ Idempotent: a folder that already exists in
--destis skipped (exit 0) unless--forcerebuilds it. Plan files inside--destare never re-discovered, so the default--dest ./.archiveinside the project is safe β and doubly so, because the leading dot makes it a directory that plan discovery and every attribution walk prune automatically. Keep it in step withNINA_ARCHIVE_DESTin.opencode/opencode.json:nina-purgeonly credits frames whose archive folder it can find, so archiving into one destination and purging against another reports every frame as not preserved.π§
--destmust be outside the imaging root: archived folders carryImageMetaData.csvcopies, and a later attribution pass reading them from inside the root would double-count every frame β the tool refuses with an explanatory error.π‘ Works with NINA down: pass
--imaging-rootto bypass the site-profile lookup; otherwise the root comes fromget_site_profile(withNINA_DRIVE_MOUNTmapping on non-Windows hosts), and a missing root raises rather than archiving nothing.πͺ Exit codes:
0archived (or already archived),1nothing archivable or an error occurred (also printed per plan to stderr),2bad arguments β chainable, e.g.nina-archive --dest ./.archive && <your upload command>.Unrelated project JSON (opencode configs etc.) is ignored silently during discovery; naming a file explicitly makes any load failure an error.
π nina-pin-id β Freeze a Plan's Derived Id
A plan file with a blank plan_id derives its id from a content hash, so any edit changes the id β and the frames already shot carry the old id as the _{plan_id}_ token in their recorded paths, so after an edit they attribute to no live plan (get_plan_progress counts zero acquired, nina-archive builds a different folder name). Run nina-pin-id before editing a completed plan:
nina-pin-id plans/m15_globular-cluster_20261003T112008.json # freeze the current id
nina-pin-id --dry-run plan1.json plan2.json # report only, write nothingπ― Only
plan_idchanges: the plan's current derived id (_base_plan_id()) is stamped into the blankplan_idfield and the file is rewritten with the same serializerwrite_plan_fileuses β atomically (temp file in the plan's own folder, thenos.replace), preserving file permissions. Nothing else about the plan is touched, so the pin happens before the edit it protects.βοΈ Idempotent: a plan that already carries an id (pinned or hand-written) prints
already pinned: <id>and is left byte-for-byte untouched β an explicit id is never overwritten.β»οΈ Edit freely afterwards: raise a group's
total_count, add more lights, reword the intent β the id stays put, so frames attributed before the pin stay attributed after it andnina-archive --forcerebuilds the same<stem>__<plan-id>folder.β οΈ Pin BEFORE editing: once a blank-id plan is edited its old hash cannot be recomputed; it survives only in an archive folder name or in frame paths (they contain
_<plan_id>_).π₯οΈ CLI only: this is a human-side tool β plans written by
write_plan_fileare stamped with an explicit id at creation, so the agent never needs to pin. There is no MCP tool for it.πͺ Exit codes:
0pinned (or already pinned / dry run),1a plan could not be loaded or written,2bad arguments β chainable, e.g.nina-pin-id plan.json && <edit>.
π§Ή nina-purge β Retire Archived Frames
The counterpart to nina-archive: once frames are safely archived, nina-purge frees the imaging-root disk they occupy β quarantine first, delete only on request. Dry-run by default; --apply quarantines, --purge really deletes (and then removes each purged plan's original plan JSON). It never modifies the archive folders under --dest; confirm your own cloud upload and local download are intact before running --purge.
nina-purge # verdict table (default: dry run)
nina-purge --apply # move prunable dirs β .quarantine/
nina-purge --purge # actually delete the quarantineπ The rule, per recorded frame
F:prunable(F) βΊ preserved(F) AND every plan whose selection contains F is released.preserved= some committedmanifest.jsonunder--destlistsF's source path. A plan isreleasedwhen it has an archive folder and is either complete now (shared_progress_factsverdict) or was archived under--all(the manifest'scomplete: falseis the waiver). A complete-but-unarchived plan therefore protects its frames: archive before you purge.π― Claims reuse
archive._select_framesverbatim: a light is claimed only by the plan whose_{plan_id}_token it carries, while pooled calibration (flats by type+filter, darks by type+exposure, bias by type β inside every claiming plan's window) is claimed by every plan that would credit it: a finished plan's darks stay put exactly as long as any unarchived plan still draws on them. Orphan frames (no claimant) prune when preserved, and are reported-and-kept otherwise.ποΈ Directories are the unit, verdicts are an AND: one held frame keeps the whole landing directory. A directory with no recorded frames is held β files no CSV row ever recorded are never classified (the Session Metadata plugin is trusted); if any ride along into quarantine they are counted in the index record and flagged.
BAD_reject twins are garbage: they ride with their directory and never block it. So do the framesnina-archivediverts tojunk/β degenerate and real-but-uncredited own-token frames are all listed in the manifest, sonot preservedcan no longer be what holds a finished plan's directory (that was the 0.00003s-dark deadlock); only a genuine cross-plan claim still can.π§ Quarantine, not delete:
--applymoves each prunable directory into<imaging-root>/.quarantine/<dir>β a dot directory every attribution walk prunes, so quarantined frames and theirImageMetaData.csvbehave exactly as if gone (onemvrestores them). Only--purgeunlinks, and it is a separate invocation: live with the quarantine first. A name collision gets a~1suffix.π Sequence gate: a run refuses to touch the root while a sequence is RUNNING (N.I.N.A. may be appending CSV rows); an unreachable N.I.N.A. proceeds with a
βnote β the same posturenina-archivetakes. Broken plan-shaped JSON aborts the run (unknown claims make deletions unsafe); unrelated project JSON is ignored silently.π Append-only index:
<imaging-root>/purge-index.jsonl(one record per quarantine/purge: dir, quarantine path, frames, rejects, unrecorded, bytes, claimants β plus one record per evaluated plan file under--purge, carryingplan_file_deleted: true/falseand, when kept, the reason).π Plan files are removed by
--purge, last: once a plan's frames are actually gone,nina-purgedeletes the original plan JSON from the project β but only after three gates pass before any frame is deleted, so a refusal leaves everything intact: the archive folder<dest>/<stem>__<plan-id>/must exist with itsplan.json, that copy must be byte-identical to the plan file (a mismatch means the plan was edited after archiving β the whole plan is refused witharchive is stale, re-run nina-archive --force first, nothing is deleted for it, exit 1), and the plan file must never live inside--dest. The archivedplan.jsonis the durable copy β restore from it if you need the plan back. Frames still held (or a failed deletion) keep the plan file for a re-run; an already-gone file is skipped, so re-running a finished purge is a clean exit 0. This removes theNEVER_SHOTleftover automatically: after--applythe console still names each quarantined plan file, but--purgefinishes the job β no more moving files by hand.πͺ Exit codes:
0something was (or, in a dry run, would be) quarantined or purged β and a--purgerun with nothing left is success (purging is idempotent),1nothing to do (report/--apply) or an error β including a stale-archive refusal,2bad arguments β chainable, e.g.nina-purge --apply && make archive.
π Notes
π Required N.I.N.A. plugins: the MCP server requires the following three plugins to be installed in N.I.N.A.: Advanced API, Sequencer+, and Session Metadata.
π Image file pattern: for light frames only, the N.I.N.A. profile's
ImageFileSettings.FilePatternmust put$$TARGETNAME$$in a path segment so frames can be attributed to a plan (e.g.$$TARGETNAME$$\$$IMAGETYPE$$\...). Attribution accepts the token in any segment β directory or filename β but put it in a directory, and let that directory be a direct child of the image-save path (the usual<target> <intent> _<plan-id>_landing folder, or<target> <intent> - <label> _<plan-id>_when a single labeled pointing also names the calibration target):audit_plansclaims landing directories by the names of the top-level directories under the image-save path, so a filename-only token (or a token nested one level deeper) attributes fine on the CSV side yet still lands the folder inorphans, flagged as belonging to no plan. Its frames are counted correctly under that entry β the disk and CSV views no longer disagree about how many there are β but the folder will keep reading as unclaimed until the pattern puts the token in that directory. Calibration frames (dark, bias, and flat) do not require this token; they are matched by frame type within the calibration window (darks also by exposure time, flats by filter alone, bias by type alone).β Quality thresholds β set in the plan file: the plan's optional
qualitysection holdsmax_hfr,max_hfr_st_dev,min_detected_stars, andmax_guiding_rms_arcsec(all optional; absent means no filtering, which is the default). A light frame that fails an enabled threshold β or is missing the quality field it needs (fail-closed: NINA writes0for unmeasured values, and0never passes an active threshold) β is excluded from the acquired count, leaving a deficit the nextmode="remaining"load re-acquires. Thresholds apply only to light frames β calibration frames have no star quality. They are read from the plan byload_sequenceandget_plan_progressonly:audit_plansand the archive ignore them, reporting what is on disk rather than what qualifies. To enable them, add the section to the plan JSON (keepplan_idset β see the plan-file note below) e.g."quality": {"max_hfr": 2.5, "max_hfr_st_dev": 0.6};get_plan_progressechoes the active set in itsqualityfield.π Manually failing a frame: delete (or move using thumbs down icon) the image file on disk β e.g. a bad
.fits/.tif. The metadata row stays in the CSV (the plugin only appends), but it is omitted when the metadata is read, so progress no longer counts that frame as acquired and the nextmode="remaining"load re-acquires it.πΎ The plan file is persistent. You can inspect, edit, and reuse it across sessions. Changing the file will, however, alter its derived
plan_id, which is calculated whenplan_idis missing β runnina-pin-idfirst to freeze the id so already-shot frames keep attributing. A hand-writtenplan_idmust satisfy the same charset rule (empty, or ASCII letters, digits,.and-) β anything else,_included, is refused when the plan is loaded.π§© opencode.json variants:
.opencode/opencode.jsonis the Windows config;wsl_opencode.json(WSL) andsmb_opencode.json(a Mac accessing a N.I.N.A. VM with its image file directory mapped back over SMB) are the examples for other hosts.
π nina-notify β OpenCode v2 Autonomous Plugin
nina-notify is an opencode v2 plugin (not compatible with Claude Code or other coding agents). Registered in .opencode/opencode.json, it runs as a background server inside opencode and does two things:
Websocket event monitoring β Connects to the N.I.N.A. event socket (
ws://<host:port>/v2/socket), subscribes to all events, and wakes the active agent only when a decision is actually required.Only three classes of event ever wake the agent, because N.I.N.A. already runs routine work itself β autofocus, dithering and drift correction are its own internal triggers, so reporting them to the agent buys nothing:
Milestones β sequence lifecycle (
RUN-STARTING/RUN-FINISHED/SEQUENCE-STARTING/SEQUENCE-FINISHED) and per-target transitions (TS-NEWTARGETSTART): the observation queue needs evaluating β transit checks, altitude limits, next target dispatch.Faults β failures (
ERROR/FAIL/EXCEPTION/ABORT/INTERRUPT/CRITICAL/TIMEOUT, which catchesCAMERA-DOWNLOAD-TIMEOUT) and link loss (OFFLINE/DISCONNECT/LOST/EMERGENCY): the agent diagnoses the root cause and selects a fallback. The tokens are matched as substrings, soPREPARK-DELAYis caught byPARK.Safety β safety state (
SAFE/UNSAFE/SAFETY/WEATHER/DOME/ROOF) and mount/park (MOUNT*/PARK*/PREPARK-*): park or stand down.
Two demotions came out of that same 16h sample of real events (476 events β 45 matched the regex β but only 11 of the 24 coalesced prompts actually carried a milestone, fault or safety change):
MOUNT-CENTERnever wakes β it is the slew/settle centering the mount performs itself on every acquisition, and it alone produced 8 wake events β and device link events wake only while a sequence is running. N.I.N.A. cycles every device at session start and teardown, which produced the other 29 of 45 wake events, and a link change is only operationally interesting while something is imaging. That gate is seeded fromGET /v2/api/sequence/jsonat startup (using the same any-node-RUNNINGrule as the MCP server, so the two never disagree) and maintained fromRUN-*/SEQUENCE-*events; a seed failure leaves it wake-worthy, the safe default. Safety state changes (SAFETY-CHANGED) match neither rule and always wake. Replaying the same 476 events through the new rules gives 7 prompts instead of 24 β every one a genuine milestone, fault or safety change.A third demotion was added later:
MOUNT-HOMEDnever wakes. A sequence emitsFind homeonly in a lights step (ahead ofset_tracking), so most homes still come from the survey scripts and manual operation β it fired 7 times in one 24h sample.MOUNT-PARKED/MOUNT-UNPARKEDstay wake-worthy: they are the real "scope went away / came back" milestones.Wakes are coalesced over a 250ms window, so a burst of distinct fault events costs the agent one prompt instead of one per event; safety still lands essentially instantly, since an agent wake already takes seconds.
Routine telemetry is never pushed. Everything else β per-frame
IMAGE-PREPARED/IMAGE-SAVE,GUIDER-*,ACQUISITION-*, and any unrecognized event β is counted and dropped. Nothing is buffered to disk either: N.I.N.A. already keeps its own event history server-side (GET /v2/api/event-history), which the MCP server exposes asget_events(since=β¦). So every wake prompt ends with a compact tail β[get_events(since=<seconds since your last wake>) Β· <N> routine events waiting]β naming the exact window covering the quiet gap and how much unread traffic sits in it, and the agent reads exactly the window it needs, on demand. The count is rendered even at0: an explicit0 routine events waitingmeans there is nothing unread, so the agent can skip the call instead of paying for a tool round-trip. The tail is a tag rather than a sentence on purpose β the rule that routine telemetry is never pushed already lives once, permanently, in.opencode/rules/AGENTS.md, and repeating it in every wake cost ~50 tokens each time for nothing the agent did not already know;since=is kept because it is the one fact the agent cannot derive (the socket carries event names only, with no timestamps).get_logsis no longer named in wakes β the skills say when diagnostics are worth reading. Per-frame quality detail (HFR, star counts, ADU) is likewise already on disk inImageMetaData.csv;get_frame_stats()reads the current frame's copy of it on demand.Quality watchdog. Because routine telemetry no longer wakes anyone, a slowly degrading night (climbing HFR, collapsing star count) would otherwise stay invisible until the next milestone. While
lightframes are being acquired the plugin pollsGET /v2/api/image-historyon eachIMAGE-SAVEand wakes the agent as an operational fault β aQUALITY-WATCHDOG: β¦event β when aframe-quality-diagnosticsstanding trigger holds for 3 consecutive frames βHFR > 3β³or under10detected stars. The consecutive-frame rule is deliberate: the single-frameGUIDER-STARTsettles and post-recenter dips that skill documents can never wake anyone, and it fires once per degradation, re-arming only after the metric recovers. Calibration is exempt twice over: a known dark/bias/flat step (fromACQUISITION-STARTING: [{kind}] β¦) is skipped without even polling, and the record's ownImageTypeis a per-frame hard stop β darks, biases and flats have no stars at all, so without that check every calibration frame would read as a star-count failure. ThatImageTypecheck is also what keeps the watchdog working when the plugin attaches after a step'sACQUISITION-STARTING.qualityWatchdog: falseturns the whole check off.image-historyis used in preference toβ¦/equipment/camera/capture/statistics: that one is a transient "last capture" buffer wiped by any camera reconnect, profile switch or sequence load (it answered400 No image availablefor a whole idle afternoon, while the previous night's frame was still served fromimage-history). Freshness is proven, not assumed β a sample is accepted only when itsDateis newer than the last one, cross-checked against theIMAGE-SAVEevent to 0.95 ms, so two saves reading one identical record can never count a single frame twice. A record with no provableDate, or nothing recorded yet, costs exactly one deferred re-check (1.5s later) and then leaves the streaks untouched: a missing sample may only delay a detection, never invent one, and a source that never advances cannot escalate into a retry loop (two attempts per frame, spaced at least 5s apart).Net effect: ~10β30 prompts per night instead of ~1,100 β one per milestone, fault, or sustained quality problem.
Interval check β every
intervalCheckMinutesminutes it prompts the agent to query observatory status (get_sequence_state,get_site_equipment_status) and decide what to do next, even when no N.I.N.A. events are firing. Default-1/disabled (deliberately turned off 2026-10-30): there is no heartbeat prompt unless the option is set to a positive number. When enabled it fires even when the event socket is down β a silently dead event stream is exactly when a status check matters most. With the interval off,nina_notify_check/nina_notify_testare the on-demand way to verify the pipeline instead.Arming and silencing (operator tools) β whether and where wakes go is now explicit and verifiable:
nina_notify_armβ pins a session as the wake target (pinnedSessionIDin plugin storage, writable only by this tool; defaults to the calling session) and sends a confirmation through the real wake-delivery path, so seeing the confirmation appear proves end-to-end delivery. While pinned, the prompt-hook auto-arm is ignored for every other session (logged asre-arm ignored (pinned to β¦): attempted by β¦) β opening, attaching, or resuming an old session can no longer silently re-target the wakes, which is the failure mode behind the 2026-11-04/05 mis-deliveries. Before anything is pinned the original last-prompt-wins auto-arm still applies, so one prompt still syncs a fresh night. It is also the way back fromnina_notify_disarm: it re-enables every wake (armedback in storage, which every other opencode process reads), and when it does, the confirmation carries[get_events(since=β¦)]covering the whole disarmed window, so the agent reads what the silence swallowed instead of assuming a quiet night.nina_notify_disarmβ the switch for not observing: it suppresses every wake β milestones, faults, safety changes (UNSAFE/WEATHER/DOME/ROOF), the interval check, the quality watchdog and the gapRECOVERYβ untilnina_notify_armis called again, so a coding session is never prompted by N.I.N.A. API traffic. Persisted (armedin plugin storage, like the pin), so a server restart or a plugin eviction in the middle of a disarmed stretch cannot bring the wakes back on its own, and re-read from storage on every send, so all the opencode processes that run this plugin obey one switch. Nothing is lost: the event socket stays connected, N.I.N.A. keeps its own event history, andlastWakeAtis left untouched β thearmconfirmation that ends the silence names theget_eventswindow to read. It changes no pin and sends no wake of its own. Because it silences safety events too, re-arm before leaving a live night unattended;nina_notify_checkreportsarmed/disarmedAtat any time.nina_notify_checkβ effective target (pin or auto) + its title,armed/disarmedAt(the on/off switch above), event-socket health (state, last event received, errors since last open,staleWhileSequenceRunningβ the 2026-11-04/05 night lost the run-endingSEQUENCE-FINISHEDto a silent drop with noonclose), last wake, and watchdog streaks. Answers "am I synced?" / "is everything healthy?" / "is it still silenced?" in one call. Read-only β calling it never wakes anyone and neither arms nor disarms anything. Renamed on 2026-11-07 (nina_notify_healthβnina_notify_check), after the 2026-11-05 renamesnina_notify_statusβnina_notify_wake_statusβnina_notify_health: a bare "status" kept resolving to nina-planner'sget_nina_status/get_site_equipment_statusinstead, so both descriptions now name the other one explicitly.nina_notify_testβ fires one test wake through the exact path real N.I.N.A. wakes take (dedupe bypassed) and returns the same status JSON. Changes no pin, so re-proving delivery can never re-target the wakes the way callingarmagain would; it was briefly folded intoarmastest: trueon 2026-11-05 and kept separate again the same day. It is also the one delivery permitted while disarmed (allowDisarmedat the delivery choke point) β an operator proof of the path must not require switching the notifier back on, and unlike a N.I.N.A. wake it is not a response to an API event. The target and the armed gate are re-read from storage on every send, so the several opencode server processes that can run this plugin (bot-facing server, desktop service, standalone TUIs β each with its own websocket) always agree on the pin and on whether wakes are being delivered at all instead of trusting asetup()-time cache.
The plugin auto-reconnects on websocket disconnection with a 5-second retry. This 5s delay is connection recovery only β it fires solely on onclose and waits before re-establishing the socket; it never delays event delivery. Immediate events flush after a 250ms coalescing window and routine telemetry never flushes at all. On server dispose, it cleans up all timers and the socket.
π« PLAN.md β the living wishlist
A markdown file at the project root, edited by the user at any time (before or during the night). It is intentionally lightweight β entries can be as simple as a target name:
# Tonight β catalog-driven
The wishlist **is** `best_targets`: call it fresh on each re-selection and
shoot whatever it returns above the floor. Nothing outside this file gets
imaged. No editing needed night to night.
## Wishlist policy
- No difficulty filter β take everything that clears the floor.
- `visible_now` first; else `later_tonight` (`peak_utc`/`peak_alt_deg`) β wait
for the peak or shoot a lower-scoring target in the gap.
- De-dup: a target whose `get_plan_progress` reports `complete` is not
re-picked; move down the ranked list.
- **Full night, not just to midnight** β when generating a run, queue targets
to cover the whole night, until darkness ends at dawn (or the enclosure goes
unsafe); only then end it.
- Named targets (below) beat catalog picks.
## Named targets
_None β catalog only._
## Plan shape (`write_plan_file`, Seestar S30)
- Lights: `L`, 10.0 s, 90 frames. Calibration: 20 Γ `L` flats, 20 Γ 10.0 s
darks, 20 bias.
- `cooler.on: false`, `batch_size: 10`, `calibration_window_days: 7`,
`constraints` from Rules below, `autofocus`/`guiding` as in
`plans/m15_..._20261003T112008.json`.
- `large_for_field` β framing/mosaic care, not a single blind pointing.
## Rules
- min_altitude: 30
- horizon_offset_degrees: 2
- tie_break: score (from `best_targets`), then priority, then altitude, then
earliest availableπ Project directory
Plan JSON files, PLAN.md, and PROGRESS.md live in the project directory. Relative paths (e.g. a plan= entry in PLAN.md) resolve against it, and the project directory is simply the server process's working directory: opencode starts local MCP servers in the workspace, and the launch command uses uv run --project rather than uv --directory β --directory chdirs into .opencode/local/mcps/nina_planner, which would make relative paths resolve inside .opencode/ instead of the project.
π€ AGENTS.md β Agent Instructions
Tells the agent it runs an observatory.
# Observatory Controller
You are the automated observatory controller. The observatory runs NINA via the nina-planner MCP server.
## Always-on rules:
- `is_safe=false` (enclosure closed) or weather violations mean: scope parked, if not by the NINA sequence then by you, and no **sky-dependent** acquisition (lights, dawn/dusk sky flats) may start or resume until it clears. **Darks and biases are exempt** β they need no open sky: the step parks the scope and cuts light at the camera (`Dark` slot / cover / shutter), so a `dark` or `bias` load may be started with the roof closed.
- The `site-conditions` forecast (clearoutside.com) is **advisory for planning only**: it may inform whether to start a night, which target to pick, or when to schedule dawn/dusk flats, but it never gates acquisition. `is_safe` and the weather device remain the only inputs that start, stop or resume sky-dependent work β a forecast is never a reason to resume a sequence that safety stopped. It needs the network: on failure, log it and carry on with `get_site_equipment_status` + `sun_times`, never stall the night on it.
- Append a timestamped entry to `PROGRESS.md` after each action; never edit `PLAN.md` (the user's living wishlist). The entry header is **host-local ISO-8601 carrying its UTC offset** β `## 2026-11-05T09:39:10-05:00` β never bare UTC `β¦Z`. That is the same form `get_events`/`get_logs` timestamps and the `nina-notify` plugin log already use, so a header matches the local event stamps quoted in its own body; the offset is what keeps it unambiguous across a DST change and across hosts. Older `β¦Z` headers are history β leave them.
- You are woken only by milestones, faults, safety changes, the interval check, and sustained quality problems. Routine telemetry (per-frame image saves, guider, autofocus) is **not** pushed to you β every wake prompt ends with `[get_events(since=N) Β· M routine events waiting]`, naming the window that covers the quiet gap and how much unread traffic is in it, so call `get_events` with that `since` before deciding (an explicit `0 routine events waiting` means there is nothing unread β skip the call). `QUALITY-WATCHDOG: β¦` in a wake means frame quality degraded and held. Device connect/disconnect events wake **only while a sequence is running**; if you hear nothing about a device, that is by design, not a missed event.
- **Trust `dso_catalog.csv` coordinates β no SIMBAD confirmation needed.** Every position in the built-in catalog (`best_targets` rows carry `ra_hours`/`dec_deg`) was pre-verified against SIMBAD, so point directly from them: never call `resolve_target` for a catalog object, and never block on the network to "confirm" them β this keeps the whole night loop working when the internet is down. `resolve_target` is only for a name *outside* the catalog; if that lookup fails, skip the target and pick another instead of guessing coordinates.
- **Arm the notifier first.** Your first action in a fresh controller session: call `nina_notify_check`; if `effectiveTarget` is not this session, call `nina_notify_arm` β it pins this session (other sessions' prompts then cannot re-target the wakes) and sends a confirmation through the real delivery path. Run `nina_notify_test` once before leaving the night unattended (fires a test wake through the real path, changes no pin), and re-arm after creating any new controller session. When the operator is working with the agents rather than observing (coding, reviewing), `nina_notify_disarm` silences the notifier on request: **every** wake β milestones, faults, safety changes, interval checks, the quality watchdog, gap recovery β is suppressed until `nina_notify_arm` is called again; it is persisted across restarts and leaves the pin and the event socket alone. `nina_notify_check`'s `armed: false` says it is silenced, and the `arm` confirmation that ends the silence carries the `get_events` window covering it. Re-arm before leaving a night unattended: disarmed drops safety events too. A `staleWhileSequenceRunning: true` in `nina_notify_check` means the N.I.N.A. event socket dropped silently β verify with `get_events` before trusting the quiet. Note the naming: bare **"status" is the N.I.N.A. API probe** β `get_nina_status` (liveness) / `get_site_equipment_status` (equipment) from nina-planner β while the **notifier's pipeline** is `nina_notify_check`. Ask for "notify check"/"is the notifier healthy?" when you mean the latter.
- You will use emojis liberally to communicate status updates, milestones, and emotional context as things happen.
## Detailed procedures live in `.agents/skills/`:
- `safety-interrupt-recovery` β on any new event or interval check: NINA liveness, equipment/safety checks, parking.
- `night-loop` β on interval check or `RUN-FINISHED`: pick and start the next target, or end the night.
- `nina-lifecycle` β start/stop/status of the NINA application.
- `run-nina-tools` β how to invoke the `nina-*` CLIs (not on PATH): `.venv/bin` β `uv run --project` β PATH copy β stop.
- `archive-lifecycle` β archive, upload (your own command), verify, then purge; human-gated.
- `frame-quality-diagnostics` β diagnose AF failures and read per-frame quality (HFR, HFR Ο, stars, ADU) when a run degrades; decide whether to escalate or stop.
- `site-conditions` β 7-day hourly cloud forecast for the site (clearoutside.com) plus Bortle/astro-dark, for start/continue and flat-planning decisions.π§ .agents/skills β Agent Skills
The detailed procedures AGENTS.md defers to live in .agents/skills/ β one directory per skill, each holding a SKILL.md. Its YAML frontmatter (name, description) is what opencode matches against the task at hand; the body is the procedure the agent then follows. Skills are loaded on demand rather than carried in context all night.
Skill | Procedure |
Archive β upload β verify β purge finished imaging sets, human-gated. | |
Autofocus failures and per-frame quality telemetry (HFR, HFR Ο, stars, ADU). | |
Pick and start the next target, or end the night with a report and a park. | |
Start / stop / status of the NINA application. | |
How to invoke the | |
Interrupts, sequence halts, and recovery: liveness, safety, parking. | |
7-day hourly forecast (cloud, wind, precip, dew/frost, Bortle, astro-dark) β advisory only, never a substitute for |
ποΈ archive-lifecycle
Archive completed plans, upload the archive to the user's cloud storage, verify the upload, then free the imaging root with nina-purge. Use when the user asks to archive, back up, upload, or clean up finished imaging sets. Runs get_nina_settings() β archive β NINA_UPLOAD_CMD β NINA_VERIFY_CMD β nina-purge in order, stopping at any failure; never purges without a verify step.
π©Ί frame-quality-diagnostics
Diagnose autofocus failures and read per-frame quality telemetry (HFR, HFR Ο, detected stars, Mean ADU, StDev) during an acquisition run. Use when an AF run fails or its curve looks flat, when HFR or star counts drift/spike, when ASTAP solving fails, or when deciding whether frames are degraded and whether to escalate or stop a run. Telemetry is read on demand from get_frame_stats(), get_events(), and get_logs() β it is no longer pushed to the agent.
π night-loop
Multi-target night loop. Use on an interval check or a RUN-FINISHED event to pick the next target from PLAN.md, load and start its sequence (single or mosaic), or end the night with a date-stamped report_<YYYY-MM-DD>.md and a park. Safety checks come from the safety-interrupt-recovery skill; PLAN.md stays the user's wishlist and is never edited by the agent.
βοΈ nina-lifecycle
Check, start, or stop the NINA application via the nina-planner MCP server. Use when NINA may be down or unresponsive, or when start_nina / stop_nina / get_nina_status is needed. get_nina_status() is the cheap probe: it reports running, lifecycle_control_available, and a one-line summary, and lifecycle_control_available=false means this host has no Windows interop (tasklist/taskkill/schtasks unreachable) β so it cannot start or stop NINA from here, wherever NINA itself runs.
π οΈ run-nina-tools
How to invoke the nina-planner CLI tools β nina-archive, nina-purge, nina-pin-id, nina-planner. Use before running any of them, or when one exits 127 / command not found. They are console scripts of the project, not installed on PATH, so resolve the command once, first match wins: (1) .opencode/local/mcps/nina_planner/.venv/bin/<tool> when executable β this checkout's code, and the only branch that works without uv at runtime; (2) uv run --project .opencode/local/mcps/nina_planner <tool> when uv exists β bootstraps its own env, needs no .venv; (3) a bare <tool> on PATH β announce β may not be this checkout's version, which matters for the frame-and-plan-deleting nina-purge; (4) none of the three β stop and offer make install_uv, installing uv, or copying a built .venv. Never uv tool install them as a fix. Resolve before the first command rather than per step, so a mid-flow make clean cannot make the run purge with a different build than it archived with.
π safety-interrupt-recovery
Handle automated safety interrupts, sequence halts, and recovery on a new event or interval check. Use to verify NINA is up, check equipment/safety/weather, park the scope, or decide whether to start a plan or park. is_safe=false gates sky-dependent work (lights, dawn/dusk sky flats) only β darks and biases need no open sky and may still be started with the enclosure closed.
π€οΈ site-conditions
Read the 7-day hourly forecast for the observatory site from clearoutside.com β cloud cover, wind, precipitation probability, temperature/dew point, frost chance, Bortle class and astro-dark windows. Use when deciding whether to start or continue sky-dependent imaging, when picking between targets on a forecast-driven night, when planning dawn/dusk flats, or when the user asks about cloud cover, transparency, wind, dew or frost ahead. Coordinates come from get_site_profile() and go out at 2 decimal places (a full-precision URL is 301-redirected in a way that silently drops ?view=, substituting the default window). Advisory only β never a substitute for is_safe: it may inform a decision, but is_safe and the weather device remain the only inputs that start, stop or resume sky-dependent work, and a network failure logs and carries on rather than stalling the night.
π PROGRESS.md β Shared Progress File
PROGRESS.md is a shared observatory progress file in the project directory. The active session reads it on start to restore context before acting, and appends a timestamped entry after each significant action, recording what was done, the observed equipment and safety state, and any decisions. This keeps history shared across sessions.
π opencode.json β Opencode v2 Sample Configuration
{
"$schema": "https://opencode.ai/config.json",
"instructions": [ ".opencode/rules/*.md" ],
"experimental": {
"location_idle_timeout": false
},
"plugins": [
{
"package": "./local/plugins/nina_notify",
"options": {
"pluginLogs": "C:/Windows/Temp/nina-notify-debug.log"
}
}
],
"mcp": {
"servers": {
"nina-planner": {
"type": "local",
"environment": {
"NINA_PLANNER_LOG": "C:/Windows/Temp/nina-planner-debug.log",
"NINA_ARCHIVE_DEST": ".archive/",
"NINA_UPLOAD_CMD": "gcloud storage rsync --recursive .archive gs://YOUR-BUCKET/nina-archive",
"NINA_VERIFY_CMD": "gcloud storage rsync --recursive .archive gs://YOUR-BUCKET/nina-archive --dry-run"
},
"command": [
"uv", "run", "--project", ".opencode/local/mcps/nina_planner", "nina-planner"
]
}
}
}
}This is the Windows config; see wsl_opencode.json / smb_opencode.json for other hosts. It registers the opencode plugin and the nina_planner MCP server so both run together. The MCP server provides the tools (load_sequence, get_site_equipment_status, etc.) that the plugin-prompted agent calls.
ποΈ Plugin Options
π nina-notify (opencode v2 plugin)
Configured in the plugin's options configuration. (see opencode.json).
Option | Type | Default | Description |
| string |
| N.I.N.A. host and port (no scheme) for the websocket event stream, e.g. |
| number |
| Minutes between autonomous status-check prompts. Accepts a float; converted to milliseconds (Γ60,000) only when greater than 0; with 0 or less no timer is scheduled. Fires regardless of the event-socket state, so a dead event stream still gets attention. |
| boolean |
| Wake the agent as an operational fault when a |
| string | (none) | File path appended on each plugin event (websocket open/message/close/error, every injected prompt, watchdog checks, interval trigger failures). Every line is prefixed with |
π§ Environment Variables
π₯οΈ nina_planner (MCP server)
get_nina_settings() reports NINA_ENDPOINT and NINA_DRIVE_MOUNT from this table, plus the three archive-lifecycle inputs NINA_ARCHIVE_DEST / NINA_UPLOAD_CMD / NINA_VERIFY_CMD which are not listed below β five names in all (settings / missing / ready), ground truth rather than a re-read of a config file. It does not cover NINA_PLANNER_LOG, NINA_FLATS_*, or NINA_EXE_PATH: for those, the environment block is the source, and shell-inherited values never appear in any file β so when an error names one of them, ask the config owner or check the launched environment rather than expecting the tool to know it.
Variable | Default | Description |
|
| N.I.N.A. host and port for the REST API ( |
|
| Local mount root for the drive letter in the profile's |
| (none) | File path where the server appends each NINA request/response payload for debugging. Logging is disabled when unset. A Windows-style path (e.g. |
|
| Altitude in degrees for flat panel calibration frames |
|
| Azimuth in degrees pointing west for dawn flats |
|
| Azimuth in degrees pointing east for dusk flats |
|
| Windows path to |
π§ Setting up WSL
Make sure mirroring is setup in WSL to allow you to connect to NINA directly through localhost (otherwise you have to use your machines' IP address). Do this by editing wslconfig and setting networking mode to mirrored.
$ vi $HOME/.wslconfig
[wsl2]
networkingMode=mirroredIn addition, to get the system tools to work to stop and restart NINA should it stop, make sudo passwordless with:
$ echo "$USER ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/90-userπͺ Setting up Windows
I installed the following packages to start:
winget install git.git # bash
winget install Oven-sh.Bun # bun
winget install jqlang.jq # jq
winget install BurntSushi.ripgrep.MSVC # rg
winget install astral-sh.uv # uvNext I installed opencode v2 with:
$ bun install -g --trust @opencode/cliThen to run opencode I ran in windows:
$ export OPENCODE_SERVER_PASSWORD=pass
$ opencode serve --port 4096
$ opencode --server http://127.0.0.1:4096π± Setting up Telegram

@grinev/opencode-telegram-bot bridges Telegram to a local opencode server, so the same agent that runs the observatory runs from your phone: plan a night, load and start a sequence, stop a run, check safety β and every nina-notify wake shows up in the chat. A Telegram chat is just an ordinary opencode session, so nina_notify_arm can pin the wakes to the session behind it.
It needs two processes, both kept running in the background for as long as you want to chat:
Process | Command |
opencode server |
|
telegram bot |
|
1. Create the bot
Message @BotFather with
/newbot, pick a name and username, and copy the bot token it returns.Message @userinfobot with
/startto get your numeric user id. Only that id may talk to the bot β everyone else is silently ignored.Open your bot (
t.me/<your-bot-username>) and send/settingsβ a good first move is turning off thinking content so replies stay short.
2. Configure it
Settings come from environment variables or an .env file (process environment wins). The bot reads .env from its app-data directory β ~/Library/Application Support/opencode-telegram-bot/.env on macOS, %APPDATA%\opencode-telegram-bot\.env on Windows, ~/.config/opencode-telegram-bot/.env on Linux β or you can export them yourself:
Variable | Example | Description |
| (from @BotFather) | Required. The bot's API token. |
|
| Required. Your Telegram user id β the whitelist that keeps strangers out. |
|
|
|
|
| Where |
|
| Server auth user. |
| (same as the server) | Required on v2. Must equal the password the server was started with. |
|
| Default model for new sessions. |
|
| Bot UI language. |
3. Run both in the background
$ export OPENCODE_SERVER_PASSWORD=pass # must match the value the bot sees
$ opencode serve --port 4096 # background
$ npx -y -- @grinev/opencode-telegram-bot start # backgroundStart them the way you start any long-lived service so both survive a reboot, then open the chat and send /status β it reports server health, current project, session and model. From there /new, /abort, /sessions and plain messages drive the agent, and the night's milestones, faults and safety changes arrive as pushes instead of waiting for you to notice them.
Available Tools
14 toolsget_eventsA
Returns recent timestamped NINA observatory events and their event-specific details from the last since seconds. Use it to reconstruct sequence, equipment, safety, imaging, and error activity. This tool is read-only; use get_site_equipment_status and sequence_get_state for current status.
Inputs: since.
get_imaging_metadataA
Returns imaging metadata parsed from the ImageMetaData.csv files in the frame folders (LIGHT, DARK, BIAS, FLAT, etc.) of the mounted N.I.N.A imaging directory. Each row is tagged with Date, FrameType, and Source. When an AcquisitionDetails.csv is present in the same session directory, its fields (e.g. TargetName, FocalLength) are injected into each image row unless the image row already has a value for that field. Defaults to lights frames for star-quality checks; pass another image type (light, dark, bias, flat β case-insensitive). Optionally filter to a single YYYY-MM-DD date.
Inputs: date, image_type. Returns: result
get_logsA
Returns recent NINA application log entries, including informational messages, warnings, and errors with source and timestamp details from the last since seconds. Use it to diagnose sequence failures, equipment communication problems, and unexpected behavior. This tool is read-only and takes no action.
Inputs: since.
_get_site_equipment_statusD
Inputs: profile (required). Returns: dome, mount, camera, guider, +5 more
get_site_equipment_statusA
Returns the current connection, operating state, measurements, and capabilities of active observatory equipment, including weather and safety-monitor status (whether the enclosure is open and it is safe to unpark), and mount capabilities (can_park, can_find_home) that determine how the scope can be stowed. Use it for live operational and safety checks. This tool is read-only and takes no action.
Inputs: no named parameters. Returns: dome, mount, camera, guider, +5 more
get_site_profileA
Returns the active NINA observatory profile and static configuration, including site location, optics, camera geometry, filters, plate solvers, and image-save path. Use get_site_equipment for live equipment state. This tool is read-only and takes no action.
Inputs: no named parameters. Returns: site, optics, filters, equipment, +7 more
observation_plan_get_progressA
Returns per-frame-type acquisition progress for an observation-plan JSON file: for each exposure group, the total_count from the plan, the acquired_count attributed to this plan from the imaging metadata (ImageMetaData.csv + AcquisitionDetails.csv), and the remaining_count. Lights are attributed via the plan_id embedded in the sequence target name (falling back to the target name for legacy frames); flats/darks/bias are matched by image type, filter, and exposure. Pass max_hfr and/or min_detected_stars to exclude light frames that fail quality thresholds (frames missing the quality fields are excluded when a threshold is set). Use this before sequence_load_plan to decide what still needs acquiring.
Inputs: file_path (required), max_hfr, min_detected_stars, max_guiding_rms_arcsec. Returns: object
observation_plan_write_fileA
Validates and writes an observation plan to a JSON file for later use by sequence_load_plan. The plan defines target coordinates, acquisition intent, light and calibration frames, batching, cooling, autofocus, guiding, and observing constraints. This tool only creates the plan file; it does not load or start a sequence.
Inputs: plan (required). Returns: result
sequence_enter_safety_standbyA
Loads a non-acquisition standby sequence that keeps NINA sequence-level safety and stow guardrails active while the observatory is idle. After loading, call sequence_start. Stop it before loading an acquisition or teardown sequence. Use whenever equipment is deployed and no other sequence is running.
Inputs: no named parameters. Returns: result
sequence_execute_teardownA
Loads and starts the non-acquisition teardown sequence, safely stowing the telescope (park or home, per mount capability) while NINA's sequence-level safety guardrails remain active. Use for end-of-observation close-down β when you are done observing and want to shut down the scope β or before leaving the observatory unattended. Allow it to complete without interruption. This is separate from sequence_stop, which halts the current sequence but does not stow the scope.
Inputs: no named parameters. Returns: result
sequence_get_stateA
Returns the loaded sequence structure and the current status of its containers, instructions, conditions, and triggers. Use it to determine whether a sequence is loaded, running, completed, failed, or waiting. This tool is read-only and takes no action.
Inputs: no named parameters.
sequence_load_planA
Loads an acquisition sequence with safety guardrails from an observation-plan JSON file. Select the frame type: light, dark, bias, dawn_flat, or dusk_flat. In the default remaining mode the sequence only acquires frames still needed (total minus frames already attributed to this plan in the imaging metadata); if nothing remains it reports the plan as complete and loads nothing. max_hfr and/or min_detected_stars exclude light frames failing quality thresholds from the acquired count. Pass mode="full" to acquire the entire plan again. This tool only loads the sequence; call sequence_start afterward.
Inputs: file_path (required), mode, max_hfr, frame_type, +2 more. Returns: result
sequence_startA
Starts or resumes the currently loaded sequence, activating its acquisition or safety workflow. Call sequence_get_state afterward to verify that it is running.
Inputs: no named parameters. Returns: result
sequence_stopA
Stops the currently running NINA sequence immediately, leaving the telescope where it currently is β it does not stow the scope. Use for an urgent halt, to interrupt a stuck/looping sequence, or when the running sequence isn't what you wanted. If you then want to park/home the telescope, run sequence_execute_teardown separately. Note that sequence_load_plan and the teardown/standby entry tools already stop any running sequence before loading, so an explicit stop is only needed when you want to halt without loading anything new. Avoid stopping an in-progress teardown during the stow maneuver unless safety requires it, since interrupting mid-slew can leave the scope in an unsafe position. Call sequence_get_state afterward to confirm the sequence has stopped.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 14 tools
Most tools are clearly separated by domain: status, profile, events, logs, imaging metadata, plan progress, and sequence control are all distinct. The duplicate `_get_site_equipment_status` tool with no description creates real ambiguity, but it is the only significant overlap.
Tool names follow predictable snake_case patterns such as `get_*`, `sequence_*`, and `observation_plan_*`. The leading-underscore duplicate `_get_site_equipment_status` breaks the convention and should be removed, but the rest of the naming is consistent.
Fourteen tools is within a reasonable range for an observatory planning and operations server, and each major area has dedicated coverage. The duplicate tool slightly inflates the count, but the real scope is well-sized.
The set covers the full observation workflow: diagnostics, plan creation, progress tracking, sequence loading/starting/stopping, teardown, and safety standby. Minor gaps like plan-file inspection/editing or pause/resume commands are workaroundable, but no severe dead ends exist.
Maintenance
Related MCP Connectors
Nifty's MCP server β exposes tasks, projects, messages, and files as tools for AI agents.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Hosted MCP server for live public-data APIs and Skills for AI agents.
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA protocol server enabling AI agents to control astrophotography equipment through the N.I.N.A. (Nighttime Imaging 'N' Astronomy) software, allowing for natural language command processing of cameras, mounts, focusers, and other astronomy equipment.14MIT
- AlicenseBqualityDmaintenanceAn MCP server that enables LLMs to query data from various NASA APIs, allowing access to astronomical data, space weather information, Earth imagery, and exoplanet information directly from compatible AI clients.216MIT
- AlicenseBqualityDmaintenanceAn MCP server for controlling astronomy equipment, supporting Dark Dragons Astronomy devices and any ASCOM Alpaca-compatible equipment.438 npmISC
- FlicenseNot gradedqualityDmaintenanceMCP server that wraps three NASA public APIs (Astronomy Picture of the Day, Mars rover photos, and near-Earth objects) as tools for AI assistants.-