Stop Wasting Your LLM Budget! Nightshift Finds Dead Code Overnight

Stop Wasting Your LLM Budget! Nightshift Finds Dead Code Overnight

Your Claude tokens reset every week. Your Codex allowance vanishes into thin air. And what do you have to show for it? Nothing. Meanwhile, your codebase is silently rotting—dead functions accumulating like digital dust, security holes widening while you ship features, documentation drifting further from reality with every commit. You've felt that nagging guilt. That "I should really audit this someday" thought that never becomes action.

What if I told you there's a tool that weaponizes your wasted LLM budget while you sleep? No more manual code audits. No more "someday." Just clean, surprise PRs waiting in your repository every morning. Like a Roomba for your codebase, but instead of picking up crumbs, it's finding vulnerabilities you didn't know existed. This isn't science fiction—it's Nightshift, and it's about to change how you think about code maintenance forever.

What is Nightshift?

Nightshift is an intelligent code maintenance agent created by Marcus that transforms your leftover LLM token budget into proactive codebase improvements. Born from a simple, brilliant observation—developers pay for AI subscriptions that reset weekly, yet most of those tokens go unused—the tool operates on a "use it or lose it" philosophy that turns waste into value.

The project lives at github.com/marcus/nightshift and has been gaining serious traction among developers who are tired of reactive maintenance. Its tagline perfectly captures the essence: "It finds what you forgot to look for." And that's exactly the problem. Modern development moves too fast for manual audits. Security issues, dead code, documentation drift, test gaps—these aren't exciting problems, but they're expensive problems when they explode in production.

Nightshift's core innovation is budget-aware automation. Unlike traditional static analysis tools that run blindly, Nightshift respects your LLM spending limits, never exceeding a configurable maximum (default 75% of daily allotment). It supports multiple AI providers—Claude Code, OpenAI Codex, and GitHub Copilot—giving you flexibility in how you allocate your existing subscriptions. The tool runs as a daemon, scheduling overnight jobs that analyze your repositories and generate pull requests with findings.

What makes Nightshift genuinely different is its zero-risk operational model. Every finding lands as a branch or PR. It never writes directly to your primary branch. Don't like a suggestion? Close it. That's the entire rollback strategy. This design choice removes the fear that stops most teams from adopting automated code modification tools. You're always in control, always able to review, never forced to accept changes blindly.

Key Features That Make Nightshift Irresistible

Budget-Aware Intelligence — Nightshift doesn't just burn through your tokens indiscriminately. It actively monitors remaining daily allotments, respects configurable maximums, and even includes calibration features to optimize spending over time. The budget command family gives you granular visibility: nightshift budget --provider claude shows current status, nightshift budget history -n 10 reveals spending patterns, and nightshift budget calibrate fine-tunes estimates based on actual usage.

Multi-Project Orchestration — Point Nightshift at multiple repositories and it "already knows what to look for." The tool auto-discovers project structures, identifies relevant tasks per codebase, and manages execution across your entire portfolio. Configuration happens through clean YAML files, not complex scripting.

Zero-Risk Execution Model — This cannot be overstated. Every Nightshift action creates a PR. No direct commits to main. No forced merges. The worst-case scenario? You wake up, see a branch you don't like, and close it. This architectural decision transforms automated code modification from "scary" to "obvious."

Exceptional Developer Experience — Thoughtful CLI defaults with clear output, multiple preview modes (--plain, --json, --explain), and integration with gum for beautiful terminal pagers. The nightshift doctor command checks environment health. The nightshift preview family lets you inspect exactly what would happen before it happens.

20+ Automated Task Types — Beyond dead code and security issues, Nightshift handles doc drift detection, test gap identification, lint fixing, skill grooming for AI assistants, and more. Tasks are categorized (pr, analysis, options, safe, map, emergency) and cost-tiered (low, medium, high, veryhigh) for intelligent scheduling.

