Skip to content

Night Agent

An autonomous Claude Code session that runs while you sleep — triages bugs, reviews code, and ships features by reading the GitHub Projects board and delegating to domain specialists.

Overview

┌──────────────────────────────────────────────────────────────────┐
│                     You (before bed)                             │
│   tickets in GitHub Projects "Ready" column                      │
└─────────────────────────────┬────────────────────────────────────┘
                              │  manual trigger or scheduled run
                              ▼
┌──────────────────────────────────────────────────────────────────┐
│              Claude Code session (night agent)                   │
│              system prompt: .claude/agent-prompt.md              │
│              invokes: /night-flow skill                          │
└──────┬───────────────────────────────────────────────────────────┘
       │
       │  runs up to ONE code-producing stage per session
       │
       ├──► Stage 1: Bug Triage     → /bug-triage skill
       ├──► Stage 2: Code Review    → /code-review skill
       ├──► Stage 3: Feature Dev    → /feature-dev skill
       └──► Stage 4: QA             → /qa skill
                 │
                 │  then always runs:
                 ├──► Security scan  → /security-scan skill
                 ├──► Update logs    → docs/agent/agent-log.md
                 ├──► Write vault    → ~/.night-mem/ (persistent memory)
                 └──► Merge & push  → agent/integrated branch
                              │
                              ▼
                    GitHub Projects board updated
                    (Backlog → Ready → In Progress → Done)
                    PR open for your morning review
What Why it matters
One code-producing stage per session Keeps each night's work reviewable and atomic
Orchestrator ≠ implementer /night-flow only does plumbing; specialists do the actual work
GitHub Projects is the queue You manage priorities; the agent just picks up what's Ready
KST 06:00 hard stop Session always ends before you wake up
Persistent vault memory The agent remembers decisions, gotchas, and context across nights

How It Works

Step 1 — Session startup

Claude Code starts
   │
   ├── git checkout main && git status
   ├── python scripts/flow_state.py init   ← creates today's state file
   │         .claude/state/night-flow-YYYY-MM-DD.json
   │
   ├── clone / pull ~/.night-mem vault     ← read prior session notes
   │         INDEX.md + relevant feature notes + last 20 lines of log.md
   │
   ├── check KST time ── if ≥ 06:00 KST → stop immediately
   │
   ├── gh project item-list 1              ← read the work queue
   └── /security-scan (deps mode)          ← pip-audit + npm audit
  • Input: nothing — agent reads its own environment
  • Output: session state initialized, work queue loaded, time gate checked
  • Who does it: /night-flow skill (orchestrator)

Step 2 — Stage selection

State file says which stages already ran today
   │
   ├── any tests failing OR bug items in Ready?   ──► Bug Triage
   ├── unreviewed agent/feat-* branches?          ──► Code Review
   ├── Ready items in work queue?                 ──► Feature Dev
   └── any stage produced commits this session?   ──► QA

Only ONE code-producing stage runs. QA always follows if commits were made.

  • Input: .claude/state/night-flow-{date}.json + GitHub Projects board + git branch list
  • Output: one stage selected and delegated
  • Who does it: /night-flow orchestrator

Step 3 — Stage execution (delegated to specialists)

Orchestrator
   │
   ├── /bug-triage   ──► debugger (opus)        diagnose + fix one bug
   ├── /code-review  ──► code-reviewer (sonnet) append review to log
   ├── /feature-dev  ──► domain sub-agent       implement + commit
   └── /qa           ──► test-engineer (haiku)  run tests + targeted checks

Sub-agents work in isolation on agent/feat-<slug> branches.
They do NOT touch git history or the GitHub Project board.
Stage Specialist Model What it produces
Bug Triage debugger Opus Fix commit on agent/feat-<slug>
Code Review code-reviewer Sonnet Review sections in agent-log.md
Feature Dev domain sub-agent (see table below) Sonnet / Opus Implementation commits
QA test-engineer Haiku PASS/FAIL report

Step 4 — Sub-agent routing (Feature Dev)

