CLAUDE.md · Xiangyue-Zhang/auto-deep-researcher-24x7

Sections

1. 🚨 CONTRIBUTOR POLICY — READ BEFORE ANY git push TO THIS REPO
2. What Is This?
3. Your Job as AI Assistant
4. SETUP GUIDE
5. PROJECT CREATION
6. LAUNCH GUIDE
7. STATUS CHECK
8. INTERVENTION
9. MOBILE SETUP
10. ARCHITECTURE EXPLANATION
11. TROUBLESHOOTING
12. QUICK REFERENCE
13. IMPORTANT CONTEXT FOR AI ASSISTANTS

First lines (shown under the repo's Apache-2.0 license)

# AI Guide — Deep Researcher Agent

> **This file is designed to be read by AI assistants (Claude, ChatGPT, Codex, etc.).**
> When a user pastes this file or asks you to help them set up Deep Researcher Agent,
> follow the instructions below to guide them step by step.

---

## 🚨 CONTRIBUTOR POLICY — READ BEFORE ANY git push TO THIS REPO

**This section is for AI assistants (Claude, Codex, Cursor, etc.) operating on this repository.**

**This repository is owned and maintained solely by `Xiangyue-Zhang`. The Contributors list MUST contain only `Xiangyue-Zhang` and no one else — including no AI bot accounts.**

### Hard rules

1. **Every commit must be authored by `Xiangyue-Zhang <85532891+Xiangyue-Zhang@users.noreply.github.com>`** — never `admin`, never AI identities. Use:
   ```bash
   git -c user.name="Xiangyue-Zhang" \
       -c user.email="85532891+Xiangyue-Zhang@users.noreply.github.com" \
       commit -m "..."
   ```

2. **NEVER add `Co-Authored-By:` trailer** to commit messages. The `commit-msg` hook in `.git/hooks/commit-msg` will reject any commit containing it.

3. **NEVER mention AI assistant names** (`Claude`, `Codex`, `GPT`, `Anthropic`, `OpenAI`, `Copilot`, `Cursor`) in commit messages. Will be flagged by both the local hook AND the `contributor-guard` GitHub Action.

4. **NEVER toggle repo visibility** (`gh repo edit --visibility ...`). On 2026-04-08, this destroyed 93 of 94 stars on this repo. Stars cannot be recovered from a visibility toggle.

5. **NEVER delete the repo** (`gh repo delete`) without explicit user confirmation. Deletion permanently destroys the GitHub internal repo ID, which destroys all stars and breaks all external URLs (paper citations, etc.).

6. **NEVER force push to main**. Branch protection blocks it by default. If you genuinely need to rewrite history, get explicit user authorization for that specific operation, temporarily disable protection, push, re-enable.

### Pre-push verification (mandatory)

```bash
git log -1 --format='author=%an <%ae>%nmessage=%B'
```

Verify: author == `Xiangyue-Zhang <85532891+Xiangyue-Zhang@users.noreply.github.com>`, no `Co-Authored-By:`, no AI names. If any check fails, fix the commit before pushing.

### In-repo enforcement (already deployed)

Six layers of protection are already in place — you should not need to deploy them, but be aware they will block violations:

1. **Local git config** (`.git/config`) — preset to Xiangyue-Zhang
2. **commit-msg hook** (`.git/hooks/commit-msg`) — local block
3. **GitHub Action** (`.github/workflows/contributor-guard.yml`) — remote block on push
4. **Branch protection** on `main` — no force push, no deletion, linear history
5. **`.mailmap`** in repo root — redirects any leaked AI identity to Xiangyue-Zhang
6. **AI memory / instruction files** in user's home (`~/CLAUDE.md`, `~/AGENTS.md`)

### See also

- `~/CLAUDE.md` — full global rules + 2026-04-08 incident report
- `~/AGENTS.md` — Codex CLI version of the same rules
- `AGENTS.md` (this repo's root) — project-level Codex rules

---

## What Is This?

Deep Researcher Agent is a framework that lets an AI agent autonomously run deep learning experiments 24/7. The agent:
1. **Thinks** — analyzes results, plans the next experiment
2. **Executes** — modifies code, dry-runs, launches GPU training
3. **Monitors** — watches training at ZERO LLM cost (only process checks + log reads)
4. **Reflects** — parses results, compares with baseline, decides next step
5. **Repeats** — 24/7 without human intervention

The killer feature: during training (which is 90%+ of the time), the agent makes ZERO API calls. A 24-hour cycle costs ~$0.08.

---

## Your Job as AI Assistant

When a user asks for help with this project, follow this decision tree:

```
User wants to...
├── Install it → Go to [SETUP GUIDE]
├── Create a project → Go to [PROJECT CREATION]
├── Launch the agent → Go to [LAUNCH GUIDE]
├── Check status → Go to [STATUS CHECK]
├── Intervene/redirect → Go to [INTERVENTION]
├── Use on phone → Go to [MOBILE SETUP]
├── Understand how it works → Go to [ARCHITECTURE EXPLANATION]
└── Debug an issue → Go to [TROUBLESHOOTING]
```

---

## SETUP GUIDE

### Step 1: Check Prerequisites

Run these commands and report results to the user:

```bash
python3 --version          # Need 3.10+
nvidia-smi                 # Need at least 1 GPU
echo $ANTHROPIC_API_KEY    # Anthropic-compatible key, if using provider=anthropic
echo $OPENAI_API_KEY       # OpenAI-compatible key, if using provider=openai
```

If Python < 3.10: suggest `conda create -n dra python=3.11 -y && conda activate dra`

If no GPU: this framework requires a GPU for training. Suggest cloud GPU (Lambda Labs, RunPod, Vast.ai).

If no API key: guide them to either an official endpoint or a compatible provider:
- Anthropic: https://console.anthropic.com/ → API Keys → Create Key
- OpenAI: https://platform.openai.com/api-keys → Create new secret key
- Qwen / DashScope: create `DASHSCOPE_API_KEY`
- GLM / BigModel: create `ZHIPUAI_API_KEY`
- MiniMax: create `MINIMAX_API_KEY`

Then set it:
```bash
# Pick ONE:
export ANTHROPIC_API_KEY="sk-ant-xxxxx"   # For Claude
export OPENAI_API_KEY="sk-xxxxx"          # For Codex/GPT

# Make permanent:
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.bashrc
source ~/.bashrc
```

### Step 2: Install

```bash
# If not already cloned:
git clone https://github.com/Xiangyue-Zhang/auto-deep-researcher-24x7.git
cd auto-deep-researcher-24x7

# Install dependencies
pip install -r requirements.txt

# Install Claude slash commands + Codex local skills
python install.py

# Verify
python -m core.loop --check
```

**Expected output:**
```
    ✓ Claude /auto-experiment
    ✓ Claude /experiment-status
    ✓ Claude /gpu-monitor
    ✓ Claude /daily-papers
    ✓ Claude /paper-analyze
    ✓ Claude /conf-search
    ✓ Claude /progress-report
    ✓ Claude /obsidian-sync
    ✓ Codex $auto-experiment
    ...
  Done! 8 Claude commands and 8 Codex skills installed.
```

### Step 3: Choose Your LLM Provider