Overnight Autonomous Research Agent

What We’re Building

An autonomous research/exploration agent built as a Claude Code skill that runs overnight on a dedicated second computer. It takes a task or research direction, explores broadly and autonomously, logs questions it would normally ask the user (continuing on its best guess instead of blocking), and produces a structured morning report with findings and a prioritized question queue. Designed to maximize use of Claude Pro/Max rate limit allocation during sleeping hours.

The morning debrief is initially markdown-based, with a future goal of a conversational voice interface so the user can review findings and answer questions on a walk.

Why This Approach

Chose a checkpoint-based Claude Code skill + restart wrapper (Approach C) over:

• Bare skill (A): Too fragile for unsupervised overnight runs. No crash/rate-limit recovery.
• Full orchestrator (B): Too much upfront infrastructure. Can evolve toward this later.

The checkpoint state file serves double duty: resilience mechanism + learning log for improving the agent over time.

Key Decisions

• Platform: Claude Code on a dedicated second computer (not cloud). Simplest path, leverages existing subscription and tooling.
• Pacing strategy: Broad exploration over depth. Spread tokens across multiple angles rather than going deep on one thread. User steers depth in morning debrief.
• Convergence behavior: As token/time budget runs low, shift from exploration to synthesis mode. Always produce a usable report, even if exploration is incomplete.
• Question queue pattern: Never block on needing user input. Log the question, note the agent’s best-guess answer, continue on that guess (or explore multiple branches). Questions are ranked by priority/impact in the morning report.
• State machine: state.json tracks branches, findings, questions, decisions, and budget. Agent writes checkpoints after each meaningful step. Enables crash recovery and serves as an audit log.
• Restart wrapper: Simple cron job every 20-30 minutes. Detects if session ended, restarts pointing at existing state.

Permissions Model

Tier	Action
Free	Read any local files on the machine
Free	Write/modify files on the machine
Free	Install software/dependencies
Free	Web research / web search
Free	Sign up for new free accounts/services
Free	Authenticate to existing accounts for read-only access
Ask first	Write actions in authenticated accounts
Ask first	Spend money (future: may get its own wallet)
Never	Send messages as user / impersonate
Never	Delete files outside its workspace

Architecture

Core Components

1. The Skill (/overnight) - agent behavior and exploration loop
2. State File (state.json) - checkpoint/resume backbone
3. Restart Wrapper - cron job for crash/rate-limit recovery
4. Morning Report (report.md) - structured findings + questions

Workspace Structure

overnight-runs/
  YYYY-MM-DD-<topic>/
    state.json          # Checkpoint state
    report.md           # Morning report (generated at end)
    questions.md        # Prioritized question queue
    findings/           # Per-branch exploration notes
      01-topic.md
      02-topic.md
    scratch/            # Working files, downloads, experiments

Agent Loop

1. Read task description + context
2. Generate initial exploration plan (multiple branches)
3. For each branch (breadth-first, paced):
   a. Research / explore / try things
   b. Log findings to findings/ directory
   c. When decision point or uncertainty arises:
      - Log question + best-guess answer to questions queue
      - Continue on best guess (or fork branch)
   d. Write checkpoint to state.json
   e. Check budget - if running low, goto step 4
4. Synthesis mode:
   - Aggregate findings across branches
   - Rank questions by priority/impact
   - Generate morning report
   - Write final state

Example Use Cases

• Marketing strategy for service business: Research competitors, identify channels, draft messaging options, price comparison, generate questions about target audience and budget
• CAD design for welding project: Research approaches, find tutorials, identify software options, sketch design considerations, generate questions about dimensions and materials
• Tax preparation: Read local financial files, research deductions, identify required forms, organize documents, generate questions about specific income/expense categories

Future Enhancements

• Voice debrief interface: Claude mobile app or custom voice app for morning walk-through
• Agent wallet: Small crypto/prepaid budget for autonomous purchases
• Learning from history: Use past overnight-runs to improve exploration strategies
• Cloud migration: Move to always-on cloud infra if usage pattern warrants it
• Multi-night continuity: Chain overnight runs into multi-day research projects

Open Questions

• What’s the exact rate limit reset schedule for the subscription tier being used?
• How should the agent estimate remaining budget mid-session? (Token counting vs time-based heuristic)
• Should the restart wrapper notify (e.g., phone notification) if the agent completes early or encounters a hard failure?

Next Steps

-> /workflows:plan for implementation details - build the skill, state schema, restart wrapper, and morning report template.