### Quick Start Installation and Usage

Source: https://github.com/marcus/nightshift/blob/main/website/docs/intro.md

Commands to install Nightshift using Homebrew, set up interactively, preview tasks, and run the tool.

```bash
# Install
brew install marcus/tap/nightshift

# Interactive setup
nightshift setup

# Preview what it will do
nightshift preview

# Run immediately
nightshift run
```

--------------------------------

### Example: Subscription Users

Source: https://github.com/marcus/nightshift/blob/main/docs/deprecated/user-guide.md

Configuration example for subscription-based billing.

```yaml
budget:
  billing_mode: subscription
  calibrate_enabled: true
  snapshot_interval: 30m
  snapshot_retention_days: 90
  week_start_day: monday
```

--------------------------------

### Basic Configuration Example

Source: https://github.com/marcus/nightshift/blob/main/docs/deprecated/user-guide.md

Example of a basic Nightshift configuration file.

```yaml
# Schedule when Nightshift runs
schedule:
  cron: "0 2 * * *"           # Run at 2 AM daily
  # OR
  interval: 4h                 # Run every 4 hours

  window:                      # Optional: only run during these hours
    start: "22:00"
    end: "06:00"
    timezone: "America/Denver"

# Budget controls
budget:
  mode: daily                  # daily | weekly
  max_percent: 75              # Max % of budget per run
  reserve_percent: 5           # Always keep this % in reserve

# Enable/disable task types
tasks:
  enabled:
    - lint
    - docs
    - security
    - dead-code
  disabled:
    - idea-generator
```

--------------------------------

### Guided Setup

Source: https://github.com/marcus/nightshift/blob/main/README.md

Initiates the guided setup process for Nightshift, which includes provider configuration, project selection, budget calibration, and daemon setup.

```bash
nightshift setup
```

--------------------------------

### Example Old Config

Source: https://github.com/marcus/nightshift/blob/main/docs/MIGRATION-v0.3.0-to-v0.3.1.md

An example of a configuration file from v0.3.0 that will still load correctly in v0.3.1.

```yaml
budget:
  mode: daily
  max_percent: 75
logging:
  level: info
```

--------------------------------

### Equivalent direct invocation

Source: https://github.com/marcus/nightshift/blob/main/docs/guides/provider-calibration.md

Example of directly invoking the provider calibration Go program.

```bash
go run ./cmd/provider-calibration \
  --repo /absolute/path/to/your/repo \
  --codex-originator codex_cli_rs \
  --min-user-turns 2
```

--------------------------------

### Preview Options Examples

Source: https://github.com/marcus/nightshift/blob/main/website/docs/cli-reference.md

Examples demonstrating various ways to use the `nightshift preview` command.

```bash
nightshift preview                # Default view
nightshift preview -n 3           # Next 3 runs
nightshift preview --long         # Detailed view
nightshift preview --explain      # With prompt previews
nightshift preview --plain        # No pager
nightshift preview --json         # JSON output
nightshift preview --write ./dir  # Write prompts to files
```

--------------------------------

### Budget Commands Examples

Source: https://github.com/marcus/nightshift/blob/main/website/docs/cli-reference.md

Examples demonstrating various ways to use the `nightshift budget` commands.

```bash
nightshift budget                 # Current status
nightshift budget --provider claude
nightshift budget snapshot --local-only
nightshift budget history -n 10
nightshift budget calibrate
```

--------------------------------

### Check Results

Source: https://github.com/marcus/nightshift/blob/main/website/docs/quick-start.md

Review what happened.

```bash
nightshift status --today
```

--------------------------------

### Run Options Examples

Source: https://github.com/marcus/nightshift/blob/main/website/docs/cli-reference.md

Examples demonstrating various ways to use the `nightshift run` command with different flags.

```bash
nightshift run                          # Preflight + confirm + execute (1 project, 1 task)
nightshift run --yes                    # Skip confirmation
nightshift run --dry-run                # Show preflight, don't execute
nightshift run --max-projects 3         # Process up to 3 projects
nightshift run --max-tasks 2            # Run up to 2 tasks per project
nightshift run --random-task            # Pick a random eligible task
nightshift run --ignore-budget          # Bypass budget limits (use with caution)
nightshift run --project ~/code/myapp   # Target specific project (ignores --max-projects)
nightshift run --task lint-fix          # Run specific task (ignores --max-tasks)
```

