mirror of https://github.com/khodges42/nightShift.git synced 2026-06-14 10:08:37 +00:00

Framework for orchestrating long running LLM projects, for local models. Highly auditable, highly customizable. Anything from designing software to writing novels.

Go to file

K. Hodges 5958c82cf9 First docs		2026-05-16 23:56:58 -07:00
docs	First docs	2026-05-16 23:56:58 -07:00
.gitattributes	Initial commit	2026-05-16 23:43:13 -07:00
.gitignore	Initial commit	2026-05-16 23:43:13 -07:00
LICENSE	Initial commit	2026-05-16 23:43:13 -07:00
README.md	First docs	2026-05-16 23:56:58 -07:00

README.md

NightShift

Auditable local-first AI coding pipelines.

Wake up to reviewable work, not chaos.

NightShift is a deterministic pipeline runner for long-running AI-assisted coding workflows.

It is designed for overnight or unattended execution against a scoped project repository using local or external coding agents.

NightShift is not an autonomous coding god.

It is a safety-aware orchestration system that treats LLMs like unreliable distributed systems.

Agents are bounded by:

scoped repository access
structured pipeline stages
tests and static analysis
retry limits
review stages
context compaction
durable artifacts

The output is:

reviewable code
plans
logs
diffs
test output
review notes
overnight summaries

Not blind autonomous shipping.

Why?

Most "AI coding agents" optimize for:

autonomy
demo magic
speed
vibes

NightShift optimizes for:

Cheapness
Correctness
Auditability
Speed

NightShift is also intended to serve as an experimentation platform for AI-assisted software engineering workflows.

The system is intentionally designed to facilitate testing and comparison of:

different models
different agent roles
prompt structures
system prompts
retry strategies
review strategies
context compaction techniques
pipeline structures
reasoning formats
constraint-driven workflows

The pipeline architecture should make these experiments reproducible, auditable, and configurable rather than hidden inside opaque agent behavior.

The assumption is simple:

AI systems are useful but unreliable.

NightShift embraces this reality by building deterministic orchestration around nondeterministic agents.

Features

Local-first execution

Designed primarily for:

Ollama
local models
Codex CLI
Claude Code
command-driven wrappers

Use cheap local models for most work. Escalate expensive models only where useful.

Declarative pipelines

Define workflows in YAML:

pipeline:
  stages:
    - id: plan
      type: agent
      agent: planner

    - id: implement
      type: agent
      agent: implementer

    - id: test
      type: command
      commands:
        - cargo test

    - id: review
      type: review
      agent: reviewer

Pipelines are intentionally portable and configurable so users can experiment with:

model routing
review loops
retry logic
prompt engineering
reasoning formats
planning strategies
context structures
cost/performance tradeoffs

NightShift is designed to make these workflow experiments measurable and repeatable rather than ad-hoc.

pipeline:
  stages:
    - id: plan
      type: agent
      agent: planner

    - id: implement
      type: agent
      agent: implementer

    - id: test
      type: command
      commands:
        - cargo test

    - id: review
      type: review
      agent: reviewer

Review-first workflows

NightShift is designed around:

plan
  -> review
  -> implement
  -> test
  -> static analysis
  -> review
  -> retry or complete

The goal is:

Wake up to a useful review package.

Durable artifacts

Every run creates a full audit trail.

Example:

.nightshift/
  runs/
    2026-05-16-overnight/
      run-summary.md

      tasks/
        TASK-001/
          plan.md
          review.md
          implementation-log.md
          test-output.txt
          diff.patch

This makes:

debugging easier
prompt experimentation possible
retries understandable
failures inspectable
portfolio demos stronger

Scoped repository safety

NightShift can:

restrict writable directories
allowlist commands
block dangerous shell operations
require clean git worktrees

The system is intentionally conservative.

Philosophy

NightShift follows a few core principles.

Deterministic orchestration

Agents are probabilistic.

The pipeline runner should not be.

Context compaction

Do not dump infinite history into prompts.

Use:

project context
task context
retry summaries

Keep context compact and intentional.

Reviewability over autonomy

NightShift is optimized to produce:

reviewable work
reviewable reasoning
reviewable failure

Not autonomous deployment.

Boring reliability beats magical demos

The system should:

fail clearly
retry explicitly
preserve artifacts
avoid spooky hidden behavior

Architecture Overview

Task Parser
    ↓
Pipeline Runner
    ↓
Stage Executor
 ┌────┴────┐
 ↓         ↓
Agents   Commands

Core components:

Task parser
Pipeline runner
Stage executor
Agent wrappers
Command runner
Artifact store
Context manager
Safety layer

