Skip to content

docs: backfill user documentation #199

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
gregggreg wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

docs: backfill user documentation #199

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0fd7ade
docs: backfill user documentation
gregggreg Jul 26, 2026
3a68bc7
docs: correct backfilled CLI behavior
gregggreg Jul 26, 2026
4d3d2c8
docs: reconcile CLI behavior
gregggreg Jul 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 80 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,8 @@ After installing, run the guided setup:
nightshift setup
```

This walks you through provider configuration, project selection, budget calibration, and daemon setup. Once complete you can preview what nightshift will do:
This walks you through provider configuration, project selection, budget calibration, and
scheduled-service setup. Once complete you can preview what nightshift will do:

```bash
nightshift preview
Expand All @@ -56,6 +57,21 @@ Or kick off a run immediately:
nightshift run
```

For a non-interactive configuration bootstrap:

```bash
nightshift init --global # ~/.config/nightshift/config.yaml
nightshift init # ./nightshift.yaml
nightshift config validate
nightshift config get budget.max_percent
nightshift config set budget.max_percent 60 --global
```

Configuration precedence is built-in defaults, global config, one project `nightshift.yaml`,
then supported environment overrides. `run --project`, `preview --project`, and
`task run --project` load the project file from the selected directory; otherwise Nightshift uses the
current directory. Command flags then override the behavior of that invocation.

## Common CLI Usage

Full reference: [CLI Reference docs](https://nightshift.haplab.com/docs/cli-reference)
Expand All @@ -72,6 +88,12 @@ nightshift preview --write ./nightshift-prompts
# Guided global setup
nightshift setup

# Create and validate config
nightshift init --global
nightshift init
nightshift config
nightshift config validate

# Check environment and config health
nightshift doctor

Expand All @@ -93,8 +115,17 @@ 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 skill-groom --provider codex --dry-run --branch main
nightshift task run docs-backfill --provider copilot --timeout 45m

# Persistent scheduler lifecycle
nightshift daemon start
nightshift daemon status
nightshift daemon stop

# Or install an OS-managed scheduled run
nightshift install
nightshift uninstall
```

If `gum` is available, preview output is shown through the gum pager. Use `--plain` to disable.
Expand All @@ -109,13 +140,16 @@ daemon, CI) confirmation is auto-skipped.
| Flag | Default | Description |
|------|---------|-------------|
| `--dry-run` | `false` | Show preflight summary and exit without executing |
| `--project`, `-p` | _(all configured)_ | Target a single project directory |
| `--project`, `-p` | configured paths, or current directory | Target one project and load its `nightshift.yaml` |
| `--task`, `-t` | _(auto-select)_ | Run a specific task by name |
| `--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 (use with caution) |
| `--yes`, `-y` | `false` | Skip the confirmation prompt |
| `--branch`, `-b` | _(current branch)_ | Base branch for new task branches |
| `--timeout` | `30m` | Per-agent execution timeout |
| `--no-color` | `false` | Disable colored output (`NO_COLOR` also works) |

```bash
# Interactive run with preflight summary + confirmation prompt
Expand All @@ -138,15 +172,19 @@ nightshift run --ignore-budget

# Target a specific project and task directly
nightshift run -p ./my-project -t lint-fix

# Select a base branch and timeout
nightshift run --branch develop --timeout 45m
```

Other useful flags:

- `nightshift status --today` to see today's activity summary
- `nightshift daemon start --foreground` for debug
- `--category` — filter tasks by category (pr, analysis, options, safe, map, emergency)
- `--cost` — filter by cost tier (low, medium, high, veryhigh)
- `--prompt-only` — output just the raw prompt text for piping
- `--provider` — required for `task run`, choose claude or codex
- `--provider` — required for `task run`, choose claude, codex, or copilot
- `--dry-run` — preview the prompt without executing
- `--timeout` — execution timeout (default 30m)

Expand All @@ -155,7 +193,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 standalone Copilot CLI, directly or through current `gh copilot`

### Claude Code

Expand All @@ -169,21 +207,30 @@ Supports Claude.ai subscriptions or Anthropic Console credentials.
### Codex

```bash
codex --login
codex
```

Supports signing in with ChatGPT or an API key.
Choose ChatGPT sign-in, or configure API-key authentication.

### GitHub Copilot

```bash
# Install Copilot CLI
# Preferred: standalone Copilot CLI
npm install -g @github/copilot
# or
curl -fsSL https://gh.io/copilot-install | bash
copilot login

# Alternative: current GitHub CLI downloads/runs Copilot CLI
gh auth login --web
gh copilot
```

Requires GitHub Copilot subscription. See [docs/COPILOT_INTEGRATION.md](docs/COPILOT_INTEGRATION.md) for details.
Nightshift prefers the standalone `copilot` executable. Recent GitHub CLI releases also expose a
built-in `gh copilot` command; the older `github/gh-copilot` extension is retired and should not
be installed. Automatic `nightshift run` can use the built-in command, but
`nightshift task run --provider copilot` still applies a stale extension-list check when
standalone Copilot is absent. Install standalone Copilot for direct task execution. The npm
package requires Node.js 22 or later, and a Copilot plan plus any required organization policy
are prerequisites.

If you prefer API-based usage, you can authenticate Claude and Codex CLIs with API keys instead.

Expand All @@ -198,9 +245,15 @@ 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`.
Run `nightshift setup` or `nightshift init --global` to create the global config at
`~/.config/nightshift/config.yaml`. A project config is named exactly `nightshift.yaml`.
`init` writes opinionated starters rather than the built-in defaults: both templates contain
legacy task aliases, and the current global template prefers Claude and Codex and explicitly
enables their unattended permission-bypass flags. Review those values and replace the template's
task names with slugs reported by `nightshift task list`.

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:

Expand All @@ -220,14 +273,19 @@ providers:
preference:
- claude
- codex
- copilot
claude:
enabled: true
data_path: "~/.claude"
dangerously_skip_permissions: true
dangerously_skip_permissions: false
codex:
enabled: true
data_path: "~/.codex"
dangerously_bypass_approvals_and_sandbox: true
dangerously_bypass_approvals_and_sandbox: false
copilot:
enabled: true
data_path: "~/.copilot"
dangerously_skip_permissions: false

projects:
- path: ~/code/sidecar
Expand Down Expand Up @@ -256,6 +314,12 @@ Each task has a default cooldown interval to prevent the same task from running

`skill-groom` is enabled by default. Add it to `tasks.disabled` if you want to opt out. It updates project-local skills under `.claude/skills` and `.codex/skills` using `README.md` as project context and starts Agent Skills docs lookup from `https://agentskills.io/llms.txt`.

Provider executables are discovered through `PATH`; `providers.*.data_path` points to usage and
session data, not to the executable. Automatic `run` selection uses `providers.preference` and
skips disabled, missing, or budget-exhausted providers. It does not verify authentication before
execution. `preview` uses the first enabled provider in the fixed Claude, Codex, Copilot order
and does not check executable availability.

## Development

### Pre-commit hooks
Expand Down
Loading