nightshift

README

Nightshift

It finds what you forgot to look for.

nightshift.haplab.com · Docs · Quick Start · CLI Reference

Your tokens get reset every week, you might as well use them. Nightshift runs overnight to find dead code, doc drift, test gaps, security issues, and 20+ other things silently accumulating while you ship features. Like a Roomba for your codebase — runs overnight, worst case you close the PR.

Everything lands as a branch or PR. It never writes directly to your primary branch. Don't like something? Close it. That's the whole rollback plan.

Features

• Budget-aware: Uses remaining daily allotment, never exceeds configurable max (default 75%)
• Multi-project: Point it at your repos, it already knows what to look for
• Zero risk: Everything is a PR — merge what surprises you, close the rest
• Great DX: Thoughtful CLI defaults with clear output and reports

Installation

Full guide: Installation docs

brew install marcus/tap/nightshift

Binary downloads are available on the GitHub releases page.

Manual install:

go install github.com/marcus/nightshift/cmd/nightshift@latest

Getting Started

Full guide: Quick Start docs

After installing, run the guided setup:

nightshift setup

This walks you through provider configuration, project selection, budget calibration, and daemon setup. Once complete you can preview what nightshift will do:

nightshift preview
nightshift budget

Or kick off a run immediately:

nightshift run

Common CLI Usage

Full reference: CLI Reference docs

# Preview next scheduled runs with prompt previews
nightshift preview -n 3
nightshift preview --long
nightshift preview --explain
nightshift preview --plain
nightshift preview --json
nightshift preview --write ./nightshift-prompts

# Guided global setup
nightshift setup

# Check environment and config health
nightshift doctor

# Budget status and calibration
nightshift budget --provider claude
nightshift budget snapshot --local-only
nightshift budget history -n 10
nightshift budget calibrate

# Browse and inspect available tasks
nightshift task list
nightshift task list --category pr
nightshift task list --cost low --json

# Show task details and planning prompt
nightshift task show lint-fix
nightshift task show lint-fix --prompt-only

# Run a task immediately
nightshift task run lint-fix --provider claude
nightshift task run lint-fix --provider codex --dry-run

If gum is available, preview output is shown through the gum pager. Use --plain to disable.

Useful flags:

• nightshift run --dry-run to simulate tasks without changes
• nightshift run --project <path> to target a single repo
• nightshift run --task <task-type> to run a specific task
• nightshift status --today to see today’s activity summary
• nightshift daemon start --foreground for debug
• --category — filter tasks by category (pr, analysis, options, safe, map, emergency)
• --cost — filter by cost tier (low, medium, high, veryhigh)
• --prompt-only — output just the raw prompt text for piping
• --provider — required for task run, choose claude or codex
• --dry-run — preview the prompt without executing
• --timeout — execution timeout (default 30m)

Authentication (Subscriptions)

Nightshift relies on the local Claude Code and Codex CLIs. If you have subscriptions, you can sign in via the CLIs without API keys.

# Claude Code
claude
/login

# Codex
codex --login

Claude Code login supports Claude.ai subscriptions or Anthropic Console credentials. Codex CLI supports signing in with ChatGPT or an API key.

If you prefer API-based usage, you can authenticate those CLIs with API keys instead.

Configuration

Full guide: Configuration docs · Budget docs · Scheduling docs · Tasks docs

Nightshift uses YAML config files to define:

• Token budget limits
• Target repositories
• Task priorities
• Schedule preferences

Run nightshift setup to create/update the global config at ~/.config/nightshift/config.yaml.

See the full configuration docs or SPEC.md for detailed options.

Minimal example:

schedule:
  cron: "0 2 * * *"

budget:
  mode: daily
  max_percent: 75
  reserve_percent: 5
  billing_mode: subscription
  calibrate_enabled: true
  snapshot_interval: 30m

providers:
  preference:
    - claude
    - codex
  claude:
    enabled: true
    data_path: "~/.claude"
    dangerously_skip_permissions: true
  codex:
    enabled: true
    data_path: "~/.codex"
    dangerously_bypass_approvals_and_sandbox: true

projects:
  - path: ~/code/sidecar
  - path: ~/code/td

Task selection:

tasks:
  enabled:
    - lint-fix
    - docs-backfill
    - bug-finder
  priorities:
    lint-fix: 1
    bug-finder: 2
  intervals:
    lint-fix: "24h"
    docs-backfill: "168h"

Each task has a default cooldown interval to prevent the same task from running too frequently on a project (e.g., 24h for lint-fix, 7d for docs-backfill). Override per-task with tasks.intervals.

License

MIT - see LICENSE for details.