|
|
|
|
# Nightshift CLI reference
|
|
|
|
|
|
|
|
|
|
**This file is a cache, not the source of truth.** Verify with `nightshift --help` before relying
|
|
|
|
|
on a flag; the roster and options change between releases. Captured against the
|
|
|
|
|
maintained local fork **0.1.51-lights-out**, based on upstream **0.1.49**, commit
|
|
|
|
|
`0227fe415d38e6df0fad4828c7999ba2a3b065de`, plus local Nightshift changes.
|
|
|
|
|
Usage analytics are removed at source level, not merely disabled. This is not
|
|
|
|
|
an unmodified upstream artifact; required notices remain in `LICENSE`.
|
|
|
|
|
|
|
|
|
|
Normally you should not call `nightshift` directly — use `scripts\start-run.ps1`, which adds the
|
|
|
|
|
preflight checks and the guaranteed finalize step. This reference exists for reading the flags the
|
|
|
|
|
wrapper passes and for diagnosing a run.
|
|
|
|
|
|
|
|
|
|
## Packaging
|
|
|
|
|
|
|
|
|
|
The skill vendors its own copy. There is no runtime install step and no dependency on an unrelated
|
|
|
|
|
published package:
|
|
|
|
|
|
|
|
|
|
- engine bundle: `vendor\node_modules\nightshift\dist\cli.mjs`
|
|
|
|
|
- package metadata: `vendor\node_modules\nightshift\package.json`
|
|
|
|
|
- separately stored source: `D:\OneDrive - Microsoft\HERE\nightshift-src.zip`
|
|
|
|
|
- separately stored installer: `D:\OneDrive - Microsoft\HERE\nightshift-0.1.51-lights-out.tgz`
|
|
|
|
|
|
|
|
|
|
Neither archive is needed for normal runs or included when sharing the skill folder. Keep the
|
|
|
|
|
preinstalled runtime modules and launchers in the shared copy. Vendor npm metadata refers to the
|
|
|
|
|
external installer for maintenance only; recipients need their own installer path if reinstalling,
|
|
|
|
|
not when running the existing copy.
|
|
|
|
|
|
|
|
|
|
Resolution order is `$env:LIGHTS_OUT_NIGHTSHIFT` → vendored copy → `nightshift` on PATH.
|
|
|
|
|
|
|
|
|
|
Only `node` needs to be on PATH. The `.bin` launchers stay beside the vendored package; the wrapper
|
|
|
|
|
invokes the bundle through `node`.
|
|
|
|
|
|
|
|
|
|
Nightshift keeps its engine-owned repo state under `.nightshift\runs\<runId>\` and its user config
|
|
|
|
|
under `~\.nightshift\config.yml`.
|
|
|
|
|
|
|
|
|
|
## Flags
|
|
|
|
|
|
|
|
|
|
| Flag | Notes |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `--agent <agent>` | `claude`, `codex`, `rovodev`, `opencode`, `copilot`, `pi`, `cursor`, or `acp:<target-or-command>` |
|
|
|
|
|
| `--model <model>` | Overrides `agentModel.<agent>` from config |
|
|
|
|
|
| `--max-iterations <n>` | Abort after N iterations |
|
|
|
|
|
| `--max-tokens <n>` | Abort after N total input+output+cache tokens |
|
|
|
|
|
| `--max-rate-limit-wait <dur>` | Abort after this much cumulative usage-limit wait (`30m`, `2h`, `0`) |
|
|
|
|
|
| `--fallback-model <model>` | Retry a Claude usage-limit rejection with this model instead of waiting |
|
|
|
|
|
| `--stop-when <condition>` | Natural-language completion condition; survives resume. `""` clears it |
|
|
|
|
|
| `--prevent-sleep <on\|off>` | Keep the machine awake. The wrapper always sets `on` for overnight runs |
|
|
|
|
|
| `--worktree` | Run in a separate git worktree, enabling parallel runs on one repo |
|
|
|
|
|
| `--current-branch` | Commit on the current branch instead of creating `nightshift/<runId>` |
|
|
|
|
|
| `--push` | Push after each successful iteration |
|
|
|
|
|
| `--meteor-frequency <0-5>` | TUI meteors. The wrapper sets `0` because there is no interactive console |
|
|
|
|
|
| `--mock` | TUI demo only. Replays canned iterations, does no git work, does not exit. Never use it to validate a real run |
|
|
|
|
|
|
|
|
|
|
## Run identity
|
|
|
|
|
|
|
|
|
|
Deterministic, derived from the prompt:
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
slug = prompt.toLowerCase()
|
|
|
|
|
.replace(/[^a-z0-9]+/g,'-')
|
|
|
|
|
.replace(/^-+|-+$/g,'')
|
|
|
|
|
.slice(0,20)
|
|
|
|
|
.replace(/-+$/,'')
|
|
|
|
|
hash = sha256(prompt).hex.slice(0,6)
|
|
|
|
|
runId = "<slug>-<hash>"
|
|
|
|
|
branch = "nightshift/<runId>"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
On collision the engine appends `-1`, `-2`, …, so the predicted id may not be the final one.
|
|
|
|
|
`Resolve-LightsOutRunDir` in `scripts\lib.ps1` handles that.
|
|
|
|
|
|
|
|
|
|
## Artifacts
|
|
|
|
|
|
|
|
|
|
Per run, in `<repo>\.nightshift\runs\<runId>\`:
|
|
|
|
|
|
|
|
|
|
| File | Contents |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `prompt.md` | The objective as given |
|
|
|
|
|
| `notes.md` | The agent's own iteration log — claims, not evidence |
|
|
|
|
|
| `end-state.json` | `status`, `stopCondition`, `agentError`, `iterations`, `successCount`, `failCount`, `endedAt` |
|
|
|
|
|
| `nightshift.log` | JSONL lifecycle log with timings and full `error.cause` chains |
|
|
|
|
|
| `iteration-<n>.jsonl` | Raw agent stream per iteration. Large; never copied to the vault |
|
|
|
|
|
| `base-commit` | Commit the run branched from |
|
|
|
|
|
| `stop-when` | Persisted stop condition |
|
|
|
|
|
|
|
|
|
|
## Behaviors that break unattended runs
|
|
|
|
|
|
|
|
|
|
Both are enforced by the wrapper's preflight:
|
|
|
|
|
|
|
|
|
|
1. Launching from a `nightshift/*` branch prompts interactively to overwrite or continue, and
|
|
|
|
|
hard-fails when stdin is not a TTY.
|
|
|
|
|
2. An empty prompt with a non-TTY stdin makes the engine read the prompt from stdin and block
|
|
|
|
|
forever.
|
|
|
|
|
|
|
|
|
|
Also: the engine requires a clean working tree, never force-pushes, never auto-pulls, and commits
|
|
|
|
|
each successful iteration separately so a night can be reviewed or reverted one change at a time.
|
|
|
|
|
|
|
|
|
|
## Provenance
|
|
|
|
|
|
|
|
|
|
The maintained source archive is stored separately at
|
|
|
|
|
`D:\OneDrive - Microsoft\HERE\nightshift-src.zip`. Rebuild the vendored bundle from that fork when
|
|
|
|
|
intentionally updating the engine; do not add a runtime install instruction to this skill.
|
