From 3a7af159abbc3c446e446c412e1733da80d59257 Mon Sep 17 00:00:00 2001 From: Marcus Vorwaller Date: Sat, 18 Apr 2026 03:28:23 -0700 Subject: [PATCH] docs: backfill CLI and provider docs Nightshift-Task: docs-backfill Nightshift-Ref: https://github.com/marcus/nightshift --- README.md | 58 ++++- website/docs/cli-reference.md | 432 +++++++++++++++++++++++++++++----- website/docs/configuration.md | 280 +++++++++++++++++----- website/docs/integrations.md | 133 +++++++++-- 4 files changed, 768 insertions(+), 135 deletions(-) diff --git a/README.md b/README.md index 84f92cd..c9f73a0 100644 --- a/README.md +++ b/README.md @@ -72,6 +72,11 @@ nightshift preview --write ./nightshift-prompts # Guided global setup nightshift setup +# Inspect and validate config +nightshift config +nightshift config get budget.max_percent +nightshift config validate + # Check environment and config health nightshift doctor @@ -94,7 +99,12 @@ 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 +nightshift task run docs-backfill --provider copilot --dry-run + +# Review results after a run +nightshift report +nightshift logs --summary +nightshift stats --period last-7d ``` If `gum` is available, preview output is shown through the gum pager. Use `--plain` to disable. @@ -115,6 +125,9 @@ daemon, CI) confirmation is auto-skipped. | `--max-tasks` | `1` | Max tasks per project (ignored when `--task` is set) | | `--random-task` | `false` | Pick a random task from eligible tasks instead of the highest-scored one | | `--ignore-budget` | `false` | Bypass budget checks (use with caution) | +| `--branch`, `-b` | _(current branch)_ | Base branch for new feature branches | +| `--timeout` | `30m` | Per-agent execution timeout | +| `--no-color` | `false` | Disable colored output | | `--yes`, `-y` | `false` | Skip the confirmation prompt | ```bash @@ -136,6 +149,9 @@ nightshift run --random-task # Bypass budget limits (shows warning) nightshift run --ignore-budget +# Override the base branch and execution timeout +nightshift run --branch develop --timeout 45m + # Target a specific project and task directly nightshift run -p ./my-project -t lint-fix ``` @@ -146,8 +162,9 @@ Other useful flags: - `--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 +- `--provider` — required for `task run`, choose claude, codex, or copilot - `--dry-run` — preview the prompt without executing +- `--branch` — use a specific base branch for generated work - `--timeout` — execution timeout (default 30m) ## Authentication (Subscriptions) @@ -155,7 +172,7 @@ Other useful flags: Nightshift supports three AI providers: - **Claude Code** - Anthropic's Claude via local CLI - **Codex** - OpenAI's GPT via local CLI -- **GitHub Copilot** - GitHub's Copilot via GitHub CLI +- **GitHub Copilot** - GitHub's Copilot via `gh copilot` or the standalone `copilot` binary ### Claude Code @@ -177,13 +194,16 @@ Supports signing in with ChatGPT or an API key. ### GitHub Copilot ```bash -# Install Copilot CLI +# Authenticate GitHub CLI and install the Copilot extension +gh auth login +gh extension install github/gh-copilot + +# or install the standalone Copilot CLI npm install -g @github/copilot -# or -curl -fsSL https://gh.io/copilot-install | bash +copilot --version ``` -Requires GitHub Copilot subscription. See [docs/COPILOT_INTEGRATION.md](docs/COPILOT_INTEGRATION.md) for details. +Requires GitHub Copilot access. Full setup details: [Integrations docs](https://nightshift.haplab.com/docs/integrations). If you prefer API-based usage, you can authenticate Claude and Codex CLIs with API keys instead. @@ -198,15 +218,29 @@ Nightshift uses YAML config files to define: - Task priorities - Schedule preferences -Run `nightshift setup` to create/update the global config at `~/.config/nightshift/config.yaml`. +Nightshift merges a global config at `~/.config/nightshift/config.yaml` with an optional project-local `nightshift.yaml`. + +Use: + +```bash +nightshift setup # guided global config +nightshift init # create ./nightshift.yaml +nightshift init --global # create ~/.config/nightshift/config.yaml +nightshift config # show merged config + source paths +nightshift config get budget.max_percent +nightshift config set logging.level debug --global +nightshift config validate +``` -See the [full configuration docs](https://nightshift.haplab.com/docs/configuration) or [SPEC.md](docs/SPEC.md) for detailed options. +See the [full configuration docs](https://nightshift.haplab.com/docs/configuration) for detailed options. Minimal example: ```yaml schedule: cron: "0 2 * * *" + max_projects: 3 + max_tasks: 2 budget: mode: daily @@ -220,14 +254,16 @@ providers: preference: - claude - codex + - copilot claude: enabled: true data_path: "~/.claude" - dangerously_skip_permissions: true codex: enabled: true data_path: "~/.codex" - dangerously_bypass_approvals_and_sandbox: true + copilot: + enabled: false + data_path: "~/.copilot" projects: - path: ~/code/sidecar diff --git a/website/docs/cli-reference.md b/website/docs/cli-reference.md index d5a2cd4..0021738 100644 --- a/website/docs/cli-reference.md +++ b/website/docs/cli-reference.md @@ -5,88 +5,410 @@ title: CLI Reference # CLI Reference -## Core Commands +Nightshift ships a single `nightshift` binary with commands for setup, execution, reporting, and service management. + +## Global Flags + +| Flag | Description | +|------|-------------| +| `--verbose` | Enable verbose output | +| `-h`, `--help` | Show help for the current command | +| `-v`, `--version` | Show the current Nightshift version | + +## Root Commands | Command | Description | |---------|-------------| -| `nightshift setup` | Guided global configuration | -| `nightshift run` | Execute scheduled tasks | -| `nightshift preview` | Show upcoming runs | -| `nightshift budget` | Check token budget status | -| `nightshift task` | Browse and run tasks | -| `nightshift doctor` | Check environment health | -| `nightshift status` | View run history | -| `nightshift logs` | Stream or export logs | -| `nightshift stats` | Token usage statistics | -| `nightshift daemon` | Background scheduler | +| `nightshift setup` | Interactive onboarding wizard | +| `nightshift init` | Create a starter config file | +| `nightshift config` | Show, get, set, or validate config | +| `nightshift doctor` | Check config, providers, database, and budget health | +| `nightshift preview` | Preview upcoming runs without executing | +| `nightshift run` | Execute tasks immediately | +| `nightshift task` | List, inspect, or run a single task | +| `nightshift budget` | Show current provider budget status | +| `nightshift status` | Show recent run history | +| `nightshift logs` | Tail, filter, or export logs | +| `nightshift report` | Render run reports in human or machine-readable formats | +| `nightshift stats` | Show aggregate statistics across runs | +| `nightshift busfactor` | Analyze code ownership concentration | +| `nightshift daemon` | Start, stop, or inspect the background daemon | +| `nightshift install` | Install a launchd, systemd, or cron service | +| `nightshift uninstall` | Remove the installed system service | +| `nightshift completion` | Generate shell completion scripts | + +## Setup and Configuration + +### `nightshift setup` + +Runs the interactive onboarding wizard. It creates or updates the global config, checks provider availability, captures a snapshot, previews the next run, and can install the daemon. + +```bash +nightshift setup +``` + +### `nightshift init` + +Creates a starter config file. + +```bash +nightshift init +nightshift init --global +nightshift init --force +``` + +| Flag | Description | +|------|-------------| +| `--global` | Create `~/.config/nightshift/config.yaml` instead of `./nightshift.yaml` | +| `-f`, `--force` | Overwrite an existing config without prompting | + +### `nightshift config` + +Running `nightshift config` with no subcommand prints the merged configuration plus the global and project config source paths. + +```bash +nightshift config +nightshift config get budget.max_percent +nightshift config get providers.preference +nightshift config set budget.max_percent 60 +nightshift config set logging.level debug --global +nightshift config validate +``` + +Subcommands: + +| Subcommand | Description | +|------------|-------------| +| `config get KEY` | Print a config value by key path | +| `config set KEY VALUE` | Write a config value to the current project config if `./nightshift.yaml` exists, otherwise to the global config | +| `config validate` | Validate the current global and project configs | + +`config set` supports: + +| Flag | Description | +|------|-------------| +| `-g`, `--global` | Always write to the global config | + +### `nightshift doctor` + +Checks configuration, schedule resolution, service installation, daemon state, provider CLIs, provider data paths, snapshots, and budget readiness. + +```bash +nightshift doctor +``` + +## Previewing and Running Work -## Run Options +### `nightshift preview` -`nightshift run` shows a preflight summary before executing, then prompts for confirmation in interactive terminals. +Shows what Nightshift would do next without executing tasks or mutating state. ```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) +nightshift preview +nightshift preview -n 5 +nightshift preview --project ~/code/nightshift +nightshift preview --task docs-backfill +nightshift preview --explain +nightshift preview --json +nightshift preview --write ./nightshift-prompts ``` -| Flag | Default | Description | -|------|---------|-------------| -| `--dry-run` | `false` | Show preflight summary and exit without executing | -| `--yes`, `-y` | `false` | Skip confirmation prompt | -| `--max-projects` | `1` | Max projects to process (ignored when `--project` is set) | -| `--max-tasks` | `1` | Max tasks per project (ignored when `--task` is set) | -| `--random-task` | `false` | Pick a random task from eligible tasks instead of the highest-scored one | -| `--ignore-budget` | `false` | Bypass budget checks with a warning | -| `--project`, `-p` | | Target a specific project directory | -| `--task`, `-t` | | Run a specific task by name | +| Flag | Description | +|------|-------------| +| `-n`, `--runs` | Number of upcoming runs to preview | +| `-p`, `--project` | Preview only a specific project path | +| `-t`, `--task` | Preview only a specific task type | +| `--long` | Show full prompts | +| `--write` | Write prompt files to a directory | +| `--explain` | Include budget and task-filter explanations | +| `--plain` | Disable gum pager output | +| `--json` | Emit JSON output, including full prompts | -Non-interactive contexts (daemon, cron, piped output) skip the confirmation prompt automatically. +### `nightshift run` -## Preview Options +Executes tasks immediately. In interactive terminals, Nightshift shows a preflight summary and asks for confirmation. In non-TTY environments such as cron, CI, and the daemon, confirmation is auto-skipped. ```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 +nightshift run +nightshift run --dry-run +nightshift run --yes +nightshift run --project ~/code/nightshift --task docs-backfill +nightshift run --max-projects 3 --max-tasks 2 +nightshift run --random-task +nightshift run --branch main --timeout 45m +nightshift run --ignore-budget ``` -## Task Commands +| Flag | Description | +|------|-------------| +| `--dry-run` | Show the preflight summary and exit without executing | +| `-p`, `--project` | Limit execution to one project directory | +| `-t`, `--task` | Run one specific task type | +| `--max-projects` | Cap how many projects are processed in the run | +| `--max-tasks` | Cap how many tasks run per project | +| `--random-task` | Pick one random eligible task instead of the highest-scored task | +| `--ignore-budget` | Bypass budget checks | +| `-b`, `--branch` | Use a specific base branch for new feature branches | +| `--timeout` | Set the per-agent execution timeout | +| `--no-color` | Disable colored output | +| `-y`, `--yes` | Skip the confirmation prompt | + +### `nightshift daemon` + +Runs Nightshift on the configured schedule in the background. ```bash -nightshift task list # All tasks -nightshift task list --category pr -nightshift task list --cost low --json -nightshift task show lint-fix +nightshift daemon start +nightshift daemon start --foreground +nightshift daemon status +nightshift daemon stop +``` + +Subcommands: + +| Subcommand | Description | +|------------|-------------| +| `daemon start` | Start the background daemon | +| `daemon status` | Show whether the daemon is running | +| `daemon stop` | Stop the daemon by sending `SIGTERM` | + +`daemon start` flags: + +| Flag | Description | +|------|-------------| +| `-f`, `--foreground` | Run in the foreground instead of daemonizing | +| `--timeout` | Set the per-agent execution timeout used by scheduled runs | + +## Tasks and Budgets + +### `nightshift task` + +Use `task` to inspect the built-in task library or run one task directly. + +```bash +nightshift task list +nightshift task list --category pr --cost low +nightshift task show docs-backfill nightshift task show lint-fix --prompt-only -nightshift task run lint-fix --provider claude -nightshift task run lint-fix --provider codex --dry-run +nightshift task run docs-backfill --provider claude +nightshift task run docs-backfill --provider codex --dry-run --timeout 45m +nightshift task run docs-backfill --provider copilot --branch develop ``` -## Budget Commands +Subcommands: + +| Subcommand | Description | +|------------|-------------| +| `task list` | List available tasks, cost tiers, and categories | +| `task show <task-type>` | Show metadata plus the planning prompt | +| `task run <task-type> --provider PROVIDER` | Execute one task immediately | + +`task list` flags: + +| Flag | Description | +|------|-------------| +| `--category` | Filter by category: `pr`, `analysis`, `options`, `safe`, `map`, `emergency` | +| `--cost` | Filter by cost tier: `low`, `medium`, `high`, `veryhigh` | +| `--json` | Emit JSON output | + +`task show` flags: + +| Flag | Description | +|------|-------------| +| `-p`, `--project` | Use a specific project path when building prompt context | +| `--prompt-only` | Print only the raw prompt text | +| `--json` | Emit JSON output | + +`task run` flags: + +| Flag | Description | +|------|-------------| +| `--provider` | Required. Choose `claude`, `codex`, or `copilot` | +| `-p`, `--project` | Run in a specific project directory | +| `--dry-run` | Print the prompt without executing | +| `--timeout` | Set the execution timeout | +| `-b`, `--branch` | Use a specific base branch for new feature branches | + +### `nightshift budget` + +Shows budget status for all enabled providers or one specific provider. ```bash -nightshift budget # Current status +nightshift budget nightshift budget --provider claude +nightshift budget --provider codex +nightshift budget --provider copilot nightshift budget snapshot --local-only nightshift budget history -n 10 -nightshift budget calibrate +nightshift budget calibrate --provider claude ``` -## Global Flags +Subcommands: + +| Subcommand | Description | +|------------|-------------| +| `budget snapshot` | Capture a calibration snapshot | +| `budget history` | Show recent snapshots | +| `budget calibrate` | Show inferred calibration status | + +Shared budget flags: + +| Flag | Description | +|------|-------------| +| `-p`, `--provider` | Filter to `claude`, `codex`, or `copilot` | + +`budget snapshot` flags: + +| Flag | Description | +|------|-------------| +| `--local-only` | Skip tmux scraping and store a local-only snapshot | + +`budget history` flags: + +| Flag | Description | +|------|-------------| +| `-n` | Number of snapshots to show | + +## Reporting and Observability + +### `nightshift status` + +Shows recent runs or a single-day summary. + +```bash +nightshift status +nightshift status --today +nightshift status -n 10 +``` + +| Flag | Description | +|------|-------------| +| `-n`, `--last` | Show the last `N` runs | +| `--today` | Show today's activity summary | + +### `nightshift logs` + +Tails or filters JSON log files from `~/.local/share/nightshift/logs` by default. + +```bash +nightshift logs +nightshift logs --follow +nightshift logs --level warn --since 2026-04-17 +nightshift logs --component run --match docs-backfill +nightshift logs --summary +nightshift logs --export ./nightshift.log +``` + +| Flag | Description | +|------|-------------| +| `-n`, `--tail` | Number of log lines to show | +| `-f`, `--follow` | Stream new log output | +| `-e`, `--export` | Export matching logs to a file | +| `--since` / `--until` | Filter by time range | +| `--level` | Filter by minimum log level | +| `--component` | Filter by component substring | +| `--match` | Filter by message substring | +| `--summary` | Show only summary stats | +| `--raw` | Show raw log lines | +| `--path` | Override the log directory | +| `--no-color` | Disable colored output | + +### `nightshift report` + +Renders structured reports from previous runs. + +```bash +nightshift report +nightshift report --report tasks +nightshift report --period last-run +nightshift report --since 2026-04-17 --until 2026-04-18 +nightshift report --format markdown +nightshift report --report raw --format plain --paths +``` + +| Flag | Description | +|------|-------------| +| `-r`, `--report` | Choose `overview`, `tasks`, `projects`, `budget`, or `raw` | +| `-p`, `--period` | Choose `last-night`, `last-run`, `last-24h`, `last-7d`, `today`, `yesterday`, or `all` | +| `-n`, `--runs` | Limit how many runs to include | +| `--since` / `--until` | Use an explicit time window instead of a named period | +| `--format` | Choose `fancy`, `plain`, `markdown`, or `json` | +| `--paths` | Include report and log file paths | +| `--max-items` | Limit highlights per run | +| `--no-color` | Disable colored output | + +### `nightshift stats` + +Aggregates results across all recorded runs. + +```bash +nightshift stats +nightshift stats --period last-7d +nightshift stats --json +``` + +| Flag | Description | +|------|-------------| +| `-p`, `--period` | Choose `all`, `last-7d`, `last-30d`, or `last-night` | +| `--json` | Emit JSON output | + +## Analysis, Services, and Utilities + +### `nightshift busfactor` + +Analyzes commit ownership concentration for the current repository or another path. + +```bash +nightshift busfactor +nightshift busfactor ~/code/nightshift +nightshift busfactor --since 2026-01-01 --file cmd/nightshift/commands/run.go +nightshift busfactor --json +nightshift busfactor --save +``` | Flag | Description | |------|-------------| -| `--verbose` | Verbose output | -| `--provider` | Select provider (claude, codex) | -| `--timeout` | Execution timeout (default 30m) | +| `-p`, `--path` | Repository or directory path | +| `-f`, `--file` | Restrict analysis to one file or path pattern | +| `--since` / `--until` | Filter commit history by date | +| `--json` | Emit JSON output | +| `--save` | Store results in the Nightshift database | +| `--db` | Override the database path | + +### `nightshift install` + +Installs a background service. If no service type is provided, Nightshift auto-detects the best option for the current OS. + +```bash +nightshift install +nightshift install launchd +nightshift install systemd +nightshift install cron +``` + +Supported targets: + +| Target | Platform | +|--------|----------| +| `launchd` | macOS | +| `systemd` | Linux user services | +| `cron` | Any Unix-like system | + +### `nightshift uninstall` + +Removes the installed system service. + +```bash +nightshift uninstall +``` + +### `nightshift completion` + +Generates shell completion scripts. + +```bash +nightshift completion bash +nightshift completion zsh +nightshift completion fish +nightshift completion powershell +``` diff --git a/website/docs/configuration.md b/website/docs/configuration.md index 4a7ee3d..9aa7e9f 100644 --- a/website/docs/configuration.md +++ b/website/docs/configuration.md @@ -5,18 +5,52 @@ title: Configuration # Configuration -Nightshift uses YAML config files. Run `nightshift setup` for an interactive setup, or edit directly. +Nightshift loads configuration in this order: -## Config Location +1. Global config: `~/.config/nightshift/config.yaml` +2. Project config: `./nightshift.yaml` +3. Environment overrides -- **Global:** `~/.config/nightshift/config.yaml` -- **Per-project:** `nightshift.yaml` or `.nightshift.yaml` in the repo root +Use `nightshift setup` for the guided global setup, `nightshift init` to create starter files, and `nightshift config` to inspect or update values from the CLI. -## Minimal Config +## Configuration Workflow + +```bash +# Guided setup for the global config +nightshift setup + +# Create starter config files +nightshift init +nightshift init --global + +# Inspect merged config and source paths +nightshift config + +# Read values +nightshift config get budget.max_percent +nightshift config get providers.preference + +# Update values +nightshift config set budget.max_percent 60 +nightshift config set logging.level debug --global + +# Validate both global and project config +nightshift config validate +``` + +Notes: + +- `nightshift setup` writes the global config only. +- `nightshift init` creates `./nightshift.yaml` by default, or `~/.config/nightshift/config.yaml` with `--global`. +- `nightshift config set` writes to `./nightshift.yaml` if it exists in the current directory. Otherwise it writes to the global config. + +## Minimal Global Config ```yaml schedule: cron: "0 2 * * *" + max_projects: 3 + max_tasks: 2 budget: mode: daily @@ -30,45 +64,172 @@ providers: preference: - claude - codex + - copilot claude: enabled: true data_path: "~/.claude" - dangerously_skip_permissions: true codex: enabled: true data_path: "~/.codex" - dangerously_bypass_approvals_and_sandbox: true + copilot: + enabled: false + data_path: "~/.copilot" projects: - - path: ~/code/sidecar + - path: ~/code/nightshift + priority: 3 - path: ~/code/td + priority: 2 +``` + +## Project Config + +Put `nightshift.yaml` in a repo root to override settings for that repo. + +```yaml +tasks: + enabled: + - lint-fix + - docs-backfill + - bug-finder + priorities: + lint-fix: 1 + docs-backfill: 2 + intervals: + lint-fix: "24h" + docs-backfill: "168h" + +budget: + max_percent: 50 +``` + +Nightshift also supports project discovery from the global config: + +```yaml +projects: + - path: ~/code/nightshift + priority: 3 + - pattern: ~/code/oss/* + exclude: + - ~/code/oss/archived ``` ## Schedule -Use cron syntax or interval-based scheduling: +Use either `schedule.cron` or `schedule.interval`, not both. + +| Key | Description | +|-----|-------------| +| `schedule.cron` | Cron expression for scheduled runs | +| `schedule.interval` | Duration-based schedule such as `8h` | +| `schedule.window.start` | Optional start time such as `22:00` | +| `schedule.window.end` | Optional end time such as `06:00` | +| `schedule.window.timezone` | IANA timezone such as `America/Los_Angeles` | +| `schedule.max_projects` | Default project cap for `nightshift run` when `--max-projects` is not set | +| `schedule.max_tasks` | Default per-project task cap when `--max-tasks` is not set | + +Examples: ```yaml schedule: - cron: "0 2 * * *" # Every night at 2am - # interval: "8h" # Or run every 8 hours + cron: "0 2 * * *" + window: + start: "22:00" + end: "06:00" + timezone: "America/Los_Angeles" +``` + +```yaml +schedule: + interval: "8h" ``` ## Budget -Control how much of your token budget Nightshift uses: +| Key | Default | Description | +|-----|---------|-------------| +| `budget.mode` | `daily` | `daily` or `weekly` | +| `budget.max_percent` | `75` | Max percentage a single Nightshift run can use | +| `budget.reserve_percent` | `5` | Budget kept in reserve for daytime work | +| `budget.aggressive_end_of_week` | `false` | Spend more aggressively near the end of a weekly cycle | +| `budget.weekly_tokens` | `700000` | Fallback weekly budget estimate | +| `budget.per_provider` | unset | Per-provider token overrides | +| `budget.billing_mode` | `subscription` | `subscription` or `api` | +| `budget.calibrate_enabled` | `true` | Enable calibration snapshots | +| `budget.snapshot_interval` | `30m` | Snapshot cadence | +| `budget.snapshot_retention_days` | `90` | Snapshot retention window | +| `budget.week_start_day` | `monday` | Weekly reset boundary for calibration | +| `budget.db_path` | `~/.local/share/nightshift/nightshift.db` | Override the SQLite database path | + +Subscription example: + +```yaml +budget: + mode: daily + max_percent: 75 + reserve_percent: 5 + billing_mode: subscription + calibrate_enabled: true + snapshot_interval: 30m +``` + +API billing example: + +```yaml +budget: + billing_mode: api + weekly_tokens: 1000000 + per_provider: + claude: 1000000 + codex: 500000 +``` + +Useful commands: + +```bash +nightshift budget +nightshift budget snapshot --local-only +nightshift budget history -n 10 +nightshift budget calibrate +``` + +## Providers -| Field | Default | Description | -|-------|---------|-------------| -| `mode` | `daily` | `daily` or `weekly` | -| `max_percent` | `75` | Max budget % to use per run | -| `reserve_percent` | `5` | Always keep this % available | -| `billing_mode` | `subscription` | `subscription` or `api` | -| `calibrate_enabled` | `true` | Auto-calibrate from local CLI data | +Nightshift supports `claude`, `codex`, and `copilot`. Provider selection follows `providers.preference` and skips disabled providers. -## Task Selection +| Key | Description | +|-----|-------------| +| `providers.preference` | Ordered provider preference list | +| `providers..enabled` | Enable or disable a provider | +| `providers..data_path` | Provider data directory used for usage tracking | +| `providers.claude.dangerously_skip_permissions` | Claude-specific unattended execution override | +| `providers.codex.dangerously_bypass_approvals_and_sandbox` | Codex-specific unattended execution override | +| `providers.copilot.dangerously_skip_permissions` | Copilot-specific unattended execution override | -Enable/disable tasks and set priorities: +Example: + +```yaml +providers: + preference: + - claude + - codex + - copilot + claude: + enabled: true + data_path: "~/.claude" + codex: + enabled: true + data_path: "~/.codex" + copilot: + enabled: true + data_path: "~/.copilot" +``` + +> There is no `--enable-writes` CLI flag in the current release. Nightshift always works through branches and PRs. Headless approval behavior is provider-specific, and the available config hooks live under `providers.*.dangerously_*`. + +## Tasks + +Use the `tasks` section to choose what Nightshift is allowed to run and how often. ```yaml tasks: @@ -76,55 +237,66 @@ tasks: - lint-fix - docs-backfill - bug-finder + disabled: + - td-review priorities: lint-fix: 1 - bug-finder: 2 + docs-backfill: 2 intervals: lint-fix: "24h" docs-backfill: "168h" + custom: + - type: release-readiness + name: "Release Readiness Review" + description: | + Review the repo for release blockers and summarize follow-up work. + category: analysis + cost_tier: medium + risk_level: low + interval: "72h" ``` -Each task has a default cooldown interval to prevent the same task from running too frequently on a project. +Useful commands: -## Multi-Project Setup +```bash +nightshift task list +nightshift task show docs-backfill +nightshift task run docs-backfill --provider claude --dry-run +``` -```yaml -projects: - - path: ~/code/project1 - priority: 1 # Higher priority = processed first - tasks: - - lint - - docs - - path: ~/code/project2 - priority: 2 +## Integrations, Logging, and Reporting - # Or use glob patterns - - pattern: ~/code/oss/* - exclude: - - ~/code/oss/archived -``` +| Key | Description | +|-----|-------------| +| `integrations.claude_md` | Read project-level `CLAUDE.md` instructions | +| `integrations.agents_md` | Read project-level `AGENTS.md` instructions | +| `integrations.task_sources` | External task sources such as `td` | +| `logging.level` | `debug`, `info`, `warn`, or `error` | +| `logging.path` | Directory for JSON or text logs | +| `logging.format` | `json` or `text` | +| `reporting.morning_summary` | Enable morning summary generation | +| `reporting.email` | Optional email destination | +| `reporting.slack_webhook` | Optional Slack webhook | -## Safe Defaults +## Environment Overrides -| Feature | Default | Override | -|---------|---------|----------| -| Read-only first run | Yes | `--enable-writes` | -| Max budget per run | 75% | `budget.max_percent` | -| Auto-push to remote | No | Manual only | -| Reserve budget | 5% | `budget.reserve_percent` | +Nightshift currently binds a small set of config keys directly from environment variables: + +| Environment Variable | Config Key | +|----------------------|------------| +| `NIGHTSHIFT_BUDGET_MAX_PERCENT` | `budget.max_percent` | +| `NIGHTSHIFT_BUDGET_MODE` | `budget.mode` | +| `NIGHTSHIFT_LOG_LEVEL` | `logging.level` | +| `NIGHTSHIFT_LOG_PATH` | `logging.path` | ## File Locations | Type | Location | |------|----------| -| Run logs | `~/.local/share/nightshift/logs/nightshift-YYYY-MM-DD.log` | -| Audit logs | `~/.local/share/nightshift/audit/audit-YYYY-MM-DD.jsonl` | -| Summaries | `~/.local/share/nightshift/summaries/` | +| Global config | `~/.config/nightshift/config.yaml` | +| Project config | `./nightshift.yaml` | +| Logs | `~/.local/share/nightshift/logs/` | +| Run reports | `~/.local/share/nightshift/reports/` | +| Morning summaries | `~/.local/share/nightshift/summaries/` | | Database | `~/.local/share/nightshift/nightshift.db` | | PID file | `~/.local/share/nightshift/nightshift.pid` | - -If `state/state.json` exists from older versions, Nightshift migrates it to the SQLite database and renames the file to `state.json.migrated`. - -## Providers - -Nightshift supports Claude Code and Codex as execution providers. It will use whichever has budget remaining, in the order specified by `preference`. diff --git a/website/docs/integrations.md b/website/docs/integrations.md index 96d5e3f..768e9f0 100644 --- a/website/docs/integrations.md +++ b/website/docs/integrations.md @@ -5,52 +5,155 @@ title: Integrations # Integrations -Nightshift integrates with your existing development workflow. +Nightshift works best when the provider CLIs, your Git workflow, and your task sources are already part of your normal setup. + +## Provider Prerequisites + +Before Nightshift can run work, the provider must be: + +- Installed and available in `PATH` +- Enabled in config under `providers..enabled` +- Authenticated in the provider's own CLI + +`nightshift doctor` is the fastest way to confirm whether Nightshift can see the provider CLI, its data path, and its budget status. ## Claude Code -Nightshift uses the Claude Code CLI to execute tasks. Authenticate via subscription or API key: +Nightshift can use the local Claude Code CLI as an execution provider. ```bash claude /login ``` +Claude Code can be authenticated through a subscription login or API-backed credentials, depending on your local Claude setup. + +Config example: + +```yaml +providers: + preference: + - claude + - codex + claude: + enabled: true + data_path: "~/.claude" +``` + ## Codex -Nightshift supports OpenAI's Codex CLI as an alternative provider: +Nightshift also supports the OpenAI Codex CLI. ```bash codex --login ``` -## GitHub +Codex can run with either a ChatGPT login or API-backed credentials, depending on your local Codex setup. + +Config example: + +```yaml +providers: + preference: + - codex + - claude + codex: + enabled: true + data_path: "~/.codex" +``` + +## GitHub Copilot + +Nightshift supports GitHub Copilot as a provider through either: + +- `gh copilot` via the GitHub CLI extension +- The standalone `copilot` binary + +GitHub CLI path: + +```bash +gh auth login +gh extension install github/gh-copilot +gh extension list +``` + +Standalone path: + +```bash +npm install -g @github/copilot +copilot --version +``` + +Nightshift prefers a standalone `copilot` binary when it is present in `PATH`; otherwise it falls back to `gh copilot`. + +Config example: + +```yaml +providers: + preference: + - claude + - codex + - copilot + copilot: + enabled: true + data_path: "~/.copilot" +``` + +Budget note: -All output is PR-based. Nightshift creates branches and pull requests for its findings. +- GitHub Copilot does not expose authoritative token usage the way Claude Code and Codex do. +- Nightshift tracks Copilot usage locally in `~/.copilot/nightshift-usage.json`. +- Budget output for Copilot is therefore an approximation based on request counting, not a server-reported quota. + +## GitHub and Pull Requests + +Nightshift is designed around Git workflows. It works in your local checkout, creates branches, and reports results as branches or PR-ready changes. + +GitHub-specific features such as issue sourcing require the `gh` CLI to be installed and authenticated: + +```bash +gh auth login +``` -## td (Task Management) +## td Task Management -Nightshift can source tasks from [td](https://td.haplab.com) — task management for AI-assisted development. Tasks tagged with `nightshift` in td will be picked up automatically. +Nightshift can source work from [`td`](https://td.haplab.com). ```yaml integrations: task_sources: - td: enabled: true - teach_agent: true # Include td usage + core workflow in prompts + teach_agent: true ``` -## CLAUDE.md / AGENTS.md - -Nightshift reads project-level instruction files to understand context when executing tasks. Place a `CLAUDE.md` or `AGENTS.md` in your repo root to give Nightshift project-specific guidance. Tasks mentioned in these files get a priority bonus (+2). +When `teach_agent: true` is enabled, Nightshift includes the local td workflow in the agent prompt context. ## GitHub Issues -Source tasks from GitHub issues labeled with `nightshift`: +Nightshift can source tasks from open GitHub issues labeled `nightshift`. ```yaml integrations: - github_issues: - enabled: true - label: "nightshift" + task_sources: + - github_issues: true ``` + +This integration uses the local `gh issue list` command in repositories whose `origin` remote points at GitHub. + +## Project Instruction Files + +Nightshift reads repo-local instruction files for extra project context: + +- `CLAUDE.md` +- `AGENTS.md` + +Enable or disable them in config: + +```yaml +integrations: + claude_md: true + agents_md: true +``` + +These files are read from the project root and included as execution context when available.