# Claude Code Usage Notes

## Golden Rule
**User gives task → spawn sub-agent → sub-agent runs Claude Code → sub-agent verifies → user gets ONE summary message. No play-by-play.**

## How to Use Claude Code

### Via Sub-Agent (preferred for complex tasks)
```
sessions_spawn with task like:
"Run Claude Code to [task]. Working dir: /path/to/project.
After Claude Code finishes, verify the changes compile and make sense.
If not, run Claude Code again with fixes. Commit and push when done."
```

### Direct (simple tasks only)
```bash
cd /path/to/project
claude -p "task description" --allowedTools "Edit,Write,Bash"
```

## Key Facts
- **Default model**: Opus 4.6 (no override needed)
- **Auth**: OAuth login already completed, no API key needed
- **Allowed tools**: Always pass `--allowedTools "Edit,Write,Bash"`
- **Timeout**: Claude Code can take 5-20 minutes for complex tasks. Don't micromanage.
- **Hanging**: Sometimes streams hang after ~10-15 min. Sub-agent can detect this and retry.
- **PTY mode**: Use `pty=true` when running via exec

## Sub-Agent Task Template
```
Run Claude Code CLI in /path/to/project to do the following:

[TASK DESCRIPTION]

Steps:
1. Run: cd /path/to/project && claude -p "[task]" --allowedTools "Edit,Write,Bash"
2. Wait for completion (up to 20 min, check if process is still alive periodically)
3. If it hangs (no file changes for 10+ min), kill and retry once
4. After completion, verify: go build / npm build / etc
5. If build fails, run Claude Code again with the error
6. Commit and push when everything works
7. Report summary of all changes made
```

## Anti-Patterns
- ❌ Polling every 30 seconds and reporting progress
- ❌ Sending WhatsApp messages during the process
- ❌ Reading every file before/after to narrate changes
- ✅ Fire and forget, verify at end, report once