/feature-dev reads the ticket → picks the right domain specialist

Ticket touches...          ──► Sub-agent
─────────────────────────────────────────────────────
scraper / DB / scheduler   ──► data-engineer   (sonnet)
ML / sentiment             ──► ml-analyst      (opus)
React / frontend           ──► frontend-engineer (sonnet)
CI / Docker / Makefile     ──► devops-engineer  (sonnet)
auth / security / RLS      ──► security-reviewer (sonnet)
crashes / stack traces     ──► debugger         (opus)

The sub-agent writes code and commits to agent/feat-<slug>. The orchestrator then updates the GitHub Project status and moves to QA.

Step 5 — Post-stage: git + GitHub Projects update

Stage completes
   │
   ├── python scripts/flow_state.py set stages.<name> '{"ran": true}'
   ├── move GitHub Project item: In Progress → Done  (or → Blocked on failure)
   └── if commits produced: run QA stage next

Step 6 — Session wrap-up

All stages done
   │
   ├── Append to docs/agent/agent-log.md  (cumulative history)
   ├── Commit log update
   │
   ├── Vault write (~/.night-mem):
   │     sessions/YYYY-MM-DD.md   ← what happened tonight
   │     features/<name>.md        ← update gotchas + session history
   │     log.md                    ← one-line append
   │     INDEX.md                  ← add row for new session note
   │     git push origin main      ← vault is a separate repo
   │
   └── Merge & push to fintrack:
         git checkout agent/integrated
         git merge --no-ff agent/feat-<slug>
         git push origin agent/integrated
         (never pushes main — PR is left open for your review)

State Machine

GitHub Project item lifecycle:

Backlog ──► Ready ──► In Progress ──► Done
                          │
                          └──► Blocked  (agent stuck, needs human)

Night agent only moves items from Ready onward.
You (or the secretary agent) move items from Backlog → Ready.

Session state (night-flow-{date}.json) tracks stages:

{
  "stages": {
    "bug-triage":   { "ran": false },
    "code-review":  { "ran": false },
    "feature-dev":  { "ran": false },
    "qa":           { "ran": false }
  },
  "security_audit": { "ran": false, "summary": "" }
}

If the session is interrupted (crash, timeout), the next run reads this file and skips completed stages.

Components

.claude/
   ├── agent-prompt.md            ← 3-line system prompt: "run /night-flow"
   └── skills/
         ├── night-flow/          ← orchestrator (sequencing, git, GH Projects)
         ├── bug-triage/          ← stage 1 skill
         ├── code-review/         ← stage 2 skill
         ├── feature-dev/         ← stage 3 skill
         ├── qa/                  ← stage 4 skill
         └── security-scan/       ← runs every session

scripts/
   └── flow_state.py              ← read/write session state JSON

~/.night-mem/                     ← persistent vault (separate git repo)
   ├── INDEX.md
   ├── log.md
   ├── sessions/YYYY-MM-DD.md
   └── features/<name>.md
Component What it does Lives in
agent-prompt.md Minimal system prompt — just invokes /night-flow .claude/agent-prompt.md
night-flow skill Orchestrator: time gate, stage sequencing, git, GH Projects .claude/skills/night-flow/SKILL.md
flow_state.py Read/write today's session state JSON scripts/flow_state.py
Stage skills Do the actual work; return structured results .claude/skills/{stage}/
Sub-agents Domain specialists invoked by /feature-dev .claude/agents/*.md
vault (~/.night-mem) Persistent memory across sessions Separate git repo

Data Flow

You
  │  create / label GitHub Project item as "Ready"
  ▼
GitHub Projects board
  │
  │  night agent reads item list
  ▼
/night-flow (orchestrator)
  │
  │  selects stage → delegates to specialist
  ▼
Sub-agent (e.g. ml-analyst)
  │  writes code → commits to agent/feat-<slug>
  │  returns { status, summary, files_changed }
  ▼
/night-flow
  │  runs QA → moves GH Project item to Done
  │  rebuilds logs → writes vault → merges to agent/integrated → pushes
  ▼
agent/integrated branch on GitHub
  │
  │  (PR open for your morning review)
  ▼
You
  │  review + merge to main
  ▼
main branch

Cost Per Session

Cost depends on which stage runs. Each session runs at most one code-producing stage.

Stage Model Typical tokens (in + out) Estimated cost
Bug Triage Opus 80k in / 20k out ~$2.70
Code Review Sonnet 60k in / 15k out ~$0.41
Feature Dev — data/frontend/devops Sonnet 80k in / 25k out ~$0.62
Feature Dev — ml/sentiment Opus 100k in / 30k out ~$3.75
QA Haiku 30k in / 8k out ~$0.06
Security scan (every session) Haiku 10k in / 3k out ~$0.02

Rough per-session total: - Light session (code review + QA + security): ~$0.50 - Typical session (Sonnet feature dev + QA + security): ~$0.70 - Heavy session (Opus bug triage or ML feature dev + QA + security): ~$2.80

Pricing basis: Opus ($15/MTok in, $75/MTok out), Sonnet ($3/MTok in, $15/MTok out), Haiku ($0.80/MTok in, $4/MTok out). Actual token counts vary with ticket complexity and codebase context loaded.

Key Decisions

Decision Chosen approach Why
One stage per session Hard limit in the orchestrator Keeps commits small and reviewable; reduces risk of a bad session polluting many areas
Orchestrator ≠ implementer Thin /night-flow + specialist skills Specialists have deep domain context; orchestrator stays lightweight and testable
agent/integrated not main Never pushes main directly You review and merge — no surprise pushes to production
KST 06:00 hard stop Time-checked at session start Session always ends before you wake up; no half-finished work in the morning
Vault in a separate repo ~/.night-mem is its own git repo Keeps agent memory out of the codebase; survives repo re-clones
GitHub Projects as queue Not BACKLOG.md Live, visual, shared with the secretary agent; both agents read the same board

What Can Go Wrong

Failure Impact How we handle it
KST 06:00 hit mid-stage Stage exits early, work incomplete Orchestrator commits whatever is done; next session resumes from state file
Sub-agent crashes Feature not implemented Ticket moved to Blocked; noted in docs/agent/agent-log.md for your review
Merge conflict on agent/integrated Some branches not merged Conflict branches left unmerged; push whatever merged cleanly; noted in log
Tests fail in QA FAIL status returned to orchestrator Bug-triage stage prioritized next session; no broken code pushed
Vault push fails Memory not persisted Noted in docs/agent/agent-log.md; session continues — vault write never blocks the fintrack push
gh CLI token missing Can't read/update GH Projects Session exits with clear error; verify GH_TOKEN in .env

Glossary

Term Plain English definition
Night agent The autonomous Claude Code session that runs overnight and does development work on your behalf
Orchestrator The /night-flow skill — it decides what to do and in what order, but doesn't write code itself
Stage skill A focused sub-program for one type of work: bug fixing, code review, feature dev, or QA
Sub-agent A domain specialist (e.g., ml-analyst, frontend-engineer) that the orchestrator delegates to for implementation
agent/feat-<slug> A short-lived git branch where the night agent does its work; merged into agent/integrated at session end
agent/integrated The staging branch where completed work accumulates; you review and merge this to main
Session state file A JSON file at .claude/state/night-flow-YYYY-MM-DD.json that tracks which stages ran — used to resume after crashes
Vault (~/.night-mem) A separate git repo that stores the agent's persistent memory: past session notes, feature gotchas, and a running log
Time gate A check at session start: if it's already 06:00 KST or later, the agent stops without doing any work
KST Korean Standard Time (UTC+9) — the timezone used for the time gate because that's where you are
Ready The GitHub Projects status meaning "this ticket is fully specified and the agent can start"
Blocked The GitHub Projects status the agent sets when it can't complete a ticket and needs human input
Security scan An automatic dependency audit (pip-audit + npm audit) that runs every session regardless of which stage is selected

Last updated: 2026-06-02 · Owner: Michael Ko