Nightshift

Your AI agent has nothing to do tonight. Put it to work.

Nightshift is a repo quality audit skill for Claude Code and OpenAI Codex. Run it before bed — wake up to a prioritized report of dead code, doc drift, test gaps, security issues, and tech debt.

What It Does

Nightshift runs 10-14 read-only checks against your repo and produces structured reports:

Check	What it finds
Dead code	Orphan files, unused exports, stale scripts
Doc drift	Broken paths, outdated instructions, stale references
Test gaps	Changed code without test updates, failing tests
Dependencies	Known vulnerabilities, outdated packages, hardcoded secrets
Code quality	Lint/type errors, bug patterns, logic defects, injection risks
Tech debt	Stale TODOs, suppression abuse, large files, complex functions
Refactoring	DRY opportunities, extract-worthy blocks, module organization
Duplicate logic	Near-identical code blocks across files (deep mode)
Architecture	Circular deps, god files, layer violations (deep mode)
Churn hotspots	High-churn files correlated with failures (deep mode)
Crontab drift	Live vs repo crontab comparison (infra, opt-in)
Container health	Docker container status checks (infra, opt-in)
Backup verification	Backup recency and log checks (infra, opt-in)
Script drift	Deployed vs repo script comparison (infra, opt-in)

Output

.nightshift/runs/2026-02-17_02-00-00/
├── executive-report.md   # Morning brief — what to fix first
├── findings.md           # Full technical detail per check
├── summary.json          # Machine-readable results (schema v1)
├── run.log               # Execution trace with timings
└── raw/                  # Tool outputs and evidence

Install

Claude Code

Copy the claude-code/nightshift/ directory to your Claude Code skills:

# Global (all repos)
mkdir -p ~/.claude/skills/nightshift/ && cp -r claude-code/nightshift/ ~/.claude/skills/nightshift/

# Per-project
mkdir -p .claude/skills/nightshift/ && cp -r claude-code/nightshift/ .claude/skills/nightshift/

Then run it:

/nightshift
/nightshift deep
/nightshift --budget fast --since HEAD~10
/nightshift --infra

Codex

Copy the codex/ directory to your Codex skills:

# Global (all repos)
mkdir -p ~/.agents/skills/nightshift/ && cp -r codex/ ~/.agents/skills/nightshift/

# Per-project
mkdir -p .agents/skills/nightshift/ && cp -r codex/ .agents/skills/nightshift/

Then run it:

$nightshift
$nightshift mode=deep budget=max
$nightshift since=HEAD~5 infra=true

Configuration

Budget Modes

Budget	Depth	Runtime	When to use
fast	Changed files, lint/typecheck	5-10 min	Quick check after a PR
standard	Grep + read flagged files	15-30 min	Default overnight
max	Read all source files	30-60 min	Pre-release, quarterly

Suppression: .nightshift-ignore

Place at repo root to suppress known findings:

# Suppress a specific finding
id=AUTH-REFRESH-DUP; reason=Known backlog item; expires=2026-03-31

# Suppress all refactoring findings in legacy code
check=refactoring; path=src/legacy/**; reason=Queued for rewrite; expires=never

# Suppress a critical finding (requires explicit opt-in)
id=SEC-OLD-123; reason=Accepted until migration; expires=2026-04-15; allow_critical=true

Suppressed findings stay visible in reports — they're never hidden.

Infrastructure Drift: .nightshift-infra.yaml

Infra checks are opt-in — without this file, they're skipped entirely.

The built-in checks are designed for SSH-accessible Linux servers and cover:

Check	What it compares
crontab	Live crontab -l output vs a committed crontab file
backup	Recent journalctl entries for a backup service
containers	docker ps output for running containers
scripts	Deployed scripts vs repo copies (detects drift)

All SSH commands are restricted to a hardcoded allowlist — no arbitrary command execution from config.

Example config:

targets:
  - name: web-server
    ssh_alias: my-web-server
    checks:
      - crontab
      - backup
      - scripts
    crontab_repo_path: deploy/crontabs/web-server.crontab
    backup_journal_unit: backup.service
    backup_journal_lines: 5
    script_mappings:
      - repo: deploy/scripts/backup.sh
        live: /opt/scripts/backup.sh

  - name: app-server
    ssh_alias: my-app-server
    checks:
      - containers
      - scripts
    script_mappings:
      - repo: deploy/scripts/db-backup.sh
        live: /opt/scripts/db-backup.sh

Adapting to your setup: The built-in checks assume traditional Linux servers with SSH access. If your infrastructure is different (Kubernetes, cloud-managed, serverless, CI/CD pipelines), you can modify the infra check logic in the skill files to match your environment — for example, replacing ssh + crontab -l with kubectl commands or cloud CLI calls. The core audit (checks 1-10) works everywhere regardless.

Schema

Both engines produce compatible summary.json with schema version "1" and the same core structure. The engine field ("claude" or "codex") identifies which tool ran the audit.

Key enums:

• Status: pass | warn | fail | skipped
• Severity: critical | high | medium | low | info
• Effort: S | M | L
• Kind: defect | improvement
• State: new | existing | resolved

See codex/references/report-schema.md for the full schema contract.

Design Principles

• Read-only. Never modifies your source code, configs, or dependencies. Only writes to .nightshift/ and optionally knowledge/learnings/. (Toolchain commands like npm test may create transient caches in their own directories — that's standard behavior, not a Nightshift side effect.)
• Conservative. Every finding includes a confidence level. Low-confidence findings are downgraded. False positives waste your morning.
• Graceful degradation. Missing tools are skipped with a reason, never crash the run.
• Cross-engine compatible. Claude and Codex produce the same JSON schema for automated merging.
• Trend tracking. Compares against previous runs to classify findings as new, existing, or resolved.

Important Notes

• Not standalone software. Nightshift is a set of instructions (prompts) for AI coding agents. It requires Claude Code or OpenAI Codex to run.
• AI output varies. Findings are heuristic and should be reviewed before acting on them. False positives are possible despite confidence scoring.
• SSH infra checks touch remote servers. When enabled, Nightshift runs read-only commands on your servers via SSH. All commands are restricted to a hardcoded allowlist, but review .nightshift-infra.yaml before running --infra on untrusted repos.
• Provided as-is. See LICENSE. No warranty, no guaranteed coverage, no SLA.

See Also

• marcus/nightshift — a different take on the same idea (auto-generates PRs instead of reports)

License

MIT