Understand every file and folder in your BlaveClaw workspace.
workspace/
├── strategies/ # your strategies
├── examples/ # reference implementations
├── lib/ # shared library
├── manager/ # portfolio management system
├── cache/ # API data cache (auto-generated)
├── references/ # guides for strategy code & deployment
└── AGENTS.md # bot behavior rulesEach strategy lives in its own subfolder. The bot runs strategy.py on a cron schedule and writes the output files automatically.
strategies/
└── my_strategy/
├── strategy.py # strategy logic
├── scan.py # parameter scan (optional)
├── stats.json # backtest results + daily returns
├── state.json # live position state
├── pnl.png # equity curve chart
└── orders.jsonl # order logAll shared utilities live in lib/. Import from here — never duplicate code in strategy files.
| File | Purpose |
|---|---|
runner.py | Unified backtest & live runner (Type A and C) |
data.py | All data fetchers — kline, alpha indicators, Taiwan stocks, futures |
execute.py | Live state management: load/save/update position, order log |
pnl.py | Write daily returns to stats.json; load all strategies for manager |
portfolio.py | Aggregate target positions, compute order diff, reconcile |
strategy.py | Vol targeting helpers: add_realized_vol, apply_vol_scaling |
analysis.py | PnL charts, regime analysis, slippage, random B&H benchmark |
param_scan.py | 2D parameter scan: percentile_thresholds, scan_grid, find_plateau, plot_heatmap |
validation.py | Monte Carlo Permutation Test (mcpt) for statistical significance |
notify.py | Telegram sender: make_sender(), send_text(), send_photo() |
The manager/ folder handles multi-strategy portfolio optimization and order reconciliation. Do not delete any file here when removing individual strategies.
| File | Purpose |
|---|---|
manager.py | Reads all strategies' stats.json, finds weights that maximize portfolio slope/std, writes optimal weights + leverage to portfolio_config.json.Run: python3 manager/manager.py --target-vol 0.30 |
reconciler.py | Polls every 5 s; detects when a strategy's state.json changes, then computes target positions (with leverage) and places orders on the exchange.Run: python3 manager/reconciler.py |
portfolio_config.json | Written by manager.py. Contains weights, leverage, and target/actual volatility. |
leverage = target_vol / ann_volatility so the portfolio's realized risk matches your target (e.g. 30% annual vol). The reconciler multiplies all position sizes by this factor when placing orders.strategy.py ──► state.json ──────────┐
(cron) stats.json ├──► reconciler.py ──► exchange
manager.py ──► portfolio_config.json ┘The reconciler needs both sources to compute order size: target = account_value × leverage × weight × position
