This started out as a small project I had Claude Code create for my internal development with my gaming and modding project, Gamespice.

Initially, one simple cron job ran every night to manage tasks and track the progress of Claude Code agents and workers. Over time, I've been adding more and more features to the project. Given these additions, I've been impressed with how much functionality has been getting integrated into the project and I decided I'd make it open source so that others can benefit from it if they want to use it for their development.

Companion repo: the scripts, systemd units, offload helpers and agent instruction files that run my own fleet on top of nightly are public in nightly-env.

Queue: prioritised to-dos with status lists and per-game sections.

Reviews, the standout: a before/after animation clip with a slider, frame stepping, timing strip, metrics and Good / Still wrong controls.

The screenshots use demo data generated by scripts/seed-demo.mjs (run it against an empty throwaway database; see the header of the script).

Stack: Next.js 16 (App Router) · tRPC v11 · Prisma 7 (SQLite via @prisma/adapter-better-sqlite3) · Tailwind v4 · React 19. The CLI is plain Node ESM on node:sqlite.

Everything below is in the web panel and in the CLI (bin/nightly); the panel talks to the same database.

• Queue and items. An item is a task, issue, check, study or review with a body written as Markdown, repos, a checkable "done when", priority and a notes thread. Lists are ordered; priority is per list, lower first, and quick-add takes a title and Enter. Items are never deleted, they are closed as done or won't fix.
• In progress. What an agent has started. An item that cannot be finished in one go sits here with a note saying exactly where it stopped, so the next agent can pick it up cold.
• Review. Work waiting for a human verdict. Agents move finished items here, you read the notes and either close them or send them back to the queue.
• Checks. Standing checks with a cadence (nightly, every 2 days, weekly, monthly). A check is due when it has not been run for its cadence, and a run goes through the due ones and records each with nightly checked.
• Blocked. Items waiting on something outside the run, with the reason in the notes, so they stop being picked up.
• Issues. Problems found by agents or schedules, filed as items of kind issue and worked like any other.
• Done. Finished and won't-fix items with their completion time and full note history.
• Agents and the live board. Every concurrent agent joins the board with its task, claims the paths it is changing, and talks to the others through messages. A claim that overlaps a live agent's is refused, which stops two agents editing the same files. Stale agents stop blocking after a while and stale claims can be released from the panel.
• Runs and reports. Each run records its status, summary, turns, duration, cost, runner log (live while it runs, with Stop) and the full report the agent writes, searchable across all runs.
• Schedules and the scheduler. Cron schedules with a prompt, extra instructions for just that schedule, max turns and an overlap switch, plus a master switch and Run now. The panel's scheduler checks every minute; a crontab line works too, and two schedulers never fire the same schedule twice.
• Prompts. The instructions every agent reads and the runner script itself live in the database, edited in the panel with every version kept and restorable.
• QA runs. Game machines push fuzz, visual, suite and performance results; the QA page shows the newest run per game and kind with a pass/fail trend and the frame-time budget charts.
• Reviews. See below.
• Screenshots. Pictures agents attach to items or file under a day appear in a gallery, open in a zoomable viewer, and a .glb next to a picture opens an orbit 3D viewer where you can pin notes.
• Games. Items, runs, pictures, reviews and QA are grouped per game, taken from the repos an item names.
• Usage limits and multiple accounts. A script reads your Claude plan's 5-hour and weekly usage. Set thresholds in Settings and the runner will not start while usage is over them. With several Claude accounts configured, each run picks the one with the most headroom.
• Login. Optional password (and username) protection for every page, the API and media, off by default.
• CLI. All of the above from a shell, without the panel or a server running: see CLI.

Reviews are for judging animation, model and sound work, where a green test says nothing about whether it looks or sounds right. A builder files a review item and posts media under one entry per weapon, character or sound:

