It finds what you forgot to look for.

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

Nightshift logo

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.

• 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

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

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

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 skill-groom
nightshift task show lint-fix --prompt-only
# Run a task immediately
nightshift task run lint-fix --provider claude
nightshift task run skill-groom --provider codex --dry-run
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.

Before executing, nightshift run displays a preflight summary showing the selected provider, budget status, projects, and planned tasks. In interactive terminals you are prompted for confirmation; in non-TTY environments (cron, daemon, CI) confirmation is auto-skipped.

# Interactive run with preflight summary + confirmation prompt
nightshift run
# Non-interactive: skip confirmation
nightshift run --yes
# Dry-run: show preflight summary and exit
nightshift run --dry-run
# Process up to 3 projects, 2 tasks each
nightshift run --max-projects 3 --max-tasks 2
# Pick a random eligible task
nightshift run --random-task
# Bypass budget limits (shows warning)
nightshift run --ignore-budget
# Target a specific project and task directly
nightshift run -p ./my-project -t lint-fix

Other useful flags:

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

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.

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
 skill-groom: 2
 bug-finder: 2
 intervals:
 lint-fix: "24h"
 skill-groom: "168h"
 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.

skill-groom is enabled by default. Add it to tasks.disabled if you want to opt out. It updates project-local skills under .claude/skills and .codex/skills using README.md as project context and starts Agent Skills docs lookup from https://agentskills.io/llms.txt.

# Remove the system service
nightshift uninstall
# Remove configs and data (optional)
rm -rf ~/.config/nightshift ~/.local/share/nightshift
# Remove the binary
rm "$(which nightshift)"

MIT - see LICENSE for details.