Skip to main content
Glama

πŸ”­ nina-planner β€” An Observatory Operator Agent

Banner for repository

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

  1. πŸ”­ Prepare N.I.N.A. β€” install the Advanced API, Sequencer+, and Session Metadata plugins, and put $$TARGETNAME$$ in the profile's FilePattern (see Notes) β€” without it, light frames can't be attributed to a plan.

  2. πŸ“¦ Install requirements β€” opencode v2 (the nina-notify plugin is not compatible with Claude Code or other coding agents), Python 3.11+, and uv. Dependencies are installed by uv on first run.

  3. 🧩 Pick a config β€” .opencode/opencode.json is the config for running opencode on Windows. For another host, replace it with wsl_opencode.json (WSL) or smb_opencode.json (e.g. a Mac reaching a N.I.N.A. VM).

  4. πŸ”Œ Point at N.I.N.A. β€” set NINA_ENDPOINT (default 127.0.0.1:1888) in the config's environment. If the server isn't on the N.I.N.A. machine, also set NINA_DRIVE_MOUNT so image metadata can be read, as smb_opencode.json does (see Environment Variables).

  5. ▢️ Start opencode in the project root; it launches the MCP server for you.

  6. 🌟 Plan a night β€” list targets in PLAN.md and 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

get_nina_status()

Lightweight liveness probe (no device probes); never raises on a down NINA.

start_nina()

πŸš€ Launch NINA into the interactive desktop session. Raises if NINA is already running or the host has no Windows interop.

stop_nina()

πŸ›‘ Terminate NINA.exe immediately via taskkill. A no-op when NINA is already down.

get_logs(since=300)

NINA application log entries from the last since seconds, for diagnosing failures. Read-only.

get_events(since=300)

Timestamped NINA events from the last since seconds, to reconstruct sequence, equipment, safety, imaging, and error activity. Read-only.

πŸ›‘οΈ Rig & Safety

Live hardware, weather, and enclosure monitor.

Tool

Purpose

get_site_equipment_status()

Live connection, state, measurements, and capabilities of all equipment, plus weather and safety-monitor status. ⚠️ Not read-only β€” it auto-connects devices (see details).

get_site_profile()

Active NINA profile and static configuration: site, optics, camera geometry, filters, plate solvers, image-save path, and the custom horizon (horizon: file_path, is_custom, sorted [azimuth, altitude] points; is_custom: false = flat 0Β°). Read-only.

🌌 Sky & Ephemeris

Darkness bounds, catalog targets, and offline coordinates. Powered by astropy; no NINA connection is needed for resolve_target.

Tool

Purpose

sun_times()

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 night_phase (evening/dark/morning) and is_dark_now for end-of-night decisions. Read-only; reads only the site profile.

moon_times()

Lunar counterpart to sun_times(): phase (name, illumination_fraction, waxing, elongation_deg, age_days) plus current altitude/azimuth/distance, moon_up_now, the next moonrise/moonset (48 h window), and the next new_moon/first_quarter/full_moon/last_quarter instants (~32 d window). Phase instants are geocentric and identical everywhere; rise/set are topocentric for the site. Read-only; offline; reads only the site profile.

best_targets(min_altitude=30.0, top=10, level, kinds, horizon_offset_degrees=2.0)

Ranks the 497-object built-in catalog (dso_catalog.csv β€” Messier, NGC and IC entries plus a handful of open clusters) to observe, returning visible_now (dark and above the floor now) plus later_tonight (peak altitude within astronomical darkness that also clears the floor), with is_dark_now and surface-brightness-based difficulty filtering. The floor is horizon-aware β€” alt >= max(min_altitude, horizon(az) + offset) using the profile's custom horizon, so visible_now never contains a target N.I.N.A. would park on; rows carry horizon_deg/clearance_deg. Each row carries pre-verified (SIMBAD-checked) ra_hours / dec_deg β€” use them directly for pointing, no resolve_target needed, so this works offline. Read-only.

resolve_target(name)

Resolve a deep-sky object name (e.g. M31, NGC 6960) to J2000 ra_hours / dec_deg through a SIMBAD lookup. 🌐 Requires internet access. Read-only.

target_altitudes(targets, hours_ahead=0.0, min_altitude=0.0, horizon_offset_degrees=2.0)

