# π§Ώ @backtest-kit/sidekick
> The fastest way to start a [backtest-kit](https://www.npmjs.com/package/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.
[](https://deepwiki.com/tripolskypetr/backtest-kit)
[](https://npmjs.org/package/@backtest-kit/sidekick)
[](https://github.com/tripolskypetr/backtest-kit/blob/master/LICENSE)
π **[Docs](https://backtest-kit.github.io/documents/article_07_ai_news_trading_signals.html)** Β· π **[Reference implementation](https://github.com/tripolskypetr/backtest-kit/tree/master/example)** Β· π **[GitHub](https://github.com/tripolskypetr/backtest-kit)**
```bash
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
4H trend filter (timeframe_4h.pine)
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) |
15m signal generator (timeframe_15m.pine)
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 & position management
**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.
Backtest frames
| 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.
Full tree
```
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
```bash
npx -y @backtest-kit/sidekick my-bot # named project
npx -y @backtest-kit/sidekick . # current directory (must be empty)
```
Dependencies installed
| Package | Purpose |
|---------|---------|
| [backtest-kit](https://www.npmjs.com/package/backtest-kit) | Core backtesting / trading framework |
| [@backtest-kit/pinets](https://www.npmjs.com/package/@backtest-kit/pinets) | Pine Script v5 runtime for Node.js |
| [@backtest-kit/ui](https://www.npmjs.com/package/@backtest-kit/ui) | Interactive charting dashboard |
| [@backtest-kit/ollama](https://www.npmjs.com/package/@backtest-kit/ollama) | LLM inference integration |
| [ccxt](https://github.com/ccxt/ccxt) | Binance exchange connectivity |
| [functools-kit](https://www.npmjs.com/package/functools-kit) | `singleshot`, `randomString` utilities |
| [pinolog](https://www.npmjs.com/package/pinolog) | File-based structured logging |
| [openai](https://www.npmjs.com/package/openai) | OpenAI API client |
| [ollama](https://www.npmjs.com/package/ollama) | Ollama local LLM client |
## π Links
[Documentation](https://backtest-kit.github.io/documents/article_07_ai_news_trading_signals.html) Β· [GitHub](https://github.com/tripolskypetr/backtest-kit) Β· [Reference implementation](https://github.com/tripolskypetr/backtest-kit/tree/master/example)
## π€ Contribute
Found a bug or want a feature? [Open an issue](https://github.com/tripolskypetr/backtest-kit/issues) or submit a PR.
## π License
MIT Β© [tripolskypetr](https://github.com/tripolskypetr)