--------------------------------

### Task Commands Examples

Source: https://github.com/marcus/nightshift/blob/main/website/docs/cli-reference.md

Examples demonstrating various ways to use the `nightshift task` commands.

```bash
nightshift task list              # All tasks
nightshift task list --category pr
nightshift task list --cost low --json
nightshift task show lint-fix
nightshift task show lint-fix --prompt-only
nightshift task run lint-fix --provider claude
nightshift task run lint-fix --provider codex --dry-run
```

--------------------------------

### Multi-Project Setup

Source: https://github.com/marcus/nightshift/blob/main/docs/deprecated/user-guide.md

Configuration for managing multiple projects using paths or glob patterns, with priority settings.

```yaml
# In global config (~/.config/nightshift/config.yaml)
projects:
  - path: ~/code/project1
    priority: 1                # Higher priority = processed first
    tasks:
      - lint
      - docs
  - path: ~/code/project2
    priority: 2

  # Or use glob patterns
  - pattern: ~/code/oss/*
    exclude:
      - ~/code/oss/archived
```

--------------------------------

### Human-readable report

Source: https://github.com/marcus/nightshift/blob/main/docs/guides/provider-calibration.md

Example of running the provider calibration script to generate a human-readable report.

```bash
scripts/provider-calibration \
  --repo /absolute/path/to/your/repo \
  --codex-originator codex_cli_rs \
  --min-user-turns 2
```

--------------------------------

### Verify Installation

Source: https://github.com/marcus/nightshift/blob/main/website/docs/installation.md

Verify the Nightshift installation by checking the version and help output.

```bash
nightshift --version
nightshift --help
```

--------------------------------

### Manual Installation using Go

Source: https://github.com/marcus/nightshift/blob/main/README.md

Installs the Nightshift CLI manually using the Go toolchain.

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

--------------------------------

### Install as System Service

Source: https://github.com/marcus/nightshift/blob/main/docs/deprecated/user-guide.md

Commands to install Nightshift as an automatic overnight service on different operating systems.

```bash
# macOS
nightshift install launchd
```

```bash
# Linux
nightshift install systemd
```

```bash
# Universal (cron)
nightshift install cron
```

--------------------------------

### Build from Repository

Source: https://github.com/marcus/nightshift/blob/main/website/docs/installation.md

Clone the repository and build Nightshift from source.

```bash
git clone https://github.com/marcus/nightshift.git
cd nightshift
go build -o nightshift ./cmd/nightshift
sudo mv nightshift /usr/local/bin/
```

--------------------------------

### Run with options

Source: https://github.com/marcus/nightshift/blob/main/website/docs/quick-start.md

Use --dry-run to preview without executing, or --yes to skip the prompt.

```bash
nightshift run --dry-run    # Preview only
nightshift run --yes        # Skip confirmation
```

--------------------------------

### Deployment Workflow

Source: https://github.com/marcus/nightshift/blob/main/docs/guides/website.md

GitHub Actions workflow for deploying the website.

```yaml
# .github/workflows/deploy-docs.yml
# Builds with Node 20, `npm ci && npm run build`
# Deploys `website/build` to GitHub Pages via `actions/deploy-pages@v4`
```

--------------------------------

### Example Configuration for Subscription Users

Source: https://github.com/marcus/nightshift/blob/main/docs/implemented/budget-inference-plan.md

Example configuration snippet for users on a subscription billing mode.

```yaml
billing_mode: subscription
snapshot_interval: 1h
snaphot_retention_days: 7
week_start_day: 0
db_path: "/var/lib/nightshift/nightshift.db"
```

--------------------------------

### Development Commands

Source: https://github.com/marcus/nightshift/blob/main/docs/guides/website.md

Commands for developing the website locally.

```bash
cd website
npm install
npm start          # Dev server at localhost:3000
npm run build      # Production build to build/
npm run serve      # Serve production build locally
```

--------------------------------

### Machine-readable report

Source: https://github.com/marcus/nightshift/blob/main/docs/guides/provider-calibration.md

Example of running the provider calibration script to generate a JSON report, redirecting output to a file.

```bash
scripts/provider-calibration \
  --repo /absolute/path/to/your/repo \
  --codex-originator codex_cli_rs \
  --min-user-turns 2 \
  --json > /tmp/provider-calibration.json
```

--------------------------------

### Custom Task Configuration Example

