{"id":47890485,"url":"https://github.com/recusive/nightshift","last_synced_at":"2026-04-04T03:01:07.763Z","repository":{"id":348820912,"uuid":"1200004489","full_name":"Recusive/Nightshift","owner":"Recusive","description":"Autonomous overnight codebase improvement agent for Claude Code. Run it before bed, wake up to production-ready fixes.","archived":false,"fork":false,"pushed_at":"2026-04-03T03:20:36.000Z","size":570,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T10:43:51.576Z","etag":null,"topics":["ai-agent","anthropic","automation","claude","claude-code","code-quality","developer-tools","overnight-agent","production-readiness","skill"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Recusive.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-02T23:56:14.000Z","updated_at":"2026-04-03T00:28:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"88c78f4b-b290-402f-be77-a55857c05919","html_url":"https://github.com/Recusive/Nightshift","commit_stats":null,"previous_names":["recusive/nightshift"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/Recusive/Nightshift","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Recusive%2FNightshift","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Recusive%2FNightshift/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Recusive%2FNightshift/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Recusive%2FNightshift/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Recusive","download_url":"https://codeload.github.com/Recusive/Nightshift/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Recusive%2FNightshift/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31385935,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T01:22:39.193Z","status":"online","status_checked_at":"2026-04-04T02:00:07.569Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","anthropic","automation","claude","claude-code","code-quality","developer-tools","overnight-agent","production-readiness","skill"],"created_at":"2026-04-04T03:00:50.528Z","updated_at":"2026-04-04T03:01:07.749Z","avatar_url":"https://github.com/Recusive.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/icon.png\" alt=\"Nightshift\" width=\"240\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eNightshift\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eYour overnight engineer. Autonomous. Thorough. Ready by morning.\u003c/strong\u003e\u003cbr/\u003e\n  Run it before bed. Wake up to a reviewed worktree, a shift log, and a machine-readable record of what the agent actually did.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Codex-Supported-10B981\" alt=\"Codex\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Claude-Supported-F97316\" alt=\"Claude Code\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-22C55E\" alt=\"MIT License\" /\u003e\n\u003c/p\u003e\n\n---\n\n## About\n\nNightshift is an overnight codebase-hardening runner built by **[Recursive Labs](https://github.com/Recusive)** as part of the [Orbit](https://github.com/Recusive/Orbit-Release) ecosystem.\n\nThe original version relied mostly on prompt discipline. This version adds a real control plane:\n\n- a Python orchestrator (the `nightshift/` package)\n- pluggable agent adapters (Codex and Claude — pick one, both go through the same pipeline)\n- machine-readable shift state (`docs/Nightshift/YYYY-MM-DD.state.json`)\n- runner-enforced guard rails, verification gates, and halt conditions\n\n---\n\n## What It Does\n\nNightshift runs in an isolated git worktree and repeatedly asks an agent to:\n\n1. read the current repo instructions and shift log\n2. find a small production-readiness improvement\n3. fix it or log it\n4. verify it\n5. record it\n\nThe runner enforces the difference between a productive overnight shift and 8 hours of churn.\n\n### Runner-enforced guard rails\n\n- Max `3` fixes per cycle\n- Max `5` files per fix\n- Max `12` files touched per cycle\n- Max `4` low-impact fixes per shift\n- Blocked edits for CI/deploy/infra/generated files and lockfiles\n- Hot-file protection via recent git activity\n- Halt after repeated failed verification or empty cycles\n- Worktree must end clean after every accepted cycle\n- Each fix commit must include the shift log update\n\n### Output artifacts\n\n- `docs/Nightshift/YYYY-MM-DD.md` — human-readable shift log\n- `docs/Nightshift/YYYY-MM-DD.state.json` — machine-readable cycle state\n- `docs/Nightshift/YYYY-MM-DD.runner.log` — raw runner output\n- `nightshift/YYYY-MM-DD` — isolated review branch\n\n---\n\n## Architecture\n\n```\nMain repo checkout                 Nightshift worktree\n├── untouched                      ├── agent edits happen here\n├── no branch switching            ├── isolated nightshift/YYYY-MM-DD branch\n└── receives copied logs           └── verification happens after each cycle\n```\n\n### Key files\n\n| File | Purpose |\n|------|---------|\n| `nightshift/` | Python package — orchestrator, policy engine, verifier, state manager |\n| `nightshift/types.py` | TypedDicts for all data structures (strict typing) |\n| `nightshift/constants.py` | DATA_VERSION, DEFAULT_CONFIG, SHIFT_LOG_TEMPLATE, etc. |\n| `nightshift/errors.py` | NightshiftError |\n| `nightshift/shell.py` | run_command, run_capture, git, command_exists, run_shell_string |\n| `nightshift/config.py` | merge_config, resolve_agent, infer_package_manager, infer_verify_command |\n| `nightshift/state.py` | read_state, write_json, load_json, append_cycle_state, top_path |\n| `nightshift/worktree.py` | ensure_worktree, ensure_shift_log, sync_shift_log, revert_cycle, cleanup_safe_artifacts |\n| `nightshift/cycle.py` | build_prompt, command_for_agent, verify_cycle, evaluate_baseline, extract_json |\n| `nightshift/cli.py` | run_nightshift, summarize, verify_cycle_cli, build_parser, main |\n| `nightshift.schema.json` | Required final-response schema for agent cycles |\n| `pyproject.toml` | Project config: mypy strict, ruff lint/format, pytest |\n| `requirements-dev.txt` | Pinned dev tool versions (mypy, ruff, pytest) |\n| `scripts/check.sh` | Local CI — runs all checks (mirrors GitHub Actions) |\n| `.github/workflows/ci.yml` | CI pipeline: lint, typecheck, test, integration, artifact validation |\n| `nightshift/SKILL.md` | Interactive nightshift skill instructions |\n| `scripts/run.sh` | Thin wrapper around `python3 -m nightshift run` |\n| `scripts/test.sh` | Thin wrapper around `python3 -m nightshift test` |\n| `.nightshift.json.example` | Optional per-repo config template |\n\n---\n\n## Install\n\n### One-liner\n\n```bash\ncurl -sL https://raw.githubusercontent.com/Recusive/Nightshift/main/scripts/install.sh | bash\n```\n\nThis installs Nightshift into both:\n\n- `~/.codex/skills/nightshift`\n- `~/.claude/skills/nightshift`\n\n### Repo setup\n\nAdd runtime artifacts to `.gitignore`:\n\n```bash\ncat \u003c\u003c'EOF' \u003e\u003e .gitignore\ndocs/Nightshift/worktree-*/\ndocs/Nightshift/*.runner.log\ndocs/Nightshift/*.state.json\nEOF\n```\n\nOptional: copy the config template into the repo root:\n\n```bash\ncp ~/.codex/skills/nightshift/.nightshift.json.example .nightshift.json\n```\n\n---\n\n## Config\n\nNightshift looks for `.nightshift.json` in the repo root.\n\nSupported keys:\n\n```json\n{\n  \"agent\": \"codex or claude\",\n  \"hours\": 8,\n  \"cycle_minutes\": 30,\n  \"verify_command\": null,\n  \"blocked_paths\": [\".github/\", \"infra/\", \"deploy/\"],\n  \"blocked_globs\": [\"*.lock\", \"package-lock.json\"],\n  \"max_fixes_per_cycle\": 3,\n  \"max_files_per_fix\": 5,\n  \"max_files_per_cycle\": 12,\n  \"max_low_impact_fixes_per_shift\": 4,\n  \"stop_after_failed_verifications\": 2,\n  \"stop_after_empty_cycles\": 2,\n  \"score_threshold\": 3,\n  \"test_incentive_cycle\": 3,\n  \"backend_forcing_cycle\": 3\n}\n```\n\nIf `verify_command` is omitted, Nightshift tries to infer one from common repo manifests such as `package.json`, `Cargo.toml`, `go.mod`, and `pyproject.toml`.\n\n---\n\n## Usage\n\n### Overnight run\n\n```bash\n~/.codex/skills/nightshift/scripts/run.sh            # prompts for agent choice\n~/.codex/skills/nightshift/scripts/run.sh --agent codex\n~/.codex/skills/nightshift/scripts/run.sh --agent claude\n~/.codex/skills/nightshift/scripts/run.sh 10          # 10 hours\n~/.codex/skills/nightshift/scripts/run.sh 6 45        # 6 hours, 45 min per cycle\n```\n\nIf no `--agent` flag is passed and `.nightshift.json` doesn't set one, the runner asks which agent to use.\n\n### Short validation run\n\n```bash\n~/.codex/skills/nightshift/scripts/test.sh\n~/.codex/skills/nightshift/scripts/test.sh --agent codex --cycles 2 --cycle-minutes 5\n```\n\n### Multi-repo run\n\n```bash\npython3 -m nightshift multi /path/to/repo1 /path/to/repo2 --agent codex\npython3 -m nightshift multi /path/to/repo1 /path/to/repo2 --agent codex --test --cycles 2\n```\n\nRuns a full hardening shift on each repo sequentially. Validates all repos upfront, prints an aggregate summary at the end.\n\n### Direct orchestrator usage\n\n```bash\npython3 -m nightshift run\npython3 -m nightshift run --agent codex\npython3 -m nightshift run --agent claude\npython3 -m nightshift test\npython3 -m nightshift multi /path/to/repo1 /path/to/repo2 --agent codex\npython3 -m nightshift summarize\n```\n\nBoth agents go through the same runner, same verification, same policy enforcement. The only difference is the CLI command each adapter constructs.\n\n---\n\n## Morning Review\n\n```bash\ncat docs/Nightshift/2026-04-02.md\ncat docs/Nightshift/2026-04-02.state.json\ngit log nightshift/2026-04-02 --oneline\ngit merge nightshift/2026-04-02\ngit worktree remove docs/Nightshift/worktree-2026-04-02\ngit branch -d nightshift/2026-04-02\n```\n\nThe shift log is for humans. The state file is for quick auditing:\n\n- how many cycles ran\n- which categories were touched\n- which files changed\n- whether verification passed\n- why the run stopped\n\n---\n\n## Requirements\n\n- Python 3.9+\n- Git\n- `codex` CLI or `claude` CLI (whichever agent you choose)\n\n---\n\n## Roadmap\n\n- [x] Pluggable agent adapters (Codex, Claude)\n- [x] Runner-enforced guard rails\n- [x] Structured cycle outputs and state files\n- [x] Post-cycle diff scoring before accepting a fix\n- [x] Cycle-to-cycle state injection\n- [x] Test writing incentives\n- [x] Backend exploration forcing\n- [x] Validated against real monorepo (Phractal)\n- [ ] Smarter category balancing\n- [ ] Loop 2: Feature Builder (plan, decompose, build, test)\n- [ ] Built-in to Orbit as a native feature\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frecusive%2Fnightshift","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frecusive%2Fnightshift","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frecusive%2Fnightshift/lists"}