Example Workflow

Input:

repository
tasks.md
nightshift.yaml
agent prompt files

Execution:

TASK-001
  ↓
plan
  ↓
review_plan
  ↓
implement
  ↓
test
  ↓
static analysis
  ↓
review
  ↓
complete or retry

Output:

modified repository
task artifacts
overnight report
review notes

Installation

Status

NightShift is currently an early-stage project.

The MVP focuses on:

local-first execution
declarative pipelines
task orchestration
artifact generation
safe command execution
reviewable workflows

Planned Installation

Python version:

pip install nightshift

Development install:

git clone <repo>
cd nightshift
pip install -e .

Quickstart

1. Initialize a project

nightshift init

Creates:

nightshift.yaml
tasks.md
agents/

2. Define tasks

Example:

- [ ] TASK-001: Add YAML config loading

Description:
Implement config loading for NightShift.

Acceptance Criteria:
- Loads `nightshift.yaml`
- Validates required fields
- Includes tests

3. Configure pipeline

Example:

project:
  root: .
  task_file: tasks.md
  artifact_dir: .nightshift

pipeline:
  max_task_retries: 3

4. Run NightShift

nightshift run

Or:

nightshift run --task TASK-001

5. Review artifacts

.nightshift/runs/<run-id>/

Contains:

plans
logs
diffs
test output
review notes
summaries

Example Config

project:
  name: example-project
  root: .
  task_file: tasks.md
  artifact_dir: .nightshift

safety:
  require_clean_worktree: true

  scoped_paths:
    - src/
    - tests/

  allowed_commands:
    - cargo test
    - cargo fmt --check

  forbidden_commands:
    - rm -rf
    - git push

agents:
  planner:
    backend: command
    command: codex
    system_prompt: agents/planner.md

  implementer:
    backend: command
    command: codex
    system_prompt: agents/implementer.md

  reviewer:
    backend: command
    command: codex
    system_prompt: agents/reviewer.md

pipeline:
  max_task_retries: 3

  stages:
    - id: plan
      type: agent
      agent: planner

    - id: implement
      type: agent
      agent: implementer

    - id: test
      type: command
      commands:
        - cargo test

    - id: review
      type: review
      agent: reviewer

Safety Model

NightShift intentionally limits agent freedom.

Repository scope restrictions

Agents should only operate within configured project paths.

Command allowlists

Commands must be explicitly permitted.

Example:

allowed_commands:
  - cargo test
  - cargo fmt --check

Dangerous command blocking

NightShift may block commands such as:

rm -rf
git push
curl | bash

Review-first workflow

The system assumes:

Humans remain the final authority.

Roadmap

MVP

YAML config loading
Markdown task parsing
Pipeline execution
Fake command agents
Artifact generation
Safe command execution
Retry handling
Overnight reports

Future

Ollama integration
Claude Code integration
Codex integration
Parallel execution
DAG workflows
Prompt A/B testing
Cost telemetry
Git branch isolation
Dashboard UI
Constraint-language experimentation

Inspiration

NightShift is inspired by:

CI/CD systems
build pipelines
state machines
agent orchestration research
distributed systems thinking
local-first tooling
practical AI skepticism

Philosophy Statement

NightShift rejects two extremes:

Fully manual engineering

Too slow.

Reckless autonomous agents

Too unreliable.

Instead:

NightShift treats AI systems as bounded workers inside deterministic workflows.

The goal is not artificial software gods.

The goal is trustworthy leverage.

License

Planned:

GPLv3

Rationale:

NightShift is licensed under GPLv3 because AI-assisted software engineering is rapidly becoming dependent on opaque, vendor-controlled tooling. As agent systems become part of the actual software production process, users deserve the freedom to inspect, modify, audit, and reproduce the systems operating on their codebases. GPLv3 helps ensure that improvements to NightShift and its orchestration layer remain part of a transparent, inspectable ecosystem rather than disappearing into proprietary black boxes. The goal is not just open source for its own sake, but preserving user autonomy, local-first experimentation, and the ability to understand how automated systems are making decisions inside increasingly critical engineering workflows.

encourages community contribution
protects local-first ecosystem
aligns with hacker/free software ethos

Contributing

NightShift is intentionally early and experimental.

Good contributions:

safety improvements
pipeline reliability
better artifact systems
better context compaction
local model integrations
tests
docs

Bad contributions:

adding magical autonomy before reliability exists
removing safety boundaries
overcomplicated abstractions before MVP stability

Final Note

AI coding tools are currently optimized for demos.

NightShift is optimized for surviving the night.