Source: https://github.com/marcus/nightshift/blob/main/docs/guides/adding-tasks.md

Example YAML configuration for custom tasks.

```yaml
tasks:
  custom:
    - type: pr-review
      name: "PR Review Session"
      description: |
        Review all open PRs. Fix obvious issues immediately.
        Create tasks for bigger problems that need follow-up.
      category: pr
      cost_tier: high
      risk_level: medium
      interval: "72h"

    - type: security-scan
      name: "Custom Security Scan"
      description: |
        Scan for hardcoded credentials and secrets.
        Check for SQL injection and XSS vulnerabilities.
      category: analysis
      cost_tier: medium
      risk_level: low
      interval: "48h"
```

--------------------------------

### Install GitHub Copilot CLI

Source: https://github.com/marcus/nightshift/blob/main/README.md

Commands to install the GitHub Copilot CLI.

```bash
npm install -g @github/copilot
```

```bash
curl -fsSL https://gh.io/copilot-install | bash
```

--------------------------------

### System Service Installation Commands

Source: https://github.com/marcus/nightshift/blob/main/docs/deprecated/user-guide.md

Bash commands for installing Nightshift as a system service on different platforms (macOS, Linux) or using cron.

```bash
# macOS (launchd)
nightshift install launchd

# Linux (systemd)
nightshift install systemd

# Any platform (cron)
nightshift install cron
```

--------------------------------

### Working Directory

Source: https://github.com/marcus/nightshift/blob/main/docs/guides/agent-tmux-integration.md

Examples showing how to set the working directory for a tmux session when starting Claude Code.

```bash
tmux new-session -d -s "$SESSION" -c "/path/to/project"
```

```bash
tmux send-keys -t "$SESSION" 'cd /path/to/project && claude' Enter
```

--------------------------------

### Example Configuration for API Users

Source: https://github.com/marcus/nightshift/blob/main/docs/implemented/budget-inference-plan.md

Example configuration snippet for users on an API billing mode.

```yaml
billing_mode: api
calibrate_enabled: false
snapshot_retention_days: 7
week_start_day: 0
db_path: "/var/lib/nightshift/nightshift.db"
```

--------------------------------

### Setup and Doctor Commands

Source: https://github.com/marcus/nightshift/blob/main/README.md

Commands for initial setup and environment health checks.

```bash
# Guided global setup
nightshift setup

# Check environment and config health
nightshift doctor
```

--------------------------------

### Installation using Homebrew

Source: https://github.com/marcus/nightshift/blob/main/README.md

Installs the Nightshift CLI using the Homebrew package manager.

```bash
brew install marcus/tap/nightshift
```

--------------------------------

### Global Configuration Example

Source: https://github.com/marcus/nightshift/blob/main/docs/implemented/initial-spec.md

Example of how to configure projects in the global Nightshift config file.

```yaml
# In global config
projects:
  # Explicit list
  - path: ~/code/project1
  - path: ~/code/project2

  # Or glob pattern
  - pattern: ~/code/oss/*
    exclude:
      - ~/code/oss/archived
```

--------------------------------

### Preview Command Examples

Source: https://github.com/marcus/nightshift/blob/main/README.md

Various options for the `nightshift preview` command to customize output.

```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
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/marcus/nightshift/blob/main/README.md

Command to install the git pre-commit hook.

```bash
make install-hooks
```

--------------------------------

### Initialize Configuration

Source: https://github.com/marcus/nightshift/blob/main/docs/deprecated/user-guide.md

Commands to set up Nightshift configuration, either globally or per project.

```bash
nightshift setup
```

```bash
cd ~/code/myproject
nightshift init
```

```bash
nightshift init --global
```

--------------------------------

### Minimal Configuration Example

Source: https://github.com/marcus/nightshift/blob/main/README.md

A minimal YAML configuration file for Nightshift.

```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
```

--------------------------------

### Website Structure

Source: https://github.com/marcus/nightshift/blob/main/docs/guides/website.md

Directory structure of the website project.

```tree
website/
├── docusaurus.config.js      # Site config, navbar, footer, fonts
├── sidebars.js               # Docs nav structure
├── package.json
├── src/
│   ├── css/custom.css        # All custom styling (ns-* prefix)
│   └── pages/index.js        # Landing page (React)
├── docs/                     # Markdown documentation
│   ├── intro.md
│   ├── installation.md
│   ├── quick-start.md
│   ├── configuration.md
│   ├── tasks.md
│   ├── budget.md
│   ├── scheduling.md
│   ├── cli-reference.md
│   └── integrations.md
└── static/
    ├── CNAME                 # nightshift.haplab.com
    ├── .nojekyll
    └── img/                  # Logos (nightshift, haplab, sidecar, betamax, td)