Each entry carries what to look for, a verdict (Good or Still wrong) with a note, and the verdict history. Builders read the notes back with scripts/review-post.sh open KEY (or nightly review open KEY on the panel's machine), fix what is marked wrong and re-post the media as after. Files are stored under NIGHTLY_REVIEWS with a review.json; there is no database table. Filing and reading are described under Panel.

nightly-env holds the pieces that run my fleet on top of nightly: the scripts, systemd units, offload helpers and agent instruction files. nightly stays generic; nightly-env is one concrete setup.

Please refer to the following commands for initially setting up the project. You can use git to clone this repository.

# Clone repository and change to its directory.
git clone https://github.com/gamemann/nightly

cd nightly

# Installs the main application and generates the Prisma client.
# Sets up the database and imports initial data.
npm install

# Run database setup and import initial data.
# Creates data/nightly.db from prisma/schema.prisma
npm run db:push

A new database is blank and paused. In the panel: add a runner script named run.sh and a prompt (Prompts), a schedule (Schedules), then switch Nightly run on (Settings). The repository includes a runner you can start from; see Runner Script below.

There is no cron job to set up. While the web panel is running, it checks every minute whether one of your schedules is due and starts it. The schedules themselves (when, which prompt, any extra instructions) are managed in the panel, and the Schedules page shows when the scheduler last checked in, with a warning if it has stopped.

Runs only start while the panel is up, so keep it running: the included systemd unit does that and starts it again after a reboot (see Panel). A run that has started keeps going if the panel is restarted.

If you would rather not depend on the panel being up, a crontab line does the same job, alongside the panel or instead of it. Two schedulers never start the same schedule twice.

# Optional: open your user's crontab.
crontab -e

# Add this line, using the path you cloned the repository to.
# tick.log only gets a line when a schedule fires or something breaks.
* * * * * /path/to/nightly/bin/nightly tick >> /path/to/nightly/data/tick.log 2>&1

# To use only the crontab, turn the panel's scheduler off in .env:
# NIGHTLY_SCHEDULER=off

The runner is the shell script each run executes. It decides whether it is safe to run and which repositories to leave alone, then starts Claude Code with your prompt. scripts/run.sh is a complete one:

• Skips the run when your Claude plan usage is past the limits set in Settings → Usage limits (using the usage check below).
• Finds every Git repository in your workspace. A repository with uncommitted changes is handed to the agent to commit first, unless one of those files changed in the last 90 minutes; then somebody is mid-edit, and the agent is told to stay out of it.
• Adds the run's id, the agent board instructions and the schedule's own instructions to the prompt, then runs claude -p unattended.
• Sends Claude's final message, turn count, duration and cost back to the run in the web panel.

You can either store it in the database, which lets you edit it from the web panel (with history), or run the file in place.

# Store the included runner in the database (Prompts -> run.sh in the web panel).
bin/nightly prompt set run.sh --file scripts/run.sh

# Or run scripts/run.sh in place instead; edits then happen in the file.
bin/nightly set-setting runner scripts/run.sh

Nothing in the runner is specific to one machine. It is configured with environment variables, which you can put in .env (copy .env.example); the CLI loads that file, so they also apply under cron.

scripts/claude-usage.sh reads your Claude plan's current 5-hour and weekly usage. The runner calls it before each run (and the agent between items), and it can be used on its own. Each call costs one tiny request against the 5-hour window.

# Show both windows with their reset times.
scripts/claude-usage.sh

# The same as JSON.
scripts/claude-usage.sh --json

# Exit 1 if the 5-hour window is at or over 80% or the weekly window at or over 90%.
# Exit 2 means the check itself could not read the usage; treat that as unknown, not as fine.
scripts/claude-usage.sh --check 80 90

Claude Code has no documented way to read plan usage outside its interactive /usage screen, so the script reads the rate-limit event claude -p reports before its answer, and falls back to looser parses if that format changes. When nothing usable comes back, it saves the raw output to data/usage-probe-last.jsonl (or CLAUDE_USAGE_DEBUG_FILE) for fixing the parse.

npm run dev            # http://0.0.0.0:3010, hot reload  (or: ~/stack/dev.sh nightly)
npm run build && npm run start   # production on :3010

Sidebar: Queue · In progress · Review · Blocked · Issues · Checks · Done · Games · Agents · Runs & reports · Screenshots · QA · Reviews · Schedules · Prompts · Settings. Quick-add bar on every list (type a title, Enter; Ctrl+Enter adds and opens it; c focuses it, / focuses search). Hover a row to move it up/down/to the top. Item pages render the body as Markdown, edit every field in place, and hold a notes thread. Settings has the doRun switch (pauses every schedule), the usage limits and an optional runner path.

• Prompts: every prompt and script, edited in place (Ctrl+S; unsaved text survives a reload; a save refuses to overwrite a newer one written by a run), with each version kept and restorable. A schedule names the prompt it starts with; the runner script is the one named run.sh.

• Schedules: each has a cron expression (local time; the next three fire times are shown as you type), a prompt (from Prompts), instructions appended for that schedule only (that is how a schedule gets a task of its own: "only the due checks", "only game-dev"), max turns, and whether it may overlap another run. Run now starts one immediately and ignores the pause switch.

• Runs & reports: every run, searchable across reports and logs; a run page shows its summary, the items it noted, the report, the runner's log (live while running, with Stop), and the screenshots filed under that day.

• Agents: live sessions with their task and claimed paths, a message feed (send to everyone or one agent), and controls to release a stale claim or end a session that vanished.

Login: off by default. Settings → Login turns it on: a password (stored as a scrypt hash), optionally a username. Every page, the API and /media then need a sign-in (an HMAC-signed cookie, 90 days; changing the username or password signs every browser out; Sign out in Settings). Locked out: bin/nightly set-setting authEnabled false on the machine. Behind anything but your own network, put the panel behind HTTPS too.

Item attachments. nightly attach <item> <file.png|jpg> [--note ..] downscales to 1280 px wide, keeps it under 2 MB (JPEG fallback), stores it in NIGHTLY_ATTACH (default data/attachments/<item>/, with an index.json) and keeps the last 20 per item. The item page shows thumbnails (click to enlarge) with notes, nightly show lists the URLs (NIGHTLY_PUBLIC_URL, default http://<hostname>:3010), served at /attachments/<item>/<file>. From another machine: copy the image to a temp path and run ssh <host> nightly attach ..., which is what a wrapper script does.

3D models and pinned notes. A .glb/.gltf stored next to a picture with the same base name (shot.png and shot.glb) is that picture's model; nightly attach shot.png copies a sibling model beside it, and it is pruned with the picture. Clicking such a picture (Screenshots, an item page, a game page) opens an orbit viewer (three.js, bundled, exact-pinned) with a 3D / Picture switch. Clicking the surface asks for a note and stores a pin (point, normal) in the Annotation table; clicking a flat picture stores x, y as fractions of its size. Routes: GET /api/annotations?item=&target=, POST (item, target, kind: model|image, x, y, z, nx, ny, nz, text, author), DELETE ?id=. Review media does not carry models.

Games (/game, /game/<slug>): items, runs, pictures, reviews and QA per game. The game is taken from an item's repos: the first game-*/mg-* repo, else a <x>-maps repo of that game, else the aliases in src/lib/games.ts; everything else is under other.

QA (/qa): game machines push fuzz / visual / suite results with scripts/qa-post.sh <kind> <game> <file> (POST /api/qa, schema on the page; table QaRun, images under NIGHTLY_ATTACH/qa-<id>/). Same optional password as the panel; the poster logs in with QA_USER/QA_PASSWORD. Panel-only table, the CLI does not read it.

Reviews (/reviews, kind review): per-weapon animation filmstrips and looping clips (before/after) and audio with waveform and licence line, each weapon with a verdict (good / still wrong) and a note. Files live under data/reviews/<key>/<weapon>/ (NIGHTLY_REVIEWS) with a review.json; no database table. Builders file with scripts/review-post.sh new KEY "Title", then media KEY WEAPON FILE --slot filmstrip|clip|audio|image [--variant before|after] [--label L] [--title T] [--licence L] [--source URL] [--waveform W.png] (same QA_URL/QA_USER/QA_PASSWORD as qa-post.sh; audio gets a waveform drawn for it if none is given; the same slot, variant and label replaces). You set the verdicts on the page. Builders read them back with scripts/review-post.sh open KEY (weapons not yet good, with notes) or, on the machine that runs the panel, nightly review open|show|list KEY; fix the weapons marked wrong, re-post the media as after, and the verdict history is kept.

Perf budget (/qa, kind perf): the Perf budget schedule (03:30) has the prompt perf-budget.md, whose first line is a shebang. run.sh runs a prompt like that as a job, not a Claude run (no plan-usage gate, no agent): it ssh-es to the game machine, runs the game repository's tools/perf_budget.sh --post (frame-time percentiles, worst stall, load time, peak RSS and pack size per map on the GPU box, against a committed baseline) and the run is ok or failed by the exit code. The script posts through scripts/qa-post.sh perf; the page draws a trend chart per metric and map (last 30 runs, baseline and budget dashed, over-budget runs red). Any other job is a new prompt with a shebang plus a schedule.

Screenshots are read from NIGHTLY_MEDIA (default archive/screenshots, laid out <YYYY-MM-DD>/…) and served at /media/…; a report's ![](screenshots/<date>/x.png) renders inline.

Opening the dev panel from another machine: set NIGHTLY_DEV_ORIGINS to the hostname(s) you use (see .env.example), or npm run dev serves the page and never hydrates.

Service: the panel is also the scheduler, so it should keep running. deploy/nightly-panel.service is a systemd user unit that runs the production build, restarts it if it stops, and starts it at boot.

# Set WorkingDirectory (your clone) and the npm path in the unit first.
# Build the panel, then install and start the unit.
npm run build
cp deploy/nightly-panel.service ~/.config/systemd/user/
systemctl --user daemon-reload && systemctl --user enable --now nightly-panel

# Keep it running when you are not logged in.
loginctl enable-linger $USER

~/stack/nightly/bin/nightly — works from any directory and under cron's bare PATH (it finds /usr/local/bin/node itself). Every command takes --json. NIGHTLY_DB=/path/to.db points it at another file (tests, scratch copies).

nightly list [--status queue,in_progress,review] [--kind task,issue] [--all]
nightly show <key>
nightly add --title T [--key K] [--kind task|issue|check|study] [--body B | --body-file F | <stdin]
            [--repos a,b] [--done-when ..] [--status S] [--cadence nightly|every-2-days|weekly|monthly]
            [--priority N | --top | --after KEY] [--by <owner>|nightly|session]
nightly set <key> [--status S] [--priority N | --top | --after KEY] [--title ..] [--body B | --body-file F]
            [--repos ..] [--done-when ..] [--kind ..] [--cadence ..]
nightly note <key> [--run ID] [--by nightly] <text | --file F | <stdin>
nightly checks [--due]
nightly checked <key> [--note ..] [--run ID]
nightly run start                                   # prints the new run id
nightly run finish <id> --status ok|failed|skipped --summary S [--report-file F] [--turns N] [--minutes N]
nightly run close-stale --status ok|failed [--report-file F]   # closes runs still 'running'; prints "closed N"
nightly run list [--all] | nightly run show <id>
nightly run stop <id>                               # SIGTERM to the runner's process group
nightly schedule list                               # schedules are edited in the panel
nightly tick [--dry-run]                            # start what is due this minute (the panel runs it; or a crontab)
nightly start <schedule-id|name>                    # fire one now; prints the run id
nightly agent join <name> [--task T] [--repos a,b] [--kind session|nightly] [--run ID]
nightly agent claim <name> <path...> [--note N] [--force]   # exit 3: a live agent holds an overlapping path
nightly agent release <name> [<path...>]
nightly agent say <name> [--to AGENT] <text>
nightly agent inbox <name> [--peek]
nightly agent board
nightly agent leave <name>
nightly get doRun                                   # prints exactly true or false
nightly set-setting doRun false
nightly brief                                       # compact digest for the run's prompt
nightly prompt list | show <name> | history <name>  # prompts and the runner script, from the DB
nightly prompt set <name> [--file F | stdin] [--note N] [--by nightly]

Notes:

• list shows open items (in progress, review, queue, blocked) ordered by status then priority; standing checks only appear with --kind check or --all (use nightly checks).
• add without --key makes a slug from the title (spy-go-1 style). Default position is the bottom of its list; add defaults --by nightly.
• set --status done|wontfix fills completedAt; moving back clears it.
• A check is due when lastRunAt is older than 20 h (nightly), 6.5 days (weekly) or 28 days (monthly).
• run finish/close-stale store the report file truncated to ~200 KB. close-stale leaves runs whose process is still alive.
• run start under nightly exec prints the run exec created (NIGHTLY_RUN_ID) instead of making a new one.
• Agent paths are relative to the workspace (the directory holding this repo); ~/stack/x/ and x are the same claim. Two claims overlap when one path contains the other; * is everything. An agent silent for 60 min no longer blocks anyone; after 6 h tick ends it and releases its claims.

panel (every minute, src/server/scheduler.ts) and/or crontab:  nightly tick
           └─ each enabled schedule whose cron matches this minute (and doRun=true), claimed
              atomically so two tickers cannot both fire it:
              creates Run(status running, scheduleId) and spawns, detached:
nightly exec <run>
           └─ spawns the runner: the `run.sh` prompt (kind script) written to a private temp file,
              or a path in setting `runner` / env NIGHTLY_RUNNER;
              with NIGHTLY_RUN_ID, NIGHTLY_SCHEDULE_ID/NAME, NIGHTLY_PROMPT, NIGHTLY_INSTRUCTIONS,
              NIGHTLY_MAX_TURNS, NIGHTLY_TRIGGER; streams its stdout/stderr into Run.log every 5 s;
              a line `::nightly-meta {"turns":..,"minutes":..,"costUsd":..}` fills those columns;
              when it exits, closes the run (ok/failed by exit code) unless the agent already did.

A schedule that does not allow overlap, due while another run is alive, gets a skipped run saying so. Start from scripts/run.sh or write your own (Prompts → New, name it run.sh): decide what is safe, then claude -p "$(nightly prompt show "$NIGHTLY_PROMPT")". nightly exec also passes NIGHTLY_ROOT, the repository's path.

N=$HOME/stack/nightly/bin/nightly
RUN=$($N run start)                            # the run exec created
$N agent join nightly-$RUN --kind nightly --run $RUN --task "..."
#   before changing a repo: $N agent claim nightly-$RUN <repo>  (exit 3 -> someone is there; message them, move on)
# prompt gets:  $N brief   (and the run id)
#   the agent works top-down:  $N show <key>, $N set <key> --status in_progress,
#   $N note <key> --run $RUN "where it stopped / what was done", $N set <key> --status done,
#   $N checks --due -> do each -> $N checked <key> --run $RUN --note "...",
#   new work found -> $N add --title ... --after <key> --repos ... --done-when ...
$N run finish "$RUN" --status ok --summary "one line" --report-file /tmp/report.md
$N agent leave nightly-$RUN

Rules carried over from the Markdown list: work Queue top-down; an item that cannot be finished in one night goes to in_progress with a note saying exactly where it stopped; items are written to be picked up cold (repos, files, a checkable "done when"); only the owner removes a Queue item without doing it; never delete — close as done/wontfix.

Item (key, title, body markdown, kind, status, priority, repos, doneWhen, addedBy, cadence, lastRunAt, completedAt), Note (item, optional run, author, body), Run (startedAt, finishedAt, status, summary, report, log, turns, minutes, costUsd, trigger, pid, schedule), Schedule (name, cron, enabled, prompt, instructions, maxTurns, allowOverlap, lastFiredAt), Agent (name, kind, task, repos, run, lastSeenAt, endedAt), Claim (agent, scope, note, releasedAt), Message (author, to, body), Prompt (name, kind prompt|script, body) with PromptVersion (every saved body), Setting (key/value; doRun, runner, usage limits). See prisma/schema.prisma.

bin/nightly, bin/nightly.mjs   CLI
lib/store.mjs                  CLI/import data layer (node:sqlite)
lib/runner.mjs                 tick / start / exec / stop
lib/agents.mjs                 the agent board (join, claim, messages)
lib/prompts.mjs                prompts and the runner script, versioned
lib/cron.mjs (+ .d.mts)        cron expressions, shared with the panel
lib/env.mjs                    loads .env for the CLI
src/instrumentation.ts         starts the built-in scheduler with the panel
prisma/schema.prisma           schema
scripts/import-markdown.ts     one-off importer (to-do list)
scripts/import-history.ts      one-off importer (report files, runner logs)
scripts/import-prompts.ts      one-off importer (prompt files, runner script)
scripts/run.sh                 the runner a schedule starts
scripts/claude-usage.sh        Claude plan usage (5-hour and weekly)
src/server/api.ts              tRPC router (items, notes, runs, schedules, prompts, agents, settings)
src/app/media/[...path]        screenshots
src/components/                list, item detail, runs, schedules, prompts, agents, settings UI
src/proxy.ts                   optional password
data/nightly.db                the database (gitignored)

Is this project actively maintained?

Yes and no. I still use it regularly, but I don't intend on actively developing new features or providing extensive support. As of right now, the project is perfect for personal use and meets my needs 🙂

What is your dev environment like?

I dedicate one of my homeservers from my home lab for development work on my personal projects including Gamespice, TekWorks, and my other general open source projects. I run a bunch of virtual machines that Claude Code has access to, which gives them full control to actively manage and interact with the development environment without restrictions. I've cut off the homeserver from crucial parts of my network in the very small chance that Claude Code agents do go rogue and try to nuke my home network 😅

MIT, see LICENSE.