Skip to content

Commit ca14255

Browse files
FvdHMBAIFvdHMBAI
committed
feat: story-driven README with morning summary mockup and ecosystem links
1 parent 96b7a69 commit ca14255

1 file changed

Lines changed: 181 additions & 103 deletions

File tree

‎README.md‎

Lines changed: 181 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,122 @@
1-
# Night Shift
1+
<h1 align="center">Night Shift</h1>
22

3-
[![Part of AgentStack](https://img.shields.io/badge/Part%20of-AgentStack-blue?style=flat-square)](https://github.com/FvdHMBAI/agent-stack)
3+
<p align="center">
4+
<a href="https://github.com/FvdHMBAI/agent-stack"><img src="https://img.shields.io/badge/Part%20of-AgentStack-blue?style=flat-square" alt="Part of AgentStack"></a>
5+
</p>
6+
7+
<p align="center">
8+
<strong>Your codebase improves while you sleep.</strong>
9+
</p>
10+
11+
<p align="center">
12+
<a href="https://github.com/FvdHMBAI/nightshift/actions"><img src="https://github.com/FvdHMBAI/nightshift/actions/workflows/ci.yml/badge.svg" alt="CI"></a>&nbsp;
13+
<a href="https://github.com/FvdHMBAI/nightshift/stargazers"><img src="https://img.shields.io/github/stars/FvdHMBAI/nightshift?style=social" alt="GitHub Stars"></a>&nbsp;
14+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
15+
</p>
16+
17+
<p align="center">
18+
<a href="#quick-start">Quick Start</a> ·
19+
<a href="#what-it-fixes">What It Fixes</a> ·
20+
<a href="#how-it-compares">Comparison</a> ·
21+
<a href="#architecture">Architecture</a> ·
22+
<a href="#agentstack-ecosystem">Ecosystem</a>
23+
</p>
24+
25+
---
426

5-
**Your codebase improves while you sleep.**
27+
I used to start every Monday reviewing the same lint errors, the same type mismatches, the same outdated dependencies. Now I wake up to a branch per fix, each one verified, each one ready to merge.
628

7-
Night Shift scans your repositories overnight, finds lint errors, TypeScript issues, security vulnerabilities, and documentation gaps — fixes them automatically, commits each fix to its own branch, and sends you a morning summary. Self-hosted, free, runs with your own LLM.
29+
Night Shift turned Monday mornings from cleanup into code review.
830

9-
[![CI](https://github.com/FvdHMBAI/nightshift/actions/workflows/ci.yml/badge.svg)](https://github.com/FvdHMBAI/nightshift/actions/workflows/ci.yml)
10-
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
11-
[![GitHub Stars](https://img.shields.io/github/stars/FvdHMBAI/nightshift?style=social)](https://github.com/FvdHMBAI/nightshift/stargazers)
31+
It scans your repositories overnight, finds lint errors, TypeScript issues, security vulnerabilities, and documentation gaps. Fixes them automatically. Commits each fix to its own branch. Sends you a morning summary. Self-hosted, free, runs with your own LLM.
32+
33+
---
1234

1335
<p align="center">
1436
<img src="demo/demo.gif" alt="Night Shift Demo" width="700">
1537
</p>
1638

39+
---
40+
41+
## Morning Summary
42+
43+
This is what arrives on your phone before your first coffee:
44+
45+
```
46+
Night Shift Run Complete
47+
2026-08-07 | 5 repos | 22:00 - 02:47
48+
49+
FIXED (12 branches ready to merge)
50+
my-frontend
51+
nightshift/lint-fix-no-unused-vars eslint --fix
52+
nightshift/type-fix-missing-null-check LLM patch + tsc verified
53+
nightshift/deps-update-minor-patch npm update (13 packages)
54+
55+
my-api
56+
nightshift/lint-fix-prefer-const eslint --fix
57+
nightshift/security-fix-express-4.19 npm audit fix + build OK
58+
nightshift/type-fix-async-return LLM patch + tsc verified
59+
nightshift/docs-expand-readme 24 lines -> 89 lines
60+
61+
my-backend
62+
nightshift/lint-fix-unused-imports eslint --fix
63+
nightshift/type-fix-optional-chain LLM patch + tsc verified
64+
nightshift/security-fix-jsonwebtoken npm audit fix + build OK
65+
66+
shared-lib
67+
nightshift/lint-fix-consistent-return eslint --fix
68+
nightshift/deps-update-minor-patch npm update (7 packages)
69+
70+
ROLLED BACK (2 tasks)
71+
my-frontend type-fix-complex-generic tsc failed after patch
72+
my-api deps-update-major build broke, reverted
73+
74+
STATS
75+
Tasks created: 14
76+
Tasks completed: 12 (85.7%)
77+
Tasks failed: 2 (auto-rolled back)
78+
LLM tokens used: 23,400 (Ollama qwen3:8b, $0.00)
79+
Duration: 4h 47m
80+
```
81+
82+
Every branch is isolated. Nothing touches your working code. You review, you merge, you move on.
83+
84+
---
85+
86+
## Why Night Shift?
87+
88+
| | Night Shift | Devin | CodeRabbit | Sweep (dead) |
89+
|---|---|---|---|---|
90+
| **Cost** | Free (self-hosted) | $500/mo | $15/mo+ | Shut down |
91+
| **Your data** | Stays on your server | Sent to cloud | Sent to cloud | N/A |
92+
| **LLM choice** | Ollama / Claude / GPT | Proprietary | Proprietary | N/A |
93+
| **Approach** | Overnight batch fixes | Interactive agent | PR review only | Issue to PR |
94+
| **What it fixes** | Lint, types, security, docs | Everything (slowly) | Nothing (reviews only) | Issues |
95+
| **Safety** | Branch per fix, auto-rollback | Full repo access | Read-only | Full access |
96+
| **Setup** | 5 minutes | Account + billing | GitHub app | N/A |
97+
98+
**Night Shift is not trying to be Devin.** It handles the boring, repetitive maintenance that piles up. The kind of work nobody wants to do but everybody benefits from. It runs when you sleep, uses your own LLM, and every fix lands on its own branch for you to review.
99+
100+
---
101+
102+
## What it fixes
103+
104+
| Category | Detection | Fix method | Verification |
105+
|----------|-----------|------------|--------------|
106+
| **Lint** | `eslint --quiet` | `eslint --fix` | Re-lint |
107+
| **Types** | `tsc --noEmit` | LLM-assisted patch | `tsc --noEmit` re-check |
108+
| **Security** | `npm audit` (high/critical) | `npm audit fix` + individual upgrades | TypeScript + build check |
109+
| **Docs** | README < 20 lines | LLM-generated expansion | Length check |
110+
| **Deps** | `npm outdated` | `npm update` (minor/patch only) | TypeScript + Next.js build |
111+
112+
Every fix runs on its own branch (`nightshift/lint-fix-20260801-eslint-no-unused-vars`), so you always review before merging.
113+
114+
---
115+
116+
<a id="architecture"></a>
117+
118+
## Architecture
119+
17120
```
18121
Night Shift Architecture
19122
@@ -49,31 +152,18 @@ Night Shift scans your repositories overnight, finds lint errors, TypeScript iss
49152
└──────────────────────┘ └──────────────────────┘
50153
```
51154

52-
## Why Night Shift?
53-
54-
| | Night Shift | Devin | CodeRabbit | Sweep (dead) |
55-
|---|---|---|---|---|
56-
| **Cost** | Free (self-hosted) | $500/mo | $15/mo+ | Shut down |
57-
| **Your data** | Stays on your server | Sent to cloud | Sent to cloud | — |
58-
| **LLM choice** | Ollama / Claude / GPT | Proprietary | Proprietary | — |
59-
| **Approach** | Overnight batch fixes | Interactive agent | PR review only | Issue→PR |
60-
| **What it fixes** | Lint, types, security, docs | Everything (slowly) | Nothing (reviews only) | Issues |
61-
| **Safety** | Branch per fix, auto-rollback | Full repo access | Read-only | Full access |
62-
| **Setup** | 5 minutes | Account + billing | GitHub app | — |
63-
64-
**Night Shift is not trying to be Devin.** It handles the boring, repetitive maintenance that piles up — the kind of work nobody wants to do but everybody benefits from. It runs when you're asleep, uses your own LLM, and every fix lands on its own branch for you to review.
155+
### Safety guarantees
65156

66-
## What it fixes
157+
1. **Branch isolation.** Every fix gets its own branch. Your main/develop is never touched.
158+
2. **Backup tags.** Created before any changes, recoverable with `git tag -l 'nightshift-backup/*'`.
159+
3. **Compilation verification.** TypeScript check after every npm change. Breaks? Automatic rollback.
160+
4. **Stash protection.** Uncommitted work is stashed before, restored after.
161+
5. **RAM monitoring.** Stops spawning workers if memory drops below threshold.
162+
6. **Task timeout.** 2-hour default prevents runaway processes.
163+
7. **Lockfile.** Prevents concurrent coordinator runs.
164+
8. **Risk classification.** High-risk tasks are flagged, complex ones deferred to a stronger model.
67165

68-
| Category | Detection | Fix method | Verification |
69-
|----------|-----------|------------|--------------|
70-
| **Lint** | `eslint --quiet` | `eslint --fix` | Re-lint |
71-
| **Types** | `tsc --noEmit` | LLM-assisted patch | `tsc --noEmit` re-check |
72-
| **Security** | `npm audit` (high/critical) | `npm audit fix` + individual upgrades | TypeScript + build check |
73-
| **Docs** | README < 20 lines | LLM-generated expansion | Length check |
74-
| **Deps** | `npm outdated` | `npm update` (minor/patch only) | TypeScript + Next.js build |
75-
76-
Every fix runs on its own branch (`nightshift/lint-fix-20260801-eslint-no-unused-vars`), so you always review before merging.
166+
---
77167

78168
## Quick Start
79169

@@ -91,7 +181,7 @@ git clone https://github.com/FvdHMBAI/nightshift.git
91181
cd nightshift
92182

93183
# 1. Configure
94-
cp config.sh config.local.sh # keep your settings separate
184+
cp config.sh config.local.sh
95185
vim config.local.sh # add repos, DB connection, LLM
96186

97187
# 2. Install (creates tables, cron jobs, checks deps)
@@ -114,113 +204,92 @@ REPOS=(
114204
)
115205

116206
# Database
117-
DB_MODE="postgres" # or "docker"
207+
DB_MODE="postgres"
118208
DB_URL="postgresql://user:pass@localhost:5432/nightshift"
119-
# DB_CONTAINER="my-postgres" # if mode=docker
120209

121-
# LLM — Ollama is default (free, local)
122-
OLLAMA_MODEL="qwen3:8b" # any Ollama model
123-
# ANTHROPIC_API_KEY="sk-ant-..." # optional: better type/doc fixes
210+
# LLM: Ollama is default (free, local)
211+
OLLAMA_MODEL="qwen3:8b"
212+
# ANTHROPIC_API_KEY="sk-ant-..." # optional: better type/doc fixes
124213

125214
# Limits
126-
MAX_TASKS=15 # max tasks per run
127-
MAX_WORKERS=3 # parallel workers
128-
MAX_TASK_DURATION=7200 # 2h timeout per task
129-
MIN_FREE_RAM_MB=3072 # abort if < 3GB free
215+
MAX_TASKS=15
216+
MAX_WORKERS=3
217+
MAX_TASK_DURATION=7200 # 2h timeout per task
218+
MIN_FREE_RAM_MB=3072 # abort if < 3GB free
130219

131220
# Notifications (ntfy.sh compatible)
132221
# NTFY_URL="https://ntfy.sh/my-nightshift"
133222
```
134223

224+
---
225+
135226
## How it works
136227

137228
```
138229
22:00 Coordinator starts
139230
├── Check RAM, create run record
140231
├── For each repo:
141232
│ ├── git fetch origin develop
142-
│ ├── ESLint scan → findings
143-
│ ├── TypeScript scan → findings
144-
│ ├── npm audit → findings
145-
│ ├── Test coverage check → findings
146-
│ └── README length check → findings
233+
│ ├── ESLint scan
234+
│ ├── TypeScript scan
235+
│ ├── npm audit
236+
│ ├── Test coverage check
237+
│ └── README length check
147238
│
148-
├── Classify findings → tasks (low/medium/high risk)
239+
├── Classify findings into tasks (low/medium/high risk)
149240
│
150241
├── Run workers (up to 3 parallel):
151242
│ ├── Create nightshift/* branch
152243
│ ├── Apply fix
153244
│ ├── Verify (tsc --noEmit, build check)
154-
│ ├── If broken → rollback, mark failed
155-
│ ├── If clean → commit, push, mark completed
245+
│ ├── If broken: rollback, mark failed
246+
│ ├── If clean: commit, push, mark completed
156247
│ └── Generate lesson (optional)
157248
│
158-
└── Generate summary → DB + ntfy notification
249+
└── Generate summary, send to DB + ntfy
159250
160251
06:00 Morning summary (catches any unfinished runs)
161252
```
162253

163-
### Safety guarantees
164-
165-
1. **Branch isolation** — every fix gets its own branch. Your main/develop is never touched.
166-
2. **Backup tags** — created before any changes, recoverable with `git tag -l 'nightshift-backup/*'`.
167-
3. **Compilation verification** — TypeScript check after every npm change. Breaks → automatic rollback.
168-
4. **Stash protection** — uncommitted work is stashed before, restored after.
169-
5. **RAM monitoring** — stops spawning workers if memory drops below threshold.
170-
6. **Task timeout** — 2-hour default prevents runaway processes.
171-
7. **Lockfile** — prevents concurrent coordinator runs.
172-
8. **Risk classification** — high-risk tasks (security) are flagged, complex ones deferred to Claude.
173-
174-
## Database
175-
176-
Night Shift uses PostgreSQL to track every run, task, and generated lesson:
177-
178-
```sql
179-
-- Recent runs
180-
SELECT started_at, tasks_created, tasks_completed, tasks_failed, summary
181-
FROM nightshift_runs ORDER BY started_at DESC LIMIT 5;
182-
183-
-- Failed tasks (what to investigate)
184-
SELECT repo, category, title, error_message
185-
FROM nightshift_tasks WHERE status = 'failed'
186-
ORDER BY created_at DESC LIMIT 10;
187-
188-
-- Lessons generated
189-
SELECT topic, concept_category, difficulty, created_at
190-
FROM lessons ORDER BY created_at DESC LIMIT 10;
191-
```
254+
---
192255

193256
## Lesson Generator (Pro)
194257

195-
Every completed fix generates a learning lesson explaining the programming concept behind the change — not just what was fixed, but why it matters. Stored in the database with topic, difficulty, code before/after, and exercises.
258+
Every completed fix generates a learning lesson explaining the programming concept behind the change. Not just what was fixed, but why it matters. Stored in the database with topic, difficulty, code before/after, and exercises.
196259

197260
Works best with an Anthropic API key but falls back to Ollama.
198261

262+
---
263+
199264
## Environment Variables
200265

201266
| Variable | Default | Description |
202267
|----------|---------|-------------|
203268
| `NIGHTSHIFT_DB_URL` | `postgresql://...localhost:5432/nightshift` | PostgreSQL connection |
204269
| `NIGHTSHIFT_DB_MODE` | `postgres` | `postgres` or `docker` |
205-
| `NIGHTSHIFT_DB_CONTAINER` | — | Docker container (if mode=docker) |
270+
| `NIGHTSHIFT_DB_CONTAINER` | n/a | Docker container (if mode=docker) |
206271
| `NIGHTSHIFT_DB_NAME` | `nightshift` | Database name (docker mode) |
207272
| `NIGHTSHIFT_DB_USER` | `postgres` | Database user (docker mode) |
208273
| `OLLAMA_URL` | `http://localhost:11434/api/generate` | Ollama endpoint |
209274
| `OLLAMA_MODEL` | `qwen3:8b` | Local LLM model |
210-
| `ANTHROPIC_API_KEY` | — | Claude API (optional, Pro features) |
275+
| `ANTHROPIC_API_KEY` | n/a | Claude API (optional, Pro features) |
211276
| `NIGHTSHIFT_CLAUDE_MODEL` | `claude-sonnet-4-6` | Claude model |
212-
| `NIGHTSHIFT_NTFY_URL` | — | ntfy.sh notification URL |
277+
| `NIGHTSHIFT_NTFY_URL` | n/a | ntfy.sh notification URL |
213278
| `NIGHTSHIFT_LOG_DIR` | `/var/log/nightshift` | Log directory |
214279
| `NIGHTSHIFT_LESSON_DIR` | `./lessons` | Lesson output directory |
215280

281+
---
282+
216283
## Extending Night Shift
217284

218285
Add custom task categories by:
219286

220-
1. Adding a scanner in `coordinator.sh` → `scan_repo()` that outputs `repo|category|title|description`
221-
2. Adding a handler in `worker.sh` → `case "$category" in your-category) execute_your_fix && success=true ;;`
287+
1. Adding a scanner in `coordinator.sh` that outputs `repo|category|title|description`
288+
2. Adding a handler in `worker.sh` with a `case "$category"` branch
222289
3. That's it. The coordinator/worker/summary pipeline handles the rest.
223290

291+
---
292+
224293
## FAQ
225294

226295
**Can it break my code?**
@@ -230,42 +299,51 @@ Every fix runs on its own branch. If TypeScript compilation fails after a fix, t
230299
Yes. Add the monorepo root to `REPOS`. The scanner checks for ESLint, TypeScript, and npm audit at the configured paths.
231300

232301
**What LLMs does it support?**
233-
Any Ollama model (local, free) or Anthropic Claude (cloud, paid). The TypeScript fixer and doc generator use the LLM; lint and security fixes are deterministic tools.
302+
Any Ollama model (local, free) or Anthropic Claude (cloud, paid). The TypeScript fixer and doc generator use the LLM. Lint and security fixes are deterministic tools.
234303

235304
**How much does it cost to run?**
236305
With Ollama: $0. With Claude API: typically $0.02-0.10 per run depending on findings. The system logs token usage per task.
237306

238307
**Can I run it manually?**
239308
Yes: `./coordinator.sh` runs a full cycle. `./summary-morning.sh` generates/sends the summary.
240309

241-
## How It Compares
310+
---
311+
312+
<a id="agentstack-ecosystem"></a>
313+
314+
## AgentStack Ecosystem
315+
316+
Night Shift is one piece of a complete AI operations stack. Each tool solves one problem well:
317+
318+
| Tool | What it does | Link |
319+
|------|-------------|------|
320+
| **[GuardRail](https://github.com/FvdHMBAI/guardrail)** | Pre-execution security for AI agents. Blocks dangerous commands before they run. | [Repo](https://github.com/FvdHMBAI/guardrail) |
321+
| **[Model Router](https://github.com/FvdHMBAI/model-router)** | Shell-native LLM routing. One config, every model, zero dependencies. | [Repo](https://github.com/FvdHMBAI/model-router) |
322+
| **Night Shift** | Overnight codebase maintenance. You are here. | |
323+
| **[Graphify Toolkit](https://github.com/FvdHMBAI/graphify-toolkit)** | Turn any codebase into a queryable knowledge graph. | [Repo](https://github.com/FvdHMBAI/graphify-toolkit) |
324+
| **[Autonomie OS](https://github.com/FvdHMBAI/autonomie-os)** | Self-improving AI agent framework. Learns from every session. | [Repo](https://github.com/FvdHMBAI/autonomie-os) |
242325

243-
| | Night Shift | Renovate / Dependabot | CodeRabbit | Devin | Sweep (dead) |
244-
|---|---|---|---|---|---|
245-
| **Scope** | Lint + types + security + docs + deps | Dependencies only | Review only (no fixes) | Everything (interactive) | Issue-to-PR |
246-
| **Runs when** | Overnight (cron) | On dependency update | On PR creation | On demand | On issue creation |
247-
| **LLM choice** | Ollama (free) or Claude | None (rule-based) | Proprietary | Proprietary | Proprietary |
248-
| **Self-hosted** | Yes | Partial (GitHub app) | No (SaaS) | No (cloud) | No |
249-
| **Branch isolation** | Yes (one branch per fix) | Yes | N/A (no changes) | No (works in-place) | Yes |
250-
| **Auto-rollback** | Yes (tsc fails = revert) | No | N/A | No | No |
251-
| **Cost** | $0 (Ollama) / ~$0.05/run (Claude) | Free tier | $15/mo+ | $500/mo | Shut down |
252-
| **Data stays local** | Yes | Partial | No | No | No |
253-
| **Verification** | TypeScript + build check | CI pipeline | None | Manual review | CI pipeline |
254-
| **Lesson generation** | Yes (Pro: explains WHY) | No | No | No | No |
326+
All five tools are open source, self-hosted, and work together. GuardRail protects. Model Router picks the right model. Night Shift maintains the code. Graphify maps the architecture. Autonomie OS makes agents smarter over time.
255327

256-
**Different category.** Renovate and Dependabot handle one slice (dependency updates). CodeRabbit reviews but never fixes. Devin is a full interactive agent ($500/mo). Night Shift covers the boring maintenance layer between those tools: lint, types, security, docs. It runs unattended, on your hardware, with your LLM, and every fix is isolated on its own branch.
328+
---
329+
330+
## Learn More
331+
332+
Want to understand how these tools fit into a complete AI governance strategy? The free course covers guard design, model routing, autonomous operations, and more:
257333

258-
## Part of AgentStack
334+
**[KI-Governance Kurs](https://lernen.promptandbuild.de)** (18 lessons, free)
259335

260-
This tool is free and always will be. For teams that need the full governance stack (GuardRail Pro + Compliance Shield + priority support), see [AgentStack Pro](https://github.com/FvdHMBAI/agent-stack/blob/main/BUNDLE.md) (EUR 79/dev/month).
336+
---
261337

262338
## License
263339

264-
MIT — see [LICENSE](LICENSE)
340+
MIT. See [LICENSE](LICENSE).
265341

266342
---
267343

268-
Built by [Prompt & Build](https://promptandbuild.de). Running 13+ SaaS products with AI agents.
344+
<p align="center">
345+
Built by <a href="https://promptandbuild.de">Prompt & Build</a>.
346+
</p>
269347

270348
<p align="center">
271349
If Night Shift saves you maintenance time, consider giving it a <a href="https://github.com/FvdHMBAI/nightshift">star</a>. It helps others find it.

0 commit comments

Comments
 (0)