Quick Start

1. Install

git clone https://github.com/judyailab/ai-night-shift.git
cd ai-night-shift
bash install.sh

2. Configure

# Copy the example config and edit your settings
cp config.env.example config.env
nano config.env

# Customize the night shift prompt
nano claude-code/prompt_template.txt

3. Test

# Run a single round to verify setup
bash claude-code/night_shift.sh --max-rounds 1

4. Schedule

# The installer adds cron jobs automatically, or set up manually:
crontab -e
# Add: 0 1 * * * cd ~/ai-night-shift && bash claude-code/wrapper.sh

Modules

| Module | Description | Docs | |--------|-------------|------| | Claude Code | Continuous developer sessions | README | | Gemini | Periodic patrol and research | README | | OpenClaw | Heartbeat coordinator pattern | README | | Protocols | Inter-agent communication | README | | Plugins | Extensible pre/post/task hooks | README | | Dashboard | Visual monitoring interface | Open dashboard/index.html | | Templates | Prompt templates by use case | 4 templates included |

Prompt Templates

| Template | Use Case | |----------|----------| | development.txt | Coding, testing, debugging | | research.txt | Data gathering, analysis | | content.txt | Writing, translation, SEO | | maintenance.txt | System admin, monitoring |

Plugin System

Extend your night shift with pre-built or custom plugins:

# Enable a plugin
ln -s plugins/examples/system_health.sh plugins/enabled/

# List all plugins
bash plugins/plugin_loader.sh --list

Built-in plugins: System Health, Backup, Git Commit Summary, Morning Report, De-Sloppify

Dashboard

Open dashboard/index.html in a browser. Drag and drop your report files to visualize:

• Agent activity and status
• Round-by-round timeline
• Night chat messages
• System health metrics

Agent Adapters

The night shift runner is agent-agnostic. Switch agents with one config change:

# In config.env
AGENT_ADAPTER=claude-code   # default
# AGENT_ADAPTER=codex-cli   # OpenAI Codex CLI
# AGENT_ADAPTER=aider       # Aider
# AGENT_ADAPTER=custom      # Your own (copy adapters/custom.sh)

Or via CLI flag:

bash claude-code/night_shift.sh --adapter codex-cli

Create your own adapter: copy adapters/custom.sh, implement 5 functions, done. See adapters/ for details.

Prompt Design for Autonomy

The most common pitfall: your agent stops mid-task and waits for confirmation that never comes.

All included templates have an Autonomy Rules block that prevents this:

• Never ask for confirmation — decide and execute
• Never wait for user input — choose the safest option and proceed
• Never use interactive commands
• If stuck 3 times, log and move on

See docs/advanced.md for the full prompt design guide.

Advanced Features

• Completion Signal — agents can say "I'm done" to end the shift early
• Shared Task Notes — cross-round context memory bridge
• De-Sloppify Pattern — separate cleanup pass for code quality
• Anti-Pattern Guide — avoid common autonomous loop pitfalls

Requirements

• Bash 4+ and Python 3.6+
• At least one AI CLI tool:
  • Claude Code (npm install -g @anthropic-ai/claude-code)
  • Gemini CLI (npm install -g @google/gemini-cli)
• A Linux/macOS system with cron and timeout (GNU coreutils; macOS: brew install coreutils)

Safety & Security

• PID locking prevents concurrent runs
• Time windows ensure shifts end on schedule
• Rate limit handling with automatic retry
• No secrets in code — all credentials via environment variables
• Append-only communication — agents can't delete each other's messages
• Plugin timeout — max 5 minutes per plugin execution

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT — Judy AI Lab

Built with real-world experience from 30+ autonomous night shifts. If your AI works harder while you sleep, you're doing it right. 🌙