Altitude/azimuth of each target at the active site, sorted highest first, for ranking candidates. Each target is {"name", ...} plus optional ra_hours / dec_deg (pass the pre-verified values from a best_targets row; without them the name is resolved via SIMBAD β€” needs internet). Rows carry horizon_deg (the profile's custom skyline at that azimuth), clearance_deg (alt βˆ’ horizon), and above_floor (alt >= max(min_altitude, horizon + offset) β€” the floor N.I.N.A.'s loop conditions enforce; pass the plan's min_altitude to gate on it). Read-only.

🎬 Sequencer

Queueing, starting, stopping, and checking runs.

Tool

Purpose

load_sequence(request=[...])

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_sequence()

Start the currently loaded sequence immediately. Use after load_sequence(). ▢️

stop_sequence()

Stop the running sequence and wait until NINA reports it stopped. ⚠️ Does not park the scope.

get_sequence_state(detail)

Per-step view of the loaded sequence: plan attribution, status, exposure progress (exposure is the step's first group; exposure_groups lists every group, since a batched step owes frames across several), horizon altitude, errors, and a top-level parse_error that is true only when the payload's target area was not recognised (reported in issues, never raised). detail: summary (default) or raw (/sequence/state). Read-only.

πŸ—ΊοΈ Plan Management

Plan creation and batch reconciliation.

Tool

Purpose

audit_plans(plans?, project_dir?, types?, include_orphans=true)

Whole-project capture audit in one call: reconcile plan expectations with CSV attribution (plus the one filesystem fact the CSV cannot hold β€” bad rejects) for every plan into an all_saved verdict plus left_to_do (including never-shot plans) and blocked work lists, and a never_shot list of plans with no frames at all. Read-only.

get_plan_progress(file_path)

Per-frame-type acquired/remaining counts for every pointing of a plan, applying the plan's quality thresholds. Use before load_sequence to see what still needs acquiring. Read-only.

list_plans(project_dir?)

Enumerates every observation plan file inside the project directory with its file, absolute path, plan_id, target, intent, pointing_count, and mtime. Read-only.

write_plan_file(plan)

Validate and write an observation plan JSON file for later use by load_sequence β€” including its optional quality thresholds, and a mosaic block whose pointings are derived from the coverage you ask for (see Mosaic block). Creates the file only; loads and starts nothing.

get_nina_settings()

Read the running server's environment β€” NINA_ARCHIVE_DEST, NINA_UPLOAD_CMD, NINA_VERIFY_CMD, NINA_ENDPOINT, NINA_DRIVE_MOUNT β€” as received at launch (config file + shell inheritance). Runs nothing; returns settings, missing, ready (the archive trio gates ready; endpoint/drive-mount are diagnostics) for the archive-lifecycle skill.

πŸ“ˆ Telemetry Watchdog

Live HFR/star-count metrics during acquisition.

Tool

Purpose

get_frame_stats(image_type?)

Live per-frame statistics for the current (most recent) frame, straight from the image-history API β€” the watchdog's own data source (HFR, HFR Οƒ, stars, ADU, guiding RMS, temp, filter, filename). Single-frame only, no history; read-only.

πŸ“– 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 Scope sends the mount to its parking position β€” that is the closing maneuver. Find home is 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 reporting can_park=false is rejected at load time (cannot park) rather than homed. Home is emitted in exactly one place: once per lights step, ahead of set_tracking(0), when can_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 changes can_park (firmware update, driver swap), re-run load_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, and date (the capture timestamp). A genuine 0 (e.g. stars: 0, a star-count failure) is preserved as 0 β€” unlike the CSV path, 0 here is a real reading, not a "not measured" sentinel.

  • Single frame only: despite its name, image-history serves 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's imageType filter to assert the current frame's type (e.g. "light", "dark"). When the current frame isn't of that type the tool reports count: 0 with a note rather than erroring.

  • Output: {count, image_type, frame, note} β€” count is 1 when a frame is present (else 0, with frame: null and note explaining 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 β€” see progress.py's matcher), and all count only when shot within calibration_window_days of the earliest attributed light, on either side of it (inclusive; a 1-day window spans anchor βˆ’ 1d … anchor + 1d).

  • Calibration window: calibration groups also carry window_open (bool) and window_end (earliest light + calibration_window_days, displayed in the host's local time with its UTC offset). While the current time is inside the window remaining_count is total βˆ’ acquired; once outside, no frame shot now could be credited, so remaining_count is 0 (with window_open: false). acquired_count stays truthful, and lights carry neither field. Raise calibration_window_days or write a new plan to reopen the window.

  • remaining_count == 0 is not "complete": the window rule above zeroes a calibration group's remaining even when frames are missing, so completion is decided from acquired_count vs total_count and window state instead β€” a closed window under a deficit is reported as expired_with_deficit, not complete. Per pane, status is complete / incomplete / expired_with_deficit; the top level carries expired_with_deficit (bool), and complete is true only when every pane is genuinely done. The expired case is separated from incomplete because its fix differs: no sequence run can close an expired calibration deficit β€” raise calibration_window_days or write a new plan β€” and warning says so.

  • Quality thresholds β€” set in the plan file, not on this call: the plan's optional quality section (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 writes 0 for unmeasured values, and 0 fails an active threshold) β€” from the acquired count, so a failed frame leaves a deficit to re-shoot. The response's top-level quality field echoes exactly which thresholds were applied ({} means none). The same section drives load_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_plans deliberately ignores quality β€” 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 from remaining_count == 0 alone) plus a pointings list with per-pane progress, per-pane complete, and per-pane status, so panes can be acquired sequentially.

  • Overshoot β€” read this before trusting complete: light items also carry surplus_count (frames attributed beyond total_count), and the top level carries overshot (bool) and warning (string or null). acquired_count is cumulative across every run of the plan while total_count is a per-plan constant, so a mode="full" re-shoot asks N.I.N.A. for total_count more 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 reported acquired_count: 137, remaining_count: 0, complete: true. When overshot is true, treat complete as "these frames exist" and not as "the last run succeeded": confirm what the latest run actually landed with audit_plans plus the per-date frame folders on the imaging drive. surplus_count cannot 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's total_count, summed over its exposure groups β€” per pointing for lights, plan-level for calibration) and attributed / remaining (exactly what get_plan_progress reports, quirks included). The filesystem is consulted for exactly one fact ImageMetaData.csv cannot carry: frames N.I.N.A. rejected via its BAD_ 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 reaches attributed; the light row reports them as bad. Calibration rows carry own_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 a never_shot count), left_to_do, blocked, never_shot, rows, orphans, errors, and root (the imaging directory actually scanned).

  • left_to_do holds only what running a sequence can fix β€” MISSING_FILES and row-level NEVER_SHOT rows, with missing = remaining and an action hint per type, plus one NEVER_SHOT entry per unshot pointing of a wholly unshot plan with missing = that pointing's whole light ask. blocked is EXPIRED: the calibration window closed under a deficit, so only raising calibration_window_days or writing a new plan helps.

  • never_shot β€” the left join's blind spot, closed: discovery is driven by ImageMetaData.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 reading left_to_do alone saw two 1-frame deficits while six whole unshot plans (240 frames) also waited β€” found only by diffing list_plans by 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 in left_to_do with reason: "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 no rows β€” expected vs attributed means nothing for frames never attempted β€” and they make all_saved false, so delete or move out any plan file you never intend to shoot (unrelated JSON is already ignored: it never loads as a plan). Explicit plans= never populates it: naming a file is the request to audit it, so an unshot plan named there audits as an ordinary row with status NEVER_SHOT.

  • status per row (first match wins):

    • EXPIRED β€” calibration window closed with an uncredited deficit; surfaces it despite remaining being forced to 0 by 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 from remaining (which is just expected βˆ’ attributed and cannot tell untried work from a partial deficit) πŸŒ‘

    • MISSING_FILES β€” remaining > 0 and the frames genuinely aren't there: shoot more πŸ”«

    • SUSPECT_JUNK β€” degenerate light/dark rows (duration under half the plan's exposure or 0.01s, e.g. 0.00003s Smart-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 is MISSING_FILES with the junk count as the cause πŸ—‘οΈ The audit reads the live imaging root only, so the status keeps all_saved: false while those rows are live β€” nina-archive has already copied them to the plan folder's junk/ by then (they are listed in manifest.files[], which is what lets the purge proceed at all). --apply alone does not clear the verdict: it quarantines the rows but leaves the plan file in place, which then reads as NEVER_SHOT β€” only nina-purge --purge (which removes that plan's JSON once its frames are gone) restores all_saved: true.

    • POOL_CREDITED β€” calibration satisfied plan-wide from another target's directory while this plan's own own_rows fall short β€” informational, not a gap 🏷️

    • OVERSHOT β€” lights attributed above expected: the target has been acquired more than once, either by a mode="full" re-run or on separate nights under one plan id. Harmless in itself ℹ️, but it is the case where complete cannot 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 attributed can legitimately exceed that plan's own own_rows β€” which is precisely what POOL_CREDITED reports. Lights also require the exposure duration to match (Β±0.05s), so degenerate frames never count. ℹ️ A bad-rejected frame never reaches attributed, so it shows up as a remaining deficit explained by the light row's bad count. 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 ordinary MISSING_FILES deficit. 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 in errors only 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_plans still reports unparseable files under its own errors), and the rest of the sweep still runs; a project directory with no plans returns a warning with root: null. orphans lists landing token directories whose plan file no longer exists (from deleted plans) β€” the dual of never_shot, which is plan files whose frames do not exist. Every .fits/.fits.fz under 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

action

light, dark, bias, or flat; decides what is built from plan.

plan

The observation-plan JSON path. Required by every action; omitting it raises an error naming the entry.

pointing_index

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).

variant

Scoped to the action; a bad pairing fails naming the entry. flat requires dawn (waits for morning twilight) or dusk (waits for sunset). dark/bias take wheel (default β€” park the wheel on the profile's Dark slot), cover (close the motorized cover, e.g. a flip-flat, around the exposures, then reopen it), or shutter (expose without moving the filter wheel, relying on the camera's shutter) β€” each capability-checked at load: wheel needs a filter wheel with a Dark slot, cover a flat device reporting open/close support, shutter a camera reporting HasShutter, and a variant the rig cannot perform fails naming the reason plus the variants it supports. light takes none.

mode

remaining (default) acquires only frames still needed (total minus frames already attributed); if nothing remains the plan is reported complete and nothing is loaded. full acquires the whole plan again β€” and warns when that light group is already complete (see Behavior).

Behavior:

  • Quality thresholds are not request fields β€” they live in the plan file's quality section (max_hfr, max_hfr_st_dev, min_detected_stars, max_guiding_rms_arcsec; all optional, defaulting to no filtering), which load_sequence and get_plan_progress both 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 in get_plan_progress's quality field.

  • 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's FilePattern. 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 labeled r{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_progress reports complete: true whether 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 a dark/bias/flat group 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 β€” full is 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

target

no

Catalog designation, e.g. "M31", "NGC 7000"

intent

no

2-3 words describing the goal

plan_id

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, . and - only: _ is the attribution-token delimiter, and N.I.N.A. rewrites other characters when it puts $$TARGETNAME$$ into the file path, so an id outside that charset is refused at write and at load rather than silently never matching its frames.

description

no

Explanation of the observation plan, including rationale, exposure goals, equipment, or sky constraints.

pointings

yes (unless mosaic)

One or more pointing objects β€” may be omitted entirely when a mosaic block is given (or passed as []; both spellings hash to the same plan_id). Each requires ra_hours (J2000 RA in hours, [0, 24)) and dec_deg (J2000 declination in degrees, [-90, +90]). Optional label is shown in the N.I.N.A. target name; position_angle_deg is rotator PA in degrees east of north, [0, 360). If omitted, 0 is sent to N.I.N.A., leaving the rotator at its current/synced position. Optional row and column are nonnegative mosaic metadata not sent to N.I.N.A.

mosaic

no

Mosaic specification as an alternative to pointings β€” see Mosaic block. Inputs: center_ra_hours (J2000, [0, 24)), center_dec_deg ([-90, +90]), coverage_width_arcmins / coverage_height_arcmins (the footprint to cover, arcmins, both > 0), optional overlap_pct (default 20, (0, 100)) and pa_deg (default 0, [0, 360)). write_plan_file derives cols/rows from the profile's optics and stamps them plus pane_fov_arcmins back onto the block; when pointings is also present the pointings are the authority.

batch_size

no

Exposures per batch; defaults to 5. Set to 0 to disable batching.

calibration_window_days

no

Defaults to 7 (minimum 1). Calibration frames count only when taken within this many days before or after the earliest attributed light. After the window closes, remaining calibration is reported as 0.

cooler

no

Cooler settings: on defaults to true; setpoint_celsius defaults to -10 and must be in [-40, 30].

constraints

no

min_altitude defaults to 30 degrees and must be in [0, 90]; horizon_offset_degrees defaults to 2 and must be in [0, 10]. Together with the profile's custom horizon they form the floor N.I.N.A. enforces on both sides: the sequence's loop conditions require alt >= horizon(az) + horizon_offset_degrees and alt >= min_altitude, and the planning tools (best_targets, target_altitudes) apply the same max(...) so they never disagree with what the sequence will do.

autofocus

no

reference_filter_name defaults to "L"; hfr_increase_sample_size to 3; hfr_increase_threshold_percent to 15; every_n_exposures to 10; and threshold_celsius to 1. Numeric values must be greater than zero.

guiding

no

dither_every_n_exposures defaults to 2; set it to 0 to never dither (no dither trigger is emitted). check_drift_every_n_exposures defaults to 6 and max_drift_arcmin to 1.5; both must be greater than zero.

light_frames

yes

Nonempty list of light exposure specs, each with filter_name, exposure_time_seconds (greater than zero), and total_count (at least 1).

flat_frames

yes

Nonempty list of flat exposure specs, each with filter_name and total_count (at least 1). No exposure time: N.I.N.A.'s SkyFlat item chooses it automatically to hit the right signal level. List order is shoot order: dawn flats shoot as written, dusk flats shoot reversed. List broadband first, narrowband last (e.g. L, R, G, B, Ha) so narrowband shoots while twilight is brighter in both variants.

dark_frames

yes

Nonempty list of dark exposure specs, each with exposure_time_seconds (greater than zero) and total_count (at least 1).

bias_frames

yes

Nonempty list of bias exposure specs, each with total_count (at least 1).

πŸ“Š 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 before pa_deg rotation; round up to the target's full extent (a best_targets row's major_arcmin/minor_arcmin is exactly this), overlap_pct (default 20, in (0, 100)), and pa_deg (default 0).

  • 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 with ceil, 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 reports colsΓ—rows, pane FOV, step, and achieved vs requested coverage.

  • The written file holds both: the expanded pointings (labels r{row}_c{col}, row/column metadata, each pane attributed independently via _{plan_id}-{pointing_index}_) and the block with derived cols / rows / pane_fov_arcmins stamped back as a record of what was planned. pointings is the authority β€” nothing re-derives on read, and the content-derived plan_id covers 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_deg must be 0. 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 with load_sequence(request=[{"plan": file_path, "action": "light", "pointing_index": N, "mode": "remaining"}]) and start_sequence(). Repeat pane by pane across the night; when the top-level complete is true, the mosaic is done β€” and if expired_with_deficit is true instead, the lights may well be fine and only the calibration window needs raising or a new plan (see get_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

+Directory points at one messy root; WBPP reads the headers and fills the Bias / Darks / Flats / Lights tabs itself. Grouping keywords (SESSION_1, …) are the only time a directory is read β€” deliberately, to separate multi-night sessions

Astro Pixel Processor

any

loads a working directory and matches masters to lights from IMAGETYP, filter and gain in the headers

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 .ssf scripts)

exactly lights, darks, flats, biases

literal batch scripts (cd biases, cd flats, …) that neither scan subdirectories nor parse IMAGETYP β€” the one reader where the name is load-bearing, and only because the script author typed it

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 >= total per group plus calibration-window state, never remaining_count (which reads 0 once a window closes even while frames are missing), the same rule get_plan_progress reports as complete. Incomplete or expired-with-deficit plans are reported and skipped (pass --all to archive them anyway; the manifest then carries an incomplete warning). 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 what get_plan_progress credits 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 within calibration_window_days of 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 to junk/) automatically joins the 11 environmental columns from sibling WeatherData.csv (temperature, dew_point, humidity, pressure, wind_speed, wind_direction, wind_gust, cloud_cover, sky_temperature, sky_brightness, sky_quality), resolved per date folder on exposure_number so multi-date flattening never mis-attaches weather. Pass --no-weather to 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 to junk/ instead of being skipped, each entry in manifest.files[] carrying "type": "JUNK", its frame_type and a reason: degenerate (no data in the frame at all β€” duration below max(0.01s, half the plan's shortest exposure), the 0.00003s Smart-Exposure dark; the same rule audit_plans calls junk) or uncredited (real data no group credited β€” outside the window, an exposure no group asked for). This is what keeps nina-purge unblocked: every live own-token row now lands in the manifest, so preserved(F) can never be false for one of this plan's own frames β€” the old disk.not_selected rows 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 own darks/ is never duplicated. Per-type counts[*].archived counts type-folder frames only (a worthless frame must not inflate archived); file_count includes junk/.

  • πŸ’½ Disk report in the manifest (no directory walk): every entry starts as a CSV record classified by an existence probe β€” disk.rejected (the BAD_-renamed twins of dropped rows: excluded everywhere, listed so an offline reader can explain expected-vs-shipped; a live agent reads audit_plans' bad), disk.gone (recorded once, now nowhere β€” warned, plus a πŸ’½ line), disk.junk (shipped to junk/, each with its reason), and disk.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_progress views keep working. Every file is size-verified after copying (--checksum adds sha256), each folder is staged in a hidden .<name>.partial sibling 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's missing (never an abort of that file β€” but if no selected frame could be copied at all, the run raises ArchiveError rather than commit a folder of nothing, even when junk files did copy), and <dest>/archive-index.jsonl logs every archive.

  • ♻️ Idempotent: a folder that already exists in --dest is skipped (exit 0) unless --force rebuilds it. Plan files inside --dest are never re-discovered, so the default --dest ./.archive inside 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 with NINA_ARCHIVE_DEST in .opencode/opencode.json: nina-purge only credits frames whose archive folder it can find, so archiving into one destination and purging against another reports every frame as not preserved.

  • 🚧 --dest must be outside the imaging root: archived folders carry ImageMetaData.csv copies, 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-root to bypass the site-profile lookup; otherwise the root comes from get_site_profile (with NINA_DRIVE_MOUNT mapping on non-Windows hosts), and a missing root raises rather than archiving nothing.

  • πŸšͺ Exit codes: 0 archived (or already archived), 1 nothing archivable or an error occurred (also printed per plan to stderr), 2 bad 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_id changes: the plan's current derived id (_base_plan_id()) is stamped into the blank plan_id field and the file is rewritten with the same serializer write_plan_file uses β€” atomically (temp file in the plan's own folder, then os.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 and nina-archive --force rebuilds 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_file are stamped with an explicit id at creation, so the agent never needs to pin. There is no MCP tool for it.

  • πŸšͺ Exit codes: 0 pinned (or already pinned / dry run), 1 a plan could not be loaded or written, 2 bad 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 committed manifest.json under --dest lists F's source path. A plan is released when it has an archive folder and is either complete now (shared _progress_facts verdict) or was archived under --all (the manifest's complete: false is the waiver). A complete-but-unarchived plan therefore protects its frames: archive before you purge.

  • 🎯 Claims reuse archive._select_frames verbatim: 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 frames nina-archive diverts to junk/ β€” degenerate and real-but-uncredited own-token frames are all listed in the manifest, so not preserved can 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: --apply moves each prunable directory into <imaging-root>/.quarantine/<dir> β€” a dot directory every attribution walk prunes, so quarantined frames and their ImageMetaData.csv behave exactly as if gone (one mv restores them). Only --purge unlinks, and it is a separate invocation: live with the quarantine first. A name collision gets a ~1 suffix.

  • πŸ”’ 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 posture nina-archive takes. 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, carrying plan_file_deleted: true/false and, when kept, the reason).

  • πŸ“Œ Plan files are removed by --purge, last: once a plan's frames are actually gone, nina-purge deletes 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 its plan.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 with archive 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 archived plan.json is 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 the NEVER_SHOT leftover automatically: after --apply the console still names each quarantined plan file, but --purge finishes the job β€” no more moving files by hand.

  • πŸšͺ Exit codes: 0 something was (or, in a dry run, would be) quarantined or purged β€” and a --purge run with nothing left is success (purging is idempotent), 1 nothing to do (report/--apply) or an error β€” including a stale-archive refusal, 2 bad 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.FilePattern must 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_plans claims 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 in orphans, 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 quality section holds max_hfr, max_hfr_st_dev, min_detected_stars, and max_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 writes 0 for unmeasured values, and 0 never passes an active threshold) β€” is excluded from the acquired count, leaving a deficit the next mode="remaining" load re-acquires. Thresholds apply only to light frames β€” calibration frames have no star quality. They are read from the plan by load_sequence and get_plan_progress only: audit_plans and the archive ignore them, reporting what is on disk rather than what qualifies. To enable them, add the section to the plan JSON (keep plan_id set β€” see the plan-file note below) e.g. "quality": {"max_hfr": 2.5, "max_hfr_st_dev": 0.6}; get_plan_progress echoes the active set in its quality field.

  • πŸ‘Ž 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 next mode="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 when plan_id is missing β€” run nina-pin-id first to freeze the id so already-shot frames keep attributing. A hand-written plan_id must 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.json is the Windows config; wsl_opencode.json (WSL) and smb_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:

  1. 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 catches CAMERA-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, so PREPARK-DELAY is caught by PARK.

    • 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-CENTER never 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 from GET /v2/api/sequence/json at startup (using the same any-node-RUNNING rule as the MCP server, so the two never disagree) and maintained from RUN-*/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-HOMED never wakes. A sequence emits Find home only in a lights step (ahead of set_tracking), so most homes still come from the survey scripts and manual operation β€” it fired 7 times in one 24h sample. MOUNT-PARKED / MOUNT-UNPARKED stay 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 as get_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 at 0: an explicit 0 routine events waiting means 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_logs is 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 in ImageMetaData.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 light frames are being acquired the plugin polls GET /v2/api/image-history on each IMAGE-SAVE and wakes the agent as an operational fault β€” a QUALITY-WATCHDOG: … event β€” when a frame-quality-diagnostics standing trigger holds for 3 consecutive frames β€” HFR > 3β€³ or under 10 detected stars. The consecutive-frame rule is deliberate: the single-frame GUIDER-START settles 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 (from ACQUISITION-STARTING: [{kind}] …) is skipped without even polling, and the record's own ImageType is 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. That ImageType check is also what keeps the watchdog working when the plugin attaches after a step's ACQUISITION-STARTING. qualityWatchdog: false turns the whole check off.

    image-history is 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 answered 400 No image available for a whole idle afternoon, while the previous night's frame was still served from image-history). Freshness is proven, not assumed β€” a sample is accepted only when its Date is newer than the last one, cross-checked against the IMAGE-SAVE event to 0.95 ms, so two saves reading one identical record can never count a single frame twice. A record with no provable Date, 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.

  2. Interval check β€” every intervalCheckMinutes minutes 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_test are the on-demand way to verify the pipeline instead.

  3. 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 (pinnedSessionID in 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 as re-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 from nina_notify_disarm: it re-enables every wake (armed back 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 gap RECOVERY β€” until nina_notify_arm is called again, so a coding session is never prompted by N.I.N.A. API traffic. Persisted (armed in 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, and lastWakeAt is left untouched β€” the arm confirmation that ends the silence names the get_events window 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_check reports armed / disarmedAt at 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-ending SEQUENCE-FINISHED to a silent drop with no onclose), 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 renames nina_notify_status β†’ nina_notify_wake_status β†’ nina_notify_health: a bare "status" kept resolving to nina-planner's get_nina_status / get_site_equipment_status instead, 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 calling arm again would; it was briefly folded into arm as test: true on 2026-11-05 and kept separate again the same day. It is also the one delivery permitted while disarmed (allowDisarmed at 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 a setup()-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:

PLAN.md

# 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.

.opencode/rules/AGENTS.md

# 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-lifecycle

Archive β†’ upload β†’ verify β†’ purge finished imaging sets, human-gated.

frame-quality-diagnostics

Autofocus failures and per-frame quality telemetry (HFR, HFR Οƒ, stars, ADU).

night-loop

Pick and start the next target, or end the night with a report and a park.

nina-lifecycle

Start / stop / status of the NINA application.

run-nina-tools

How to invoke the nina-* CLIs β€” not on PATH: .venv/bin first, then uv run --project, then a PATH copy, else stop.

safety-interrupt-recovery

Interrupts, sequence halts, and recovery: liveness, safety, parking.

site-conditions

7-day hourly forecast (cloud, wind, precip, dew/frost, Bortle, astro-dark) β€” advisory only, never a substitute for is_safe.

πŸ—„οΈ 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

.opencode/opencode.json

{
  "$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

ninaEndpoint

string

127.0.0.1:1888

N.I.N.A. host and port (no scheme) for the websocket event stream, e.g. 192.168.0.24:1888. The plugin connects to ws://<ninaEndpoint>/v2/socket.

intervalCheckMinutes

number

-1

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.

qualityWatchdog

boolean

true

Wake the agent as an operational fault when a frame-quality-diagnostics standing trigger β€” HFR > 3β€³ or fewer than 10 detected stars β€” holds for 3 consecutive light frames. Polls GET /v2/api/image-history on each IMAGE-SAVE, accepts a record only when its Date advanced, and gates on the record's ImageType as well as on the step kind β€” so darks, biases and flats never trigger it; re-arms once the metric recovers.

pluginLogs

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 [<YYYY-MM-DDTHH:mm:ss.mmmΒ±HH:MM>] in host-local time with its UTC offset (e.g. [2026-11-05T09:39:10.981-05:00]) β€” the same form get_events timestamps use, so a wake prompt's events and the log line that carried them read as one clock, while the offset keeps it unambiguous across DST and convertible to UTC when lining up with PROGRESS.md's older …Z headers. Each injected prompt additionally names the receiving session (… -> session=<sessionID>), so events correlate across the separate opencode sessions a telegram-bot bridge creates. Set to a writable path (e.g. /tmp/nina-plugins.log) to capture diagnostic output. Omit or leave empty to disable file logging.


πŸ”§ 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

NINA_ENDPOINT

127.0.0.1:1888

N.I.N.A. host and port for the REST API (host:port). For WSL, try 192.168.0.24:1888. Setting it at a remote host does not by itself flip get_nina_status().lifecycle_control_available β€” that flag is windows_interop_available() (can this host run tasklist/taskkill/schtasks), and start_nina/stop_nina cannot operate on NINA when it is false.

NINA_DRIVE_MOUNT

/mnt/<drive>

Local mount root for the drive letter in the profile's image_save_path, used to resolve the imaging directory on Linux, WSL, and macOS (by audit_plans, get_plan_progress, and the archive/purge tooling). The value must be the local path where the Windows drive root is mounted (C:\Users\me\img becomes <value>/Users/me/img), e.g. /mnt/c in WSL, or wherever you mounted the share on macOS (such as /System/Volumes/Data/Network). The mount point is arbitrary and the drive need not be C:; the drive letter in the profile path is replaced by this value whatever it is. Defaults to /mnt/<drive> (e.g. /mnt/c). On Windows (win32) the profile image_save_path is used directly. The resolved value is also exposed as the derived local_image_save_path field on the profile returned by get_site_profile.

NINA_PLANNER_LOG

(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. C:/Windows/Temp/nina-planner-debug.log) on a non-Windows host is redirected to the system temp dir under the same file name.

NINA_FLATS_ALTITUDE

80

Altitude in degrees for flat panel calibration frames

NINA_FLATS_AZIMUTH_DAWN

270

Azimuth in degrees pointing west for dawn flats

NINA_FLATS_AZIMUTH_DUSK

90

Azimuth in degrees pointing east for dusk flats

NINA_EXE_PATH

C:\Program Files\N.I.N.A. - Nighttime Imaging 'N' Astronomy\NINA.exe

Windows path to NINA.exe used by start_nina to launch NINA.

🐧 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=mirrored

In 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 # uv

Next I installed opencode v2 with:

$ bun install -g --trust @opencode/cli

Then 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

telegram chat

@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

opencode serve --port 4096 (started with OPENCODE_SERVER_PASSWORD set)

telegram bot

npx -y -- @grinev/opencode-telegram-bot start

1. Create the bot

  1. Message @BotFather with /newbot, pick a name and username, and copy the bot token it returns.

  2. Message @userinfobot with /start to get your numeric user id. Only that id may talk to the bot β€” everyone else is silently ignored.

  3. 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

TELEGRAM_BOT_TOKEN

(from @BotFather)

Required. The bot's API token.

TELEGRAM_ALLOWED_USER_ID

123456789

Required. Your Telegram user id β€” the whitelist that keeps strangers out.

OPENCODE_SERVER_VERSION

v2

v1 or v2; must match the server you run.

OPENCODE_API_URL

http://127.0.0.1:4096

Where opencode serve listens.

OPENCODE_SERVER_USERNAME

opencode

Server auth user.

OPENCODE_SERVER_PASSWORD

(same as the server)

Required on v2. Must equal the password the server was started with.

OPENCODE_MODEL_PROVIDER / OPENCODE_MODEL_ID

opencode-go / mimo-v2.6-flash

Default model for new sessions.

BOT_LOCALE

en

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   # background

Start 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 tools
get_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

    B3.2/5.0

    Scored across 14 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      A 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.
      14
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      An 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.
      21
      6
      MIT