Getting Started
Install NightShift, run your first problem, and understand how to describe tasks in YAML. Up and running in under 5 minutes.
Requirements
- Python 3.11+ — NightShift uses modern type hints and async features
- Anthropic API key — the system uses Claude (Haiku for cheap agents, Sonnet for planning)
- Git — the Evaluator uses git diff as the source of truth
- ~500MB disk for LanceDB + ModernBERT model (downloaded on first run)
Installation
Add export ANTHROPIC_API_KEY=... to your ~/.zshrc or ~/.bashrc so you don't have to set it every session.
Your First Run
The quickest way to try NightShift is with a natural language description:
On the second run with a similar problem, the Coordinator reads what it learned from this run and improves its approach.
Problem YAML Format
For complex tasks, use a problem.yaml file. This gives the system more context and lets you specify acceptance criteria and budget.
YAML Fields
| Field | Type | Required | Description |
|---|---|---|---|
title |
string | required | Short name for the problem. Used in KB entries and logs. |
description |
string | required | Full problem description. Be specific — vague descriptions produce vague results. |
acceptance |
list | optional | Criteria the output must meet. Passed to the Evaluator — each criterion is checked individually. |
optimize_for |
enum | optional | quality (default), speed, or cost. Influences Coordinator's planning choices. |
max_budget_usd |
float | optional | Hard budget cap in USD (LLM API cost). Run stops if exceeded. Default: 5.0. |
max_attempts |
int | optional | Maximum improvement iterations. Default: 3. Set to 1 to disable retries. |
context |
string | optional | Additional context the Coordinator gets before planning (e.g., "target audience: CTOs"). |
Acceptance criteria are your contract with the Evaluator. The more specific you are, the more reliably the system meets them. "At least 3 named competitors" is better than "competitor analysis."
Running in Background
For longer runs, use --bg to detach and monitor separately:
Understanding the Output
When a run completes, NightShift creates files in the current directory:
output/— the actual deliverable (code files, reports, analysis).nightshift/status.json— full run state (nodes, costs, quality).nightshift/events.jsonl— event stream (every action logged).nightshift/kb/— the Knowledge Base (grows with every run)
The KB is in .nightshift/ in your project directory. Add .nightshift/ to your .gitignore if you don't want to commit it. The global KB at ~/.nightshift/ is never committed.
What Next
- CLI Reference — all commands and flags
- Configuration — full YAML reference and global config
- Learning System — how the KB and AR patterns improve over runs
- Architecture — deep-dive into the 9 pillars