Smart Scheduling & Cooldowns — Each task has default intervals preventing over-execution. lint-fix won't run more than every 24 hours; docs-backfill and skill-groom default to weekly. Override per-task in configuration when your project demands different rhythms.

Real-World Use Cases Where Nightshift Shines

The Legacy Codebase Archaeologist — You've inherited a 50,000-line monolith. Nobody knows which functions are dead, which imports are ghost dependencies, which security patterns are outdated. Manual audit? Weeks of developer time. Nightshift? Runs overnight, surfaces findings as reviewable PRs. You merge what makes sense, close what doesn't, and build institutional knowledge without the archaeological dig.

The Fast-Moving Startup — Shipping daily means documentation dies weekly. Your API docs drift, your README becomes fiction, your onboarding guide misleads new hires. Nightshift's docs-backfill task detects these gaps and proposes updates. The skill-groom task even keeps your AI assistant skills current, ensuring Claude and Codex understand your evolving codebase.

The Security-Conscious Team — Security audits get postponed because they're "not urgent until they're critical." Nightshift's continuous, low-cost scanning finds issues before they become incidents. The budget-aware model means you're spending pennies of existing subscription money, not allocating new security tool budgets.

The Multi-Repo Maintainer — Open source maintainers juggling ten repositories know the pain: which repo needs attention? Nightshift's multi-project configuration lets you define all targets in one YAML file, automatically distributing attention based on task priorities, cooldown intervals, and available budget.

The "We'll Clean It Later" Team — Every team has technical debt they're "getting to." Nightshift removes the activation energy. No tickets to create, no sprints to allocate. Just configure once, let it run, and review PRs when convenient. The friction drops from "schedule a refactoring sprint" to "check GitHub in the morning."

Step-by-Step Installation & Setup Guide

Getting Nightshift running takes minutes, not hours. Choose your installation path:

macOS (Homebrew — Recommended)

# Tap the repository and install
brew install marcus/tap/nightshift

Go Install (Cross-Platform)

# Requires Go toolchain installed
go install github.com/marcus/nightshift/cmd/nightshift@latest

Binary Download

Grab prebuilt binaries from the GitHub releases page for your platform.

Initial Configuration

After installation, run the guided setup wizard:

# Interactive setup: provider config, project selection, budget calibration
nightshift setup

This creates your global configuration at ~/.config/nightshift/config.yaml. Verify everything works:

# Check environment and configuration health
nightshift doctor

# Preview what Nightshift would do on next run
nightshift preview

# Check current budget status
nightshift budget

Authenticate Your AI Provider

For Claude Code:

claude
/login
# Follow prompts for Claude.ai subscription or Anthropic Console credentials

For Codex:

codex --login
# Sign in with ChatGPT account or provide API key

For GitHub Copilot:

# Install Copilot CLI first
npm install -g @github/copilot
# Or use the install script
curl -fsSL https://gh.io/copilot-install | bash
# Requires active GitHub Copilot subscription

Configure Your First Project

Edit ~/.config/nightshift/config.yaml with your project paths and preferences:

# Minimal configuration example
schedule:
  cron: "0 2 * * *"  # Run daily at 2 AM

budget:
  mode: daily
  max_percent: 75      # Never use more than 75% of daily budget
  reserve_percent: 5   # Keep 5% emergency reserve
  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/your-project
  - path: ~/code/another-project

Start the daemon for automated overnight runs:

# Start background service
nightshift daemon start

# Or run immediately for testing
nightshift run --dry-run  # Preview without executing
nightshift run            # Interactive run with confirmation

REAL Code Examples from Nightshift

Let's examine actual usage patterns from the Nightshift repository, with detailed explanations of what each command accomplishes.

Example 1: Preview Commands — Inspect Before You Execute

# Preview next 3 scheduled runs with prompt previews
nightshift preview -n 3

# Show extended details including full prompt content
nightshift preview --long

# Add human-readable explanations of what each task does
nightshift preview --explain

# Plain text output (no gum pager, no colors)
nightshift preview --plain

# Machine-readable JSON output for scripting/integration
nightshift preview --json

