https://github.com/marcus/nightshift
Nightshift uses your leftover Claude / Codex budget to surprise you with useful PRs. Love them or leave them.
https://github.com/marcus/nightshift
Last synced: 3 months ago
JSON representation
Nightshift uses your leftover Claude / Codex budget to surprise you with useful PRs. Love them or leave them.
- Host: GitHub
- URL: https://github.com/marcus/nightshift
- Owner: marcus
- License: mit
- Created: 2026-02-05T04:08:39.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-02-05T16:32:26.000Z (4 months ago)
- Last Synced: 2026-02-05T17:23:53.677Z (4 months ago)
- Language: Go
- Homepage:
- Size: 1.47 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Nightshift
> It finds what you forgot to look for.
**[nightshift.haplab.com](https://nightshift.haplab.com)** · [Docs](https://nightshift.haplab.com/docs/intro) · [Quick Start](https://nightshift.haplab.com/docs/quick-start) · [CLI Reference](https://nightshift.haplab.com/docs/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](https://nightshift.haplab.com/docs/installation)
```bash
brew install marcus/tap/nightshift
```
Binary downloads are available on the GitHub releases page.
Manual install:
```bash
go install github.com/marcus/nightshift/cmd/nightshift@latest
```
## Getting Started
Full guide: [Quick Start docs](https://nightshift.haplab.com/docs/quick-start)
After installing, run the guided setup:
```bash
nightshift setup
```
This walks you through provider configuration, project selection, budget calibration, and daemon setup. Once complete you can preview what nightshift will do:
```bash
nightshift preview
nightshift budget
```
Or kick off a run immediately:
```bash
nightshift run
```
## Common CLI Usage
Full reference: [CLI Reference docs](https://nightshift.haplab.com/docs/cli-reference)
```bash
# 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.
Useful flags:
- `nightshift run --dry-run` to simulate tasks without changes
- `nightshift run --project ` to target a single repo
- `nightshift run --task ` 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.
```bash
# 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](https://nightshift.haplab.com/docs/configuration) · [Budget docs](https://nightshift.haplab.com/docs/budget) · [Scheduling docs](https://nightshift.haplab.com/docs/scheduling) · [Tasks docs](https://nightshift.haplab.com/docs/tasks)
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](https://nightshift.haplab.com/docs/configuration) or [SPEC.md](docs/SPEC.md) for detailed options.
Minimal example:
```yaml
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:
```yaml
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`.
## License
MIT - see [LICENSE](LICENSE) for details.