🧿 @backtest-kit/sidekick

The fastest way to start a backtest-kit trading bot — but the full-control one. Scaffolds a complete multi-timeframe crypto strategy where every wire (exchange, frames, risk, actions, runner) is editable source in your project: a 4H trend filter + 15m signal generator in Pine Script, partial profit taking, breakeven trailing stops, and risk validation.

📚 Docs · 🌟 Reference implementation · 🐙 GitHub

npx -y @backtest-kit/sidekick my-trading-bot
cd my-trading-bot && npm start

Init vs. Sidekick — pick your level of control

@backtest-kit/cli --init keeps the boilerplate inside the CLI; your repo holds only strategy files. Sidekick is the "eject": it writes the entire wiring — exchange adapter, frames, risk rules, actions, bootstrap, runner — as plain, editable source in your project, with no CLI in the loop and nothing hidden. Choose Sidekick when you want to read and own every line, not just the strategy.

What you get out of the box: a working multi-timeframe Pine Script strategy (4H trend + 15m signals), SL/TP distance risk validation, partial profit taking + breakeven trailing stops, cache utilities and debug scripts, a CLAUDE.md for AI-assisted iteration, and environment config.

• 🚀 Zero config — one command, no setup.
• 📊 Multi-timeframe — 4H trend filter (RSI+MACD+ADX) + 15m entries (EMA crossover + volume spike + momentum).
• 📜 Pine Script v5 — strategies run locally via @backtest-kit/pinets, no TradingView.
• 🛡️ Risk management — SL/TP distance validation, 33/33/34 partial profit, breakeven trailing.
• 🔄 Full lifecycle — scheduled/opened/closed/cancelled event logging.
• 🔌 Binance via CCXT — OHLCV, order-book depth, tick-precise formatting.
• 🕐 Historical frames — bull, sharp-drop, and sideways periods predefined.
• 🎨 Web dashboard — @backtest-kit/ui charting.
• 💾 Crash-safe storage — atomic persistence for backtest and live.

The strategy it scaffolds

Classifies the market regime from three indicators:

| Regime | Condition | |--------|-----------| | AllowLong | ADX > 25, MACD histogram > 0, DI+ > DI−, RSI > 50 | | AllowShort | ADX > 25, MACD histogram < 0, DI− > DI+, RSI < 50 | | AllowBoth | Strong trend, no clear bull/bear regime | | NoTrades | ADX ≤ 25 (weak trend) |

EMA crossover confirmed by volume and momentum:

• Long — EMA(5) crosses above EMA(13), RSI 40–65, price above EMA(50), volume spike (>1.5× MA), positive momentum.
• Short — EMA(5) crosses below EMA(13), RSI 35–60, price below EMA(50), volume spike, negative momentum.
• SL/TP — static 2% / 3% from entry. Signal expiry — 5 bars.

Risk filters: reject signals with SL distance < 0.2% or TP distance < 0.2% (slippage protection); enforce trend alignment (longs rejected in a bear regime, shorts in a bull regime).

Position management: partial profit taking scales out at three levels — 33% at TP3, 33% at TP2, 34% at TP1; when breakeven is reached, the trailing stop is lowered by 3 points.

| Frame | Period | Market note | |-------|--------|-------------| | February2024 | Feb 1–29, 2024 | Bull run | | October2025 | Oct 1–31, 2025 | Sharp drop Oct 9–11 | | November2025 | Nov 1–30, 2025 | Sideways with downtrend | | December2025 | Dec 1–31, 2025 | Sideways, no clear direction |

Generated project structure

Everything below lands as editable source in your project — this is the package's deliverable.

my-trading-bot/
├── src/
│   ├── index.mjs                  # Entry point — loads config, logic, bootstrap
│   ├── main/bootstrap.mjs         # Mode dispatcher (backtest / paper / live)
│   ├── config/
│   │   ├── setup.mjs              # Logger, storage, notifications, UI server
│   │   ├── validate.mjs          # Schema validation for all enums
│   │   ├── params.mjs            # Environment variables (Ollama API key)
│   │   └── ccxt.mjs              # Binance exchange singleton via CCXT
│   ├── logic/
│   │   ├── strategy/main.strategy.mjs    # Main strategy — multi-TF signal logic
│   │   ├── exchange/binance.exchange.mjs # Exchange schema — candles, order book, formatting
│   │   ├── frame/*.frame.mjs             # Backtest time frames (Feb 2024, Oct–Dec 2025)
│   │   ├── risk/sl_distance.risk.mjs     # Stop-loss distance validation (≥0.2%)
│   │   ├── risk/tp_distance.risk.mjs     # Take-profit distance validation (≥0.2%)
│   │   └── action/
│   │       ├── backtest_partial_profit_taking.action.mjs
│   │       ├── backtest_lower_stop_on_breakeven.action.mjs
│   │       └── backtest_position_monitor.action.mjs
│   ├── classes/
│   │   ├── BacktestPartialProfitTakingAction.mjs  # Scale out at 3 TP levels
│   │   ├── BacktestLowerStopOnBreakevenAction.mjs # Trailing stop on breakeven
│   │   └── BacktestPositionMonitorAction.mjs      # Position event logger
│   ├── math/
│   │   ├── timeframe_4h.math.mjs   # 4H trend data — RSI, MACD, ADX, DI+/DI−
│   │   └── timeframe_15m.math.mjs  # 15m signal data — EMA, ATR, volume, momentum
│   ├── enum/                       # String constants for type-safe schema refs
│   └── utils/getArgs.mjs           # CLI argument parser with defaults
├── config/source/
│   ├── timeframe_4h.pine    # Pine Script v5 — Daily Trend Filter (RSI/MACD/ADX)
│   └── timeframe_15m.pine   # Pine Script v5 — Signal Strategy (EMA/ATR/Volume)
├── scripts/
│   ├── run_timeframe_15m.mjs # Standalone 15m Pine Script runner
│   ├── run_timeframe_4h.mjs  # Standalone 4H Pine Script runner
│   └── cache/
│       ├── cache_candles.mjs     # Pre-download OHLCV candles (1m/15m/4h)
│       ├── validate_candles.mjs  # Verify cached candle data integrity
│       └── cache_model.mjs       # Pull Ollama LLM model with progress bar
├── docker/ollama/
│   ├── docker-compose.yaml   # Ollama GPU container setup
│   └── watch.sh              # nvidia-smi monitor
├── CLAUDE.md                 # AI strategy development guide
├── .env                      # Environment variables
└── package.json

CLI options & dependencies

npx -y @backtest-kit/sidekick my-bot   # named project
npx -y @backtest-kit/sidekick .        # current directory (must be empty)

| Package | Purpose | |---------|---------| | backtest-kit | Core backtesting / trading framework | | @backtest-kit/pinets | Pine Script v5 runtime for Node.js | | @backtest-kit/ui | Interactive charting dashboard | | @backtest-kit/ollama | LLM inference integration | | ccxt | Binance exchange connectivity | | functools-kit | singleshot, randomString utilities | | pinolog | File-based structured logging | | openai | OpenAI API client | | ollama | Ollama local LLM client |

🔗 Links

Documentation · GitHub · Reference implementation

🤝 Contribute

Found a bug or want a feature? Open an issue or submit a PR.

📜 License

MIT © tripolskypetr