# CryptoClaw Bot — Agent Instructions

## CRITICAL: Backtest Safety Rules

### NEVER run backtests inline
Running `python3 run_btc_backtest.py` or importing `BacktestEngine` directly in
a bot conversation will block the agent thread for 5-30+ minutes and may time out
or crash. **Do not do this.**

### Use the background wrapper instead
Always use the provided scripts to run backtests safely:

#### Start a backtest
```bash
/var/www/html/crpytotradingbot/run_backtest_bg.sh [OPTIONS]
```
Options:
- `--dataset=6month` (default) or `--dataset=5year`
- `--max-rows=500000` (default) — set to 0 for unlimited
- `--tf=5min` (default) — candle timeframe

The script prints a `RUN_ID` (e.g. `20260208_231500`) and exits immediately.
The backtest runs in the background via `nohup`.

#### Check backtest status
```bash
/var/www/html/crpytotradingbot/check_backtest.sh latest
# or
/var/www/html/crpytotradingbot/check_backtest.sh <RUN_ID>
```
Status will be one of: `running`, `complete`, `failed`.
When complete, full results are in `/var/www/html/crpytotradingbot/results/result_<RUN_ID>.json`.

#### Read results
```bash
cat /var/www/html/crpytotradingbot/results/result_<RUN_ID>.json
# or for the summary output:
cat /var/www/html/crpytotradingbot/results/output_<RUN_ID>.txt
```

### Typical bot workflow
1. User asks for a backtest
2. Run `run_backtest_bg.sh` with appropriate args
3. Tell the user: "Backtest started (RUN_ID: ...). I'll check on it shortly."
4. Poll `check_backtest.sh latest` after ~60 seconds
5. Once status = `complete`, read the result JSON and summarize for the user
6. If status = `failed`, read the output file for error details

### Safe inline operations
These are fine to run directly (they are fast):
- Reading settings: `python3 -c "import settings; print(vars(settings))"`
- Checking CSV row counts: `wc -l BTCUSD_PAST6MONTHS.csv`
- Listing past results: `ls -lt results/`
- Reading existing result files

### Forbidden inline operations
- `python3 run_btc_backtest.py` — NEVER run directly
- `python3 -c "from backtest import BacktestEngine; ..."` with `.run()` — NEVER
- Any long-running Python that processes the full CSV — NEVER
- `python3 run_aggressive_sweep.py` or `run_hybrid_sweep.py` — NEVER inline

## File Layout
```
/var/www/html/crpytotradingbot/
├── run_backtest_bg.sh      # Background backtest launcher
├── check_backtest.sh       # Status checker
├── results/                # All backtest outputs
│   ├── status_*.txt        # Status files (running/complete/failed)
│   ├── output_*.txt        # Stdout/stderr capture
│   └── result_*.json       # Structured results
├── run_btc_backtest.py     # Core backtest entry point (DO NOT run inline)
├── backtest.py             # BacktestEngine class
├── settings.py             # Active trading settings
├── BTCUSD_PAST6MONTHS.csv  # 6-month tick data
└── BTCUSD.csv              # 5-year tick data
```