🌙 Nightshift

Nightshift is an overnight autonomous research agent designed for OpenCode. It performs deep analysis of codebases while you sleep, providing comprehensive audits, enhancement recommendations, and research reports by the time you start your next day.

Project Status

Nightshift is currently in maintenance mode.

• This repository is stable for community use, forks, and experimentation.
• New feature development is not on an active roadmap.
• Issue triage and PR review are best-effort with no guaranteed response SLA.

Compatibility Notes

v0.2.0 (released February 17, 2026) is the baseline community release.

• Validated against the OpenCode CLI integration surface used by Nightshift (opencode models and opencode run) as of this release date.
• Future OpenCode CLI changes may require community patches.
• For setup verification, run nightshift doctor and nightshift start . --dry-run before full runs.

Features

• Autonomous Research: Deep dives into codebases without manual intervention.
• Multi-Model Failover: Automatically discovers available OpenCode models and builds a resilient fallback chain.
• Comprehensive Reports: Generates detailed HTML research reports and differential reports comparing changes between runs.
• OpenCode Integration: A dedicated plugin that lets you control Nightshift directly from your editor.
• Smart Scheduling: Built-in support for daily research tasks using cron or macOS launchd.
• GitHub Integration: Automatically creates issues for critical findings.
• Notifications: Real-time alerts via Slack or custom webhooks.
• Web Dashboard: Interactive dashboard for monitoring runs and viewing findings.
• Setup UX: Built-in nightshift init and nightshift doctor commands for first-run setup and troubleshooting.

Installation

1. Python Package

Install the core engine and CLI:

cd /path/to/nightshift
pip install -e .

2. OpenCode Plugin

Install the plugin dependencies:

cd /path/to/nightshift/plugin
bun install

To load the plugin in OpenCode, point your plugin configuration to the plugin/index.ts file or the compiled output.

First 10 Minutes

Use this path if you want to validate your setup quickly before running a full overnight session.

1. Create starter config (in your local Nightshift data directory):

   nightshift init --no-add-current-project

2. Verify your environment:

   nightshift doctor

3. Preview tasks without executing agents:

   nightshift start . --duration 0.5 --priority-mode quick_scan --dry-run

4. Start dashboard:

   nightshift serve

   Open: http://127.0.0.1:7890/

5. Run a small real pass:

   nightshift start . --duration 1 --priority-mode quick_scan
   nightshift report

Replace . with a project alias from config.toml if you prefer named targets.

Quick Start

1. Initialize local config:

   nightshift init

2. Validate setup:

   nightshift doctor

3. Start the API Server:

   nightshift serve

4. Run a Research Task:

   nightshift start opsorchestra --duration 8.0

5. View the Report:

   nightshift report

CLI Usage

The nightshift command provides several subcommands:

• start [PROJECTS]...: Start a research run on specified projects or paths.
• start [PROJECTS]... --dry-run: Validate config and preview the generated task plan without running agents.
• init: Create a starter config.toml in your Nightshift data directory.
• doctor: Validate OpenCode/GitHub/config/dependency setup and show fix hints.
• serve: Start the HTTP API server (default port: 7890).
• status: Show current run status and model availability.
• report: Open the latest research report in your browser.
• diff: Generate and open a differential report comparing to the previous run.
• list: List all historical reports.
• clean: Delete old data and reports.

Web Dashboard

Once the server is running (nightshift serve), you can access the interactive dashboard at: http://127.0.0.1:7890/

The dashboard allows you to:

• Monitor real-time task progress.
• View live findings and model performance.
• Manage scheduled runs.

API Reference

Nightshift exposes a REST API on port 7890.

Start a Run

curl -X POST http://127.0.0.1:7890/start \
     -H "Content-Type: application/json" \
     -d '{
       "projects": ["opsorchestra"],
       "duration_hours": 8.0,
       "create_github_issues": true,
       "priority_mode": "balanced"
     }'

Check Status

curl http://127.0.0.1:7890/status

Other Endpoints

• GET /reports: List all reports.
• GET /report/latest: View the latest HTML report.
• GET /report/diff: View the differential report.
• GET /models: Check model availability and rate limits.
• POST /stop: Stop the current run.

Configuration

Nightshift stores its data in ~/.nightshift.

Config File

Nightshift reads optional user config from:

• ~/.nightshift/config.toml
• or NIGHTSHIFT_CONFIG_FILE if set

Create a starter config with:

nightshift init

Example:

[defaults]
duration_hours = 8.0
priority_mode = "balanced"
open_report_in_browser = true

[projects]
backend = "/path/to/backend"
frontend = "/path/to/frontend"

[models]
preferred = ["openai/gpt-5.2", "google/antigravity-gemini-3-pro-high"]

Environment Variables

• NIGHTSHIFT_DATA_DIR: Override the default data directory.
• NIGHTSHIFT_CONFIG_FILE: Override the default config path.
• NIGHTSHIFT_PROJECT_OPSORCHESTRA: Override default path for the opsorchestra alias.
• NIGHTSHIFT_PROJECT_GHOST_SENTRY: Override default path for the ghost-sentry alias.
• SLACK_WEBHOOK_URL: Default webhook for notifications.

See .env.example for a complete starter environment file.

Model Selection

Nightshift tries to:

1. Use preferred models from config.toml (if set).
2. Keep only models available in your current OpenCode environment.
3. Auto-rank discovered models when preferred models are unavailable.

Architecture

Nightshift consists of three main components:

1. Core Engine (Python): Handles the task queue, model management, and research logic.
2. API Server (FastAPI): Provides a bridge between the core engine and external tools.
3. OpenCode Plugin (TypeScript): Exposes research tools directly within the developer environment.

For deeper implementation details, see ARCHITECTURE.md.

Contributing

Forks and external contributions are welcome. See CONTRIBUTING.md for local setup, dev commands, and PR expectations.

---

Built for autonomous engineering.