# Write prompts to files for manual inspection or debugging
nightshift preview --write ./nightshift-prompts

What's happening here? The preview command is Nightshift's safety mechanism and transparency layer. Before any tokens are spent, you can inspect exactly what would run, when, and why. The -n 3 flag limits output to three upcoming runs. The --long variant reveals the actual prompts sent to LLMs—crucial for understanding why certain tasks were selected. The --explain flag adds natural language descriptions, making output shareable with non-technical stakeholders. For CI/CD integration, --json provides structured data, while --write exports prompts for offline review or custom tooling.

Example 2: Task Inspection and Targeted Execution

# List all available tasks with their categories and costs
nightshift task list

# Filter to PR-generating tasks only
nightshift task list --category pr

# Find cheap tasks, output as JSON for filtering
nightshift task list --cost low --json

# Deep-dive into specific task implementation
nightshift task show lint-fix
nightshift task show skill-groom

# View only the raw prompt (useful for piping/debugging)
nightshift task show lint-fix --prompt-only

# Execute specific task with provider selection
nightshift task run lint-fix --provider claude

# Dry-run: see exactly what would happen without spending tokens
nightshift task run skill-groom --provider codex --dry-run
nightshift task run lint-fix --provider codex --dry-run

The power of explicit task control. While Nightshift's automatic task selection is intelligent, sometimes you need precision. task list --category pr shows only tasks that generate pull requests—filtering out analysis-only or mapping tasks when you want actionable output. The --cost low filter helps when budget is tight. task show reveals implementation details, including the planning prompt that guides LLM behavior. This transparency is rare in AI tools and invaluable for debugging unexpected results. The --prompt-only output enables advanced workflows: pipe prompts to custom processors, diff against previous versions, or audit for prompt injection risks.

Example 3: Production Run with Full Control Flags

# Standard interactive run: preflight summary + confirmation prompt
nightshift run

# Non-interactive mode for cron/CI: auto-confirm
nightshift run --yes

# Preview mode: show preflight, exit before execution
nightshift run --dry-run

# Scale up: process 3 projects with 2 tasks each
nightshift run --max-projects 3 --max-tasks 2

# Randomize task selection for broader coverage
nightshift run --random-task

# Emergency override: bypass budget limits (shows warning)
nightshift run --ignore-budget

# Surgical strike: specific project and task
nightshift run -p ./my-project -t lint-fix

Understanding the preflight summary. Before executing, nightshift run displays critical information: selected provider, current budget status, target projects, and planned tasks. In interactive terminals, you're prompted to confirm; in non-TTY environments (cron jobs, GitHub Actions, systemd timers), confirmation auto-skips for seamless automation. The --max-projects and --max-tasks flags prevent runaway execution—essential when first configuring or testing. --random-task diversifies findings over time instead of always picking the highest-scored task. The --ignore-budget emergency escape hatch exists for critical situations, but the explicit warning ensures conscious use.

Example 4: Advanced Configuration — Task Selection and Priorities

# Task selection with priorities, enablement, and cooldown intervals
tasks:
  enabled:
    - lint-fix
    - docs-backfill
    - bug-finder
  disabled:
    - skill-groom    # Opt out of default-enabled task
  priorities:
    lint-fix: 1      # Highest priority (lower number = higher priority)
    skill-groom: 2
    bug-finder: 2
  intervals:
    lint-fix: "24h"      # Run at most once per day
    skill-groom: "168h"  # Run weekly (7 days)
    docs-backfill: "168h"

Precision control over automation behavior. This configuration demonstrates Nightshift's sophistication. The enabled list explicitly includes desired tasks; disabled opts out of defaults like skill-groom (which updates .claude/skills and .codex/skills using README.md context). Priority values determine selection order when multiple tasks are eligible—lint-fix at 1 always wins against bug-finder at 2. The intervals map prevents task saturation: even if budget and priority allow, lint-fix won't run more than every 24 hours. These cooldowns respect both your token budget and your code review bandwidth.

Advanced Usage & Best Practices

Calibrate, Don't Guess — Run nightshift budget calibrate weekly for the first month. Nightshift learns your actual token consumption patterns and improves estimates. The snapshot_interval: 30m setting in config enables fine-grained budget tracking.

Preview Before You Sleep — Make nightshift preview --explain part of your end-of-day routine. Understand what will run overnight, adjust task priorities if needed, and never be surprised by morning PRs.

Use --dry-run in CI — Integrate nightshift run --dry-run into pull request checks. This validates configuration changes without spending tokens, catching errors before they reach your scheduled runs.

Monitor with status --today — The nightshift status --today command shows activity summary. Add this to your morning routine to quickly assess what Nightshift found overnight.

Daemon Debugging — When troubleshooting scheduled runs, use nightshift daemon start --foreground to see real-time logs. Exit with Ctrl-C when satisfied.

Task Cost Optimization — Use nightshift task list --cost low --json to identify budget-friendly tasks. When tokens are tight, these provide maximum value per dollar.

Skill-Groom Strategy — The default-enabled skill-groom task improves your AI assistant's project understanding. Keep it enabled unless you're manually curating skills files. It pulls from https://agentskills.io/llms.txt for current best practices.

Comparison with Alternatives

Why Nightshift wins: It occupies a unique intersection—intelligent analysis powered by existing AI subscriptions, with zero-risk execution and genuine automation. Traditional tools find syntax issues; Nightshift finds semantic problems that require understanding. Static analysis platforms cost thousands and need dedicated infrastructure; Nightshift runs on your laptop using tokens you'd otherwise waste. Manual review is thorough but unsustainable at scale; Nightshift provides continuous, cost-effective coverage.

FAQ

Is Nightshift free? The tool itself is MIT-licensed and free. You pay only for the LLM tokens consumed, which come from existing Claude, Codex, or Copilot subscriptions you'd otherwise underutilize.

Can Nightshift break my code? No. Nightshift never writes directly to primary branches. Everything arrives as a reviewable PR. The worst case is closing a branch you don't want. This is architectural, not optional.

How much does it cost to run? Highly variable based on codebase size and task selection. The default 75% budget cap prevents runaway spending. Most users report spending less than $5/week in otherwise-wasted subscription allocation.

Does it work with private repositories? Yes. Nightshift operates on local code with local AI CLI tools. Your code never leaves your machine unless you choose to push generated branches to remote hosts.

What if I don't like a task's suggestions? Close the PR. No merge required, no configuration needed. You can also disable specific tasks in config.yaml or adjust their priorities and cooldown intervals.

Can I run it without scheduling? Absolutely. nightshift run executes on-demand. The daemon and cron scheduling are optional conveniences, not requirements.

Which provider works best? Claude Code and Codex offer the most mature integrations. GitHub Copilot support is newer; check docs/COPILOT_INTEGRATION.md for current capabilities.

Conclusion

Nightshift represents a genuinely new category of developer tool: budget-positive automation that transforms waste into value. In an industry obsessed with shipping features, it addresses the unglamorous reality that codebases accumulate invisible debt—dead code, security gaps, documentation drift—until they become visible crises.

The genius is in the execution model. By making every action a PR, Nightshift removes the fear that blocks adoption of automated code modification. By respecting existing subscription budgets, it removes the budget justification friction. By running overnight, it removes the time allocation problem. The "worst case you close the PR" philosophy turns a potentially scary tool into an obvious one.

After reviewing the architecture, the thoughtful CLI design, and the real-world applicability, I'm convinced this is how maintenance should work in the LLM era. Not massive refactoring sprints scheduled quarterly. Not ignored static analysis dashboards. Continuous, intelligent, reviewable improvement that costs essentially nothing.

Stop letting your tokens expire worthless. Install Nightshift tonight, configure your first project, and wake up to cleaner code tomorrow. The repository is waiting at github.com/marcus/nightshift—star it, install it, and never waste another token.