```

--------------------------------

### Create project config

Source: https://github.com/marcus/nightshift/blob/main/docs/deprecated/user-guide.md

Command to create a project configuration file.

```bash
nightshift init
```

--------------------------------

### Multi-Project Setup

Source: https://github.com/marcus/nightshift/blob/main/website/docs/configuration.md

Configuration for setting up multiple projects, including priorities, specific tasks, and glob patterns with exclusions.

```yaml
projects:
  - path: ~/code/project1
    priority: 1                # Higher priority = processed first
    tasks:
      - lint
      - docs
  - path: ~/code/project2
    priority: 2

  # Or use glob patterns
  - pattern: ~/code/oss/*
    exclude:
      - ~/code/oss/archived
```

--------------------------------

### Testing Upgrade - Database Functionality

Source: https://github.com/marcus/nightshift/blob/main/docs/MIGRATION-v0.3.0-to-v0.3.1.md

Command to test if the database still works after upgrading.

```bash
nightshift run --dry-run
```

--------------------------------

### Help Commands

Source: https://github.com/marcus/nightshift/blob/main/website/docs/troubleshooting.md

Commands to get help information for Nightshift.

```bash
nightshift --help
nightshift <command> --help
```

--------------------------------

### Custom Tasks Configuration

Source: https://github.com/marcus/nightshift/blob/main/website/docs/tasks.md

Example YAML configuration for defining a custom task.

```yaml
tasks:
  custom:
    - type: pr-review
      name: "PR Review Session"
      description: |
        Review all open PRs. Fix obvious issues immediately.
        Create tasks for bigger problems.
      category: pr
      cost_tier: high
      risk_level: medium
      interval: "72h"
```

--------------------------------

### Immediate Run Command

Source: https://github.com/marcus/nightshift/blob/main/README.md

Starts an immediate run of Nightshift.

```bash
nightshift run
```

--------------------------------

### Track Changes Over Time Example

Source: https://github.com/marcus/nightshift/blob/main/docs/bus-factor.md

Example of how to track bus factor changes over time by running the analysis regularly with the --save flag.

```bash
# Run regularly with --save
nightshift busfactor --save

# View historical trends
# Results stored in database at ~/.local/share/nightshift/nightshift.db
```

--------------------------------

### Bus Factor Metric Example

Source: https://github.com/marcus/nightshift/blob/main/docs/bus-factor.md

Example calculation of Bus Factor based on contributor commit percentages.

```text
Contributors: A(50%), B(25%), C(15%), D(10%)
Bus Factor: 1 (A alone = 50%)
```

--------------------------------

### Create global config

Source: https://github.com/marcus/nightshift/blob/main/docs/deprecated/user-guide.md

Command to create a global configuration file.

```bash
nightshift init --global
```

--------------------------------

### System Service Installation

Source: https://github.com/marcus/nightshift/blob/main/website/docs/scheduling.md

Commands to install Nightshift as a system service for automatic startup on different operating systems.

```bash
# macOS (launchd)
nightshift install launchd

# Linux (systemd)
nightshift install systemd

# Universal (cron)
nightshift install cron
```

--------------------------------

### Task Selection Configuration Example

Source: https://github.com/marcus/nightshift/blob/main/README.md

YAML configuration for enabling and prioritizing tasks.

```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"
```

--------------------------------

### Target a specific project and task directly

Source: https://github.com/marcus/nightshift/blob/main/README.md

Example of how to run a specific task on a project.

```bash
nightshift run -p ./my-project -t lint-fix
```

--------------------------------

### Budget Display Example

Source: https://github.com/marcus/nightshift/blob/main/docs/guides/codex-budget-tracking.md

Example output of the budget display showing both rate limit and local token usage.

```plaintext
[codex]
  Mode:         daily
  Weekly:       1.6M tokens (calibrated, high confidence, 7 samples)
  Daily:        228.6K tokens
  Used today:   43.4K (19.0%)
  Remaining:    185.1K tokens
  Rate limit:   19% primary (5h) · 31% weekly
  Local tokens: 451.9K today · 1.2M this week (billable)
  Reserve:      11.4K tokens
  Nightshift:   185.1K remaining x 80% max = 148.1K - 11.4K reserve = 136.7K available
```

--------------------------------

### Testing Upgrade - Config Load

Source: https://github.com/marcus/nightshift/blob/main/docs/MIGRATION-v0.3.0-to-v0.3.1.md

Command to test if the configuration still loads correctly after upgrading.

```bash
nightshift status
```

--------------------------------

### Show specific provider

Source: https://github.com/marcus/nightshift/blob/main/docs/deprecated/user-guide.md

Command to display budget information for a specific provider.

```bash
nightshift budget --provider claude
```

--------------------------------

### Show recent snapshots

Source: https://github.com/marcus/nightshift/blob/main/docs/deprecated/user-guide.md

Command to display recent budget snapshots.

```bash
nightshift budget history -n 20
```

--------------------------------

### Analyze Specific Module Example

Source: https://github.com/marcus/nightshift/blob/main/docs/bus-factor.md

Command to analyze bus factor for files within a specific module.

```bash
nightshift busfactor --file "internal/database/*"
```

--------------------------------

### System Integration Commands

Source: https://github.com/marcus/nightshift/blob/main/docs/implemented/initial-spec.md

Commands for installing and uninstalling system services.

```bash
nightshift install [launchd|systemd|cron]
                                        # Generate and install system service
nightshift uninstall                    # Remove system service
```

--------------------------------

### Initialize Configuration

Source: https://github.com/marcus/nightshift/blob/main/website/docs/troubleshooting.md

Commands to create project or global configuration files.

```bash
nightshift init           # Create project config
nightshift init --global  # Create global config
```

--------------------------------

### Task Cooldown Overrides Example

Source: https://github.com/marcus/nightshift/blob/main/docs/deprecated/user-guide.md

Example of overriding default task cooldown intervals in the configuration.

```yaml
tasks:
  intervals:
    lint-fix: "24h"
    docs-backfill: "168h"
    bug-finder: "72h"
```

--------------------------------

### Optional: Stricter Database Permissions

Source: https://github.com/marcus/nightshift/blob/main/docs/MIGRATION-v0.3.0-to-v0.3.1.md

Apply stricter owner-only access permissions to an existing database directory.

```bash
chmod 0700 ~/.local/share/nightshift
```

--------------------------------

### Enable GitHub Issues Integration

Source: https://github.com/marcus/nightshift/blob/main/docs/deprecated/user-guide.md

YAML configuration to enable GitHub Issues as a task source.

```yaml
integrations:
  task_sources:
    - github_issues
```

--------------------------------

### Add the Registry Entry

Source: https://github.com/marcus/nightshift/blob/main/docs/guides/adding-tasks.md

Example of adding a TaskDefinition to the registry map in Go.

```go
TaskMyNewTask: {
    Type:            TaskMyNewTask,
    Category:        CategoryPR,       // See categories below
    Name:            "My New Task",
    Description:     "What the agent should do, written as instructions",
    CostTier:        CostMedium,       // Estimated token usage
    RiskLevel:       RiskLow,          // Risk of unintended changes
    DefaultInterval: 72 * time.Hour,   // Minimum time between runs per project
}
```

--------------------------------

### Export Results to File Example

Source: https://github.com/marcus/nightshift/blob/main/docs/bus-factor.md

Command to export bus factor analysis results to a JSON file.

```bash
nightshift busfactor --json > analysis.json
```

--------------------------------

### Reading agents.md Example

Source: https://github.com/marcus/nightshift/blob/main/docs/implemented/initial-spec.md

Code snippet demonstrating how to read and utilize information from 'agents.md' for configuring agent behavior and safety constraints.

```go
// Look for agents.md or AGENTS.md
// Extract: agent behavior preferences, tool restrictions
// Use for: configuring agent behavior, safety constraints
```

--------------------------------

### Analyze Recent Changes Example

Source: https://github.com/marcus/nightshift/blob/main/docs/bus-factor.md

Command to analyze bus factor for commits since a specific date.

```bash
nightshift busfactor --since 2025-01-01
```

--------------------------------

### Daemon Mode Commands

Source: https://github.com/marcus/nightshift/blob/main/docs/deprecated/user-guide.md

Bash commands for managing the Nightshift daemon, including starting, checking status, stopping, and running in foreground mode.

```bash
# Start the daemon
nightshift daemon start

# Check status
nightshift daemon status

# Stop the daemon
nightshift daemon stop

# Run in foreground (for debugging)
nightshift daemon start --foreground
```

--------------------------------

### Check Run History Commands

Source: https://github.com/marcus/nightshift/blob/main/docs/deprecated/user-guide.md

Bash commands for checking Nightshift run history, with options to specify the number of runs, view today's summary, and display example output.

```bash
# Show last 5 runs
nightshift status

# Show last 10 runs
nightshift status --last 10

# Today's summary
nightshift status --today
```

--------------------------------

### Collect Budget Samples

Source: https://github.com/marcus/nightshift/blob/main/website/docs/troubleshooting.md

Commands to collect samples for budget calculation.

```bash
nightshift budget snapshot
```

--------------------------------

### Log Format Example

Source: https://github.com/marcus/nightshift/blob/main/docs/implemented/initial-spec.md

Example of the JSON structure for Nightshift log entries.

```json
{
  "timestamp": "2024-01-15T02:30:00Z",
  "level": "info",
  "component": "task_selector",
  "message": "Selected task",
  "task": "dead-code-detector",
  "project": "/Users/dev/myproject",
  "budget_used": 15234,
  "budget_remaining": 84766
}
```

--------------------------------

### Build, Run, and Test Commands

Source: https://github.com/marcus/nightshift/blob/main/AGENTS.md

Basic commands for building, running, and testing the Nightshift CLI tool.

```bash
# Build
go build ./cmd/nightshift

# Run
./nightshift

# Test
go test ./...

```

--------------------------------

### Morning Summary Example

Source: https://github.com/marcus/nightshift/blob/main/docs/implemented/initial-spec.md

Example markdown format for the Nightshift morning summary report.

```markdown
# Nightshift Summary - 2024-01-15

## Budget
- Started with: 100,000 tokens
- Used: 45,234 tokens (45%)
- Remaining: 54,766 tokens

## Projects Processed
1. **myproject** (3 tasks)
2. **library** (1 task)

## Tasks Completed
- [PR #123] Fixed 12 linting issues in myproject
- [Report] Found 3 dead code blocks in library
- [Analysis] Test coverage gaps identified (see report)

## Tasks Skipped (insufficient budget)
- migration-rehearsal (estimated: 200k tokens)

## What's Next?
- Review PR #123 in myproject
- Consider removing dead code in library (see report)
```

--------------------------------

### Nightshift Run Command Examples

Source: https://github.com/marcus/nightshift/blob/main/README.md

Demonstrates various ways to use the `nightshift run` command, including interactive, non-interactive, dry-run, and limiting scope.

```bash
# 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
```

--------------------------------

### Disabling Custom Tasks Example

Source: https://github.com/marcus/nightshift/blob/main/docs/guides/adding-tasks.md

Example YAML configuration for disabling custom tasks.

```yaml
tasks:
  disabled:
    - security-scan
  custom:
    - type: security-scan
      # ...
```

--------------------------------

### Build Command

Source: https://github.com/marcus/nightshift/blob/main/docs/implemented/budget-inference-plan.md

Command to build the project.

```bash
go build ./...
```

--------------------------------

### Hardcoded Artifact Name Example

Source: https://github.com/marcus/nightshift/blob/main/SECURITY_AUDIT.md

Example of a hardcoded artifact name that could lead to conflicts.

```go
const nightshiftPlanIgnore = ".nightshift-plan"
```

--------------------------------

### Low Risk Example Output

Source: https://github.com/marcus/nightshift/blob/main/docs/bus-factor.md

Example output for a low risk level in bus factor analysis.

```text
Risk Level: low
Bus Factor: 3
Total Contributors: 8
Top 1 Contributor: 20.0%
Top 3 Contributor: 55.0%
Herfindahl Index: 0.08
```

--------------------------------

### High Risk Example Output

Source: https://github.com/marcus/nightshift/blob/main/docs/bus-factor.md

Example output for a high risk level in bus factor analysis.

```text
Risk Level: high
Bus Factor: 2
Total Contributors: 3
Top 1 Contributor: 60.0%
Top 3 Contributor: 95.0%
Herfindahl Index: 0.45
```

--------------------------------

### Critical Risk Example Output

Source: https://github.com/marcus/nightshift/blob/main/docs/bus-factor.md

Example output for a critical risk level in bus factor analysis.

```text
Risk Level: critical
Bus Factor: 1
Total Contributors: 1
Top 1 Contributor: 100.0%
Herfindahl Index: 1.0
```

--------------------------------

### Enable Auto-Calibration Configuration

Source: https://github.com/marcus/nightshift/blob/main/website/docs/budget.md

YAML configuration to enable automatic budget calibration and set the snapshot interval.

```yaml
budget:
  calibrate_enabled: true
  snapshot_interval: 30m
```

--------------------------------

### Example: Fetching Usage Stats

Source: https://github.com/marcus/nightshift/blob/main/docs/guides/agent-tmux-integration.md

A bash script demonstrating how to fetch usage statistics from Claude Code by automating the interaction with the CLI via tmux.

```bash
#!/bin/bash
SESSION="claude-usage-$"

# Start session and Claude Code
tmux new-session -d -s "$SESSION"
tmux send-keys -t "$SESSION" 'claude' Enter
sleep 3

# Handle trust prompt (press Enter to confirm)
OUTPUT=$(tmux capture-pane -t "$SESSION" -p)
if echo "$OUTPUT" | grep -q "Do you trust"; then
    tmux send-keys -t "$SESSION" Enter
    sleep 3
fi

# Run /usage command
tmux send-keys -t "$SESSION" '/usage' Enter
sleep 2

# Capture the usage output
USAGE=$(tmux capture-pane -t "$SESSION" -p)

# Extract percentages (example parsing)
WEEKLY_ALL=$(echo "$USAGE" | grep -A1 "Current week (all models)" | grep -oE '[0-9]+%' | head -1)
WEEKLY_SONNET=$(echo "$USAGE" | grep -A1 "Current week (Sonnet only)" | grep -oE '[0-9]+%' | head -1)

echo "Weekly (all models): $WEEKLY_ALL"
echo "Weekly (Sonnet only): $WEEKLY_SONNET"

# Cleanup
tmux send-keys -t "$SESSION" Escape
sleep 1
tmux send-keys -t "$SESSION" '/exit' Enter
sleep 1
tmux kill-session -t "$SESSION" 2>/dev/null
```

--------------------------------

### Codex Rate Limits Example

Source: https://github.com/marcus/nightshift/blob/main/docs/implemented/initial-spec.md

Example JSON structure for Codex rate limits, showing primary and secondary usage percentages and reset times.

```json
{
  "rate_limits": {
    "primary": { "used_percent": 34.0, "window_minutes": 300, "resets_at": 1769896359 },
    "secondary": { "used_percent": 10.0, "window_minutes": 10080, "resets_at": 1770483159 }
  }
}
```

--------------------------------

### Cron-Based Schedule

Source: https://github.com/marcus/nightshift/blob/main/website/docs/scheduling.md

Example of setting a cron schedule for Nightshift.

```yaml
schedule:
  cron: "0 2 * * *"  # Every night at 2am
```

--------------------------------

### Check Budget

Source: https://github.com/marcus/nightshift/blob/main/website/docs/troubleshooting.md

Command to check the current budget status.

```bash
nightshift budget
```

--------------------------------

### Example: Running a Task

Source: https://github.com/marcus/nightshift/blob/main/docs/guides/agent-tmux-integration.md

A bash script that automates running a task in Claude Code, including handling prompts, sending the task, waiting for completion, and capturing the result.

```bash
#!/bin/bash
SESSION="claude-task-$"
TASK="Review the code in src/ and suggest improvements"

tmux new-session -d -s "$SESSION"
tmux send-keys -t "$SESSION" 'claude' Enter
sleep 3

# Handle trust prompt
tmux send-keys -t "$SESSION" Enter
sleep 3

# Send the task
tmux send-keys -t "$SESSION" "$TASK" Enter

# Wait for completion (poll for idle state)
while true; do
    OUTPUT=$(tmux capture-pane -t "$SESSION" -p)
    # Check if prompt is waiting for input (adjust pattern as needed)
    if echo "$OUTPUT" | grep -qE '❯.*$'; then
        break
    fi
    sleep 5
done

# Capture final output
RESULT=$(tmux capture-pane -t "$SESSION" -p -S -1000)  # -S -1000 captures scrollback

# Cleanup
tmux send-keys -t "$SESSION" '/exit' Enter
sleep 1
tmux kill-session -t "$SESSION" 2>/dev/null

echo "$RESULT"
```

--------------------------------

### Codex Configuration

Source: https://github.com/marcus/nightshift/blob/main/docs/guides/codex-budget-tracking.md

Example configuration for Nightshift to track Codex budgets.

```yaml
budget:
  mode: daily              # daily or weekly
  weekly_tokens: 700000    # fallback budget if calibration unavailable
  calibrate_enabled: true  # enable tmux scraping for calibration
  billing_mode: subscription
  max_percent: 80          # nightshift uses up to 80% of remaining budget
  reserve_percent: 5       # hold 5% in reserve
  week_start_day: monday

providers:
  codex:
    enabled: true
    data_path: ~/.codex
```

--------------------------------

### Update the Completeness Test

Source: https://github.com/marcus/nightshift/blob/main/docs/guides/adding-tasks.md

Example of updating the TestRegistryCompleteness function in Go.

```go
taskTypes := []TaskType{
    // ... existing types ...
    TaskMyNewTask,
}
```

--------------------------------

### Calibrator.Calibrate method logic

Source: https://github.com/marcus/nightshift/blob/main/docs/implemented/budget-inference-plan.md

Outlines the logic within the Calibrate method for determining the weekly token budget, including handling different billing modes, enabling calibration, filtering outliers, and scoring confidence.

```go
func (cal *Calibrator) Calibrate(provider provider.Provider) CalibrationResult {
	// 1. Handle API billing mode
	if cal.config.BillingMode == "api" {
		return CalibrationResult{
			InferredBudget: cal.config.WeeklyTokens,
			Confidence:     "high",
			Source:         "api",
		}
	}

	// 2. Handle calibration disabled
	if !cal.config.CalibrateEnabled {
		return CalibrationResult{
			InferredBudget: cal.config.WeeklyTokens,
			Confidence:     "none",
			Source:         "config",
		}
	}

	// 3. Get valid snapshots for current week
	snapshots, err := cal.db.GetSnapshotsForCalibration(provider.Name(), cal.config.GetWeekStart(time.Now()))
	if err != nil {
		// Log error and fallback to config
		return cal.fallbackResult()
	}

	var inferredBudgets []int64
	for _, s := range snapshots {
		if s.ScrapedPct != nil && *s.ScrapedPct >= 10 && *s.ScrapedPct <= 95 && *s.LocalTokens > 0 {
			inferred := int64(float64(*s.LocalTokens) / (*s.ScrapedPct / 100.0))
			inferredBudgets = append(inferredBudgets, inferred)
		}
	}

	// 4. Filter outliers using MAD if enough samples
	if len(inferredBudgets) >= 3 {
		inferredBudgets = cal.filterOutliers(inferredBudgets)
	}

	// 5. Compute median
	medianBudget := cal.calculateMedian(inferredBudgets)

	// 6. Score confidence
	confidence := cal.scoreConfidence(len(inferredBudgets), medianBudget, inferredBudgets)

	// 7. Fallback if no valid data after filtering
	if len(inferredBudgets) == 0 {
		return cal.fallbackResult()
	}

	return CalibrationResult{
		InferredBudget: medianBudget,
		Confidence:     confidence,
		SampleCount:    len(inferredBudgets),
		Variance:       cal.calculateVariance(medianBudget, inferredBudgets),
		Source:         "calibrated",
	}
}

func (cal *Calibrator) fallbackResult() CalibrationResult {
	return CalibrationResult{
		InferredBudget: cal.config.WeeklyTokens,
		Confidence:     "none",
		Source:         "config",
	}
}
```

--------------------------------

### Browse Tasks

Source: https://github.com/marcus/nightshift/blob/main/website/docs/tasks.md

Commands to list and filter built-in tasks by category, cost, or to show task details.

```bash
# List all tasks
nightshift task list

# Filter by category
nightshift task list --category pr
nightshift task list --category analysis

# Filter by cost tier
nightshift task list --cost low
nightshift task list --cost medium

# Show task details
nightshift task show lint-fix
nightshift task show lint-fix --prompt-only
```

--------------------------------

### Enable Debug Mode

Source: https://github.com/marcus/nightshift/blob/main/website/docs/troubleshooting.md

Command to enable verbose logging for debugging.

```bash
nightshift run --verbose
```