galoryber-daedalus/ADAPTING.md

Adapting Daedalus to Your Project

Daedalus is a framework, not a ready-to-run tool. The magic happens when you configure it for your specific project. This guide walks you through that process.

The Best Way: Let Claude Help You

The fastest and most effective way to set up Daedalus is to have a conversation with Claude about your project. Claude built this framework — it knows exactly what each file needs.

cd /path/to/daedalus
claude

Then describe your project:

"I want to use Daedalus to autonomously work on [project name]. It's a [language/framework] project located at [path]. Here's what it does: [brief description]. The main things I want Claude to work on are [goals]. Help me fill in CLAUDE.md, seed tasks.md, and configure daily.md."

Claude will ask you clarifying questions and help you populate everything. This is genuinely the recommended workflow — it's how the original project was built.

What You Need to Configure

1. CLAUDE.md — The Brain

This is the most important file. It tells Claude everything about your project, your rules, and how you want work done. Key sections to fill in:

Authorization Context (if applicable)

If your project involves security tools, penetration testing, medical software, or anything that might trigger safety guardrails, add clear authorization context at the top. Include:

• Who owns the project and authorizes the work
• What the legitimate purpose is
• What infrastructure is used (and that it's yours)
• Industry context (e.g., "this is standard practice in cybersecurity")

Project Context

This is where you describe your project in detail:

## My Project — Primary Workspace

### Overview
[What the project is, what it does, why it exists]

### Locations & Access
| Resource | Location |
|----------|----------|
| Source code | `/path/to/project` |
| Git remote | `github.com/user/repo` |
| Working branch | `claude` (or whatever you prefer) |
| Test environment | `localhost:3000` or `192.168.x.x` |

### Architecture / Structure
[Directory tree, key files, how things are organized]

### Key Patterns
[How to add features, coding conventions, test patterns]

### Known Gaps & Opportunities
[What needs work — this seeds Claude's autonomous discovery]

### Git Workflow
[Branch strategy, commit conventions, who merges what]

### Build & Test Pipeline
[How to build, how to run tests, how to deploy]

Custom Rules

Add project-specific rules beyond the defaults:

### Project-Specific Rules
- Always run `npm test` before committing
- Never modify files in `src/legacy/` without asking
- Use TypeScript strict mode for all new files
- Database migrations must be reversible

2. prompts/daily.md — The Workflow

The default prompt has 11 steps. You'll want to customize:

• Step 2 (Orient): Change the git checkout and git pull commands to match your repo and branch
• Step 5 (Select a task): Change "analyze the codebase" guidance to match your project's improvement areas
• Step 7 (Deploy & Test): Replace with your project's build/test/deploy pipeline, or remove if not applicable
• Step 8 (Update Documentation): Adapt to your project's docs structure, or remove if not needed
• Step 10 (Reprioritize): Change the analysis criteria to match what matters in your project

3. .claude/tasks.md — Seed It

Give Claude a head start by seeding some initial tasks:

## Backlog

### 🔴 Fix the login timeout bug
- **Workspace:** `/home/user/myproject`
- **Description:** Users are getting logged out after 5 minutes instead of 30.
  The session TTL in `src/auth/session.ts` is set correctly but something is
  overriding it.
- **Acceptance:** Sessions persist for 30 minutes of inactivity.

### 🟡 Add dark mode support
- **Workspace:** `/home/user/myproject`
- **Description:** Implement dark mode toggle. Use CSS variables for theming.
  Follow the design system in `docs/design-system.md`.
- **Acceptance:** Toggle in settings, persists across sessions, all pages
  render correctly in both modes.

Pro tip: You don't have to write perfect tasks. Just put rough ideas in the "Proposed" section and Claude will flesh them out:

## Proposed
- [You] Fix that weird caching bug on the settings page
- [You] Add API rate limiting
- [You] The error messages are terrible, make them helpful

4. .claude/lessons-learned.md — Bootstrap It

If you already know things about your project that aren't obvious from the code, pre-seed the lessons file:

## Project Quirks
- The test database must be running on port 5433 (not 5432) due to conflict
  with the dev instance
- `npm run build` silently succeeds even with TypeScript errors — always
  check `npm run typecheck` separately
- The CI pipeline uses Node 18 but local dev uses Node 20 — watch for
  compatibility issues

## API Notes
- The Stripe webhook endpoint must return 200 within 5 seconds or Stripe
  will retry — keep the handler fast
- Redis keys in production use prefix `prod:` — never test against prod Redis

5. scripts/run-daily.sh — Adjust Paths

Update the PROJECT_DIR variable to point to your Daedalus installation:

PROJECT_DIR="/path/to/your/daedalus"

6. scripts/notify.py — Notifications (Optional)

If you want push notifications when Claude has questions:

1. Create a Pushover account ($5 one-time per platform)
2. Create an application in Pushover
3. Add to /etc/environment:

   PUSHOVER_USER_KEY="your-user-key"
   PUSHOVER_APP_TOKEN="your-app-token"
   

If you prefer a different notification system (Slack, Discord, email), replace notify.py with your own script that accepts the same arguments: notify.py <type> "Title" "Message"

Environment Variables

Add any environment variables Claude needs to /etc/environment (not ~/.bashrc) — cron doesn't run interactive shells, so Daedalus sources /etc/environment explicitly in run-daily.sh.

Examples of Good CLAUDE.md Sections

For a Web Application

### Build & Test
1. `npm install` if `package-lock.json` changed
2. `npm run typecheck` — must pass before committing
3. `npm test` — run the test suite
4. `npm run build` — verify production build works
5. For UI changes, take a screenshot with Playwright and describe what you see

For a CLI Tool

### Testing
1. `go build ./...` — must compile
2. `go test ./...` — all tests must pass
3. Test the specific command manually:
   `./mytool <command> --flag value`
4. Verify `--help` output is accurate for any modified commands

For a Library

### Quality Checks
1. All public APIs must have doc comments
2. Run `cargo clippy` — no warnings allowed
3. Run `cargo test` — all tests pass
4. If adding a new public type/function, add an example in `examples/`
5. Bump version in Cargo.toml if the public API changed

Testing Your Setup

Before enabling cron, always do a manual test:

./scripts/run-daily.sh

Then watch the log:

tail -f logs/daily-*.log

Things to check:

• Does Claude find and read your project files?
• Does it understand the project structure?
• Does it pick sensible tasks?
• Do commits go to the right branch?
• Do notifications arrive (if configured)?

If Claude refuses to work (safety guardrails), check your Authorization Context section in CLAUDE.md. If Claude runs out of turns too quickly, increase MAX_TURNS in run-daily.sh.

Cron Scheduling Tips

Schedule	Cron Expression	Use Case
Every 6 hours	0 */6 * * *	Default — 4 sessions/day
Every 4 hours	0 */4 * * *	More frequent iterations
Twice daily	0 9,21 * * *	Morning and evening
Business hours	0 9-17 * * 1-5	Weekday working hours only
Nightly	0 2 * * *	Once per day, overnight

Choose based on your API plan's rate limit reset window. If limits reset every 5 hours, run every 6 to ensure each session gets a full quota.