Daedalus

In Greek mythology, Daedalus was the master craftsman who built autonomous machines — bronze giants that guarded Crete, animated statues that could move on their own. He was, in a sense, the first AI engineer: building things that worked tirelessly without supervision.

Daedalus is a framework for running Claude Code as a fully autonomous agent via cron. It gives Claude persistent memory, task management, and session handoff — so it can work on your project continuously across sessions, days, and weeks without losing context.

Why Daedalus?

Claude Code is powerful in interactive mode, but what if it could work while you sleep? Daedalus makes that possible:

• Checkpoint-based session handoff — each session writes a "save game" that the next session resumes from. No context is ever lost.
• File-based state — all state lives in markdown files. Human-readable, git-trackable, and editable by both you and Claude.
• Full autonomy — Claude decides what to work on, prioritizes tasks, and self-directs. Or you can drop suggestions and let Claude evaluate them.
• Human-in-the-loop — a questions file + push notifications for when Claude needs your input. Non-blocking questions let Claude continue other work.
• Persistent memory — a lessons-learned file accumulates knowledge across sessions. Claude gets smarter about your project over time.
• PID management — prevents overlapping sessions, detects and kills stale processes automatically.

Quick Start

1. Clone and configure

git clone https://github.com/your-user/daedalus.git
cd daedalus
chmod +x scripts/*.sh scripts/*.py

2. Adapt it to your project

This is the most important step. The best way to set up Daedalus is to describe your project to Claude and let it help you fill in the config:

claude

Then tell Claude:

"I want to use Daedalus to autonomously work on [your project]. Help me fill in CLAUDE.md with project context, seed tasks.md with initial tasks, and configure daily.md for my workflow."

See ADAPTING.md for a detailed guide.

3. Set environment variables

# Add to /etc/environment for system-wide access (including cron)
PUSHOVER_USER_KEY="your-user-key"
PUSHOVER_APP_TOKEN="your-app-token"

(Pushover is optional but recommended. Without it, Claude can't notify you when it has questions.)

4. Test manually

./scripts/run-daily.sh
# Watch the session live:
tail -f logs/daily-*.log

5. Add to cron

crontab -e

# Run every 6 hours
0 */6 * * * /path/to/daedalus/scripts/run-daily.sh

# Clean up old logs weekly
0 0 * * 0 /path/to/daedalus/scripts/rotate-logs.sh 30

How It Works

cron triggers run-daily.sh
  → checks for previous session (skip if active, kill if stale)
  → reads prompts/daily.md
  → claude -p (non-interactive, autonomous)
    → reads checkpoint.md (resume from last session)
    → reads CLAUDE.md (project rules + context)
    → reads tasks.md (what to work on)
    → reads worklog.md (history)
    → reads questions.md (check for human answers)
    → reads lessons-learned.md (accumulated knowledge)
    → does the work, checkpointing at every step
    → commits & pushes to working branch
    → updates all state files
    → reprioritizes and picks next task
  → output captured in logs/
  → session ends at max-turns or rate limit
  → next cron invocation resumes from checkpoint

Project Structure

daedalus/
├── CLAUDE.md                  # Project instructions for Claude (you customize this)
├── ADAPTING.md                # Guide: how to make Daedalus yours
├── .claude/
│   ├── checkpoint.md          # Living session state ("save game")
│   ├── tasks.md               # Task tracker (source of truth)
│   ├── worklog.md             # Session history (append-only)
│   ├── questions.md           # Human interaction channel
│   └── lessons-learned.md     # Persistent knowledge base
├── prompts/
│   ├── daily.md               # Default autonomous prompt (customize this)
│   └── review.md              # Example: code review prompt
├── scripts/
│   ├── run-daily.sh           # Cron wrapper (PID mgmt + stale detection)
│   ├── run-prompt.sh          # Run any prompt file on-demand
│   ├── notify.py              # Push notifications (Pushover)
│   └── rotate-logs.sh         # Log cleanup
└── logs/                      # Session output (gitignored)

State Files

File	Purpose	Update Pattern
checkpoint.md	Living session state — where Claude left off	Overwritten at every step
tasks.md	Task tracker — what to work on	Updated on status changes
worklog.md	Session history — what happened	Append-only
questions.md	Human interaction — questions & answers	Updated by both sides
lessons-learned.md	Persistent memory — accumulated knowledge	Append-only, never cleared

Key Concepts

The Checkpoint System

Every time Claude does something meaningful (writes a file, runs a test, makes a decision), it overwrites checkpoint.md with its current state. If the session dies — rate limit, crash, max turns — the next session reads the checkpoint and picks up exactly where the last one left off. Think of it as a save game.

Task Lifecycle

Proposed → Backlog → In Progress → Done → Archive

• Proposed: Ideas discovered by Claude or suggested by you ([You] tag)
• Backlog: Accepted and ready for implementation
• In Progress: Currently being worked on
• Done: Completed today (rotated to Archive the next day)

Human Interaction

When Claude needs your input, it adds a question to questions.md and (optionally) sends a push notification. Questions are either:

• 🛑 Blocking — work is stopped until you respond
• 💬 Non-blocking — Claude continues other work while waiting

You answer by editing the file. Next session, Claude processes your response.

Lessons Learned

This file is Claude's long-term memory. It records things like API quirks, debugging solutions, infrastructure details, things that didn't work. Each session consults it before attempting unfamiliar operations — past Claude may have already solved the problem.

Notifications

Daedalus uses Pushover for notifications:

Type	When	Priority
blocking	Work is stopped, needs your response	🔴 High
question	Non-blocking question, Claude continues	🟡 Normal
resolved	Claude figured out a previous question	🟢 Low
info	Milestone reached, task completed	⚪ Lowest
error	Unexpected failure	🔴 High

Configuration

Max Turns

MAX_TURNS in run-daily.sh controls how many actions Claude can take per session. Default is 200. Each "turn" is roughly one tool use (file read, write, terminal command). The startup sequence costs ~10 turns, so low values leave little room for work.

Cron Frequency

Set based on your API plan's rate limit reset window. If limits reset every 5 hours, running every 6 hours ensures each session gets a full quota.

Stale Detection

If a previous session's process is still running but hasn't updated the checkpoint in STALE_THRESHOLD_MINUTES (default: 30), it's considered stale and killed. This prevents zombie sessions from blocking new ones.

Design Philosophy

1. Files over databases — everything is a markdown file. You can read it, edit it, git diff it, and understand it without any tooling.
2. Autonomy with guardrails — Claude decides what to work on, but operates within rules you define in CLAUDE.md.
3. Graceful degradation — rate limits, crashes, and errors are expected. The checkpoint system means nothing is ever lost.
4. Human escalation — Claude should never be stuck. If it can't proceed, it asks you and moves on to other work.
5. Cumulative intelligence — every session makes Claude smarter about your project through lessons-learned.

License

MIT