QuantLab

An agentic crypto-research harness. Ask questions in plain English; a coding agent writes ClickHouse SQL, runs it across your candle warehouse — thousands of rows by default, millions once you load minute bars — and answers in milliseconds. Built on Pi (a minimal, hackable terminal agent), ClickHouse (the speed), and Claude Sonnet (the brain).

It's read-only research — backtests, volatility, returns, drawdowns. Not a trading bot, not financial advice.

free APIs ──ingest.py──▶ ClickHouse (Docker) ◀─clickhouse_query─ Pi agent ──▶ Claude Sonnet
(Kraken/Binance/CoinGecko)      quantlab.ohlcv    (TS extension)      (AGENTS.md persona)

The agent's tool is a TypeScript Pi extension; everything else — ingest, the tools/ch.py fallback — is Python.

Why it's interesting

• Why ClickHouse, not a notebook? An agent doesn't ask once — to test one idea it fires a dozen queries (filter, aggregate, backtest, refine). At seconds per query the loop stalls; at milliseconds it explores freely. ClickHouse scans millions of candles per query in single-digit ms, which is what makes an agentic analytics loop feel alive.
• Pi has no built-in MCP — by design. Its docs say "No MCP. Build CLI tools with READMEs, or build an extension." So we built a native TypeScript extension (.pi/extensions/clickhouse/, heavily commented) that registers a first-class clickhouse_query tool — no protocol, no server, talking straight to ClickHouse. A plain Python tools/ch.py is included as a no-Node fallback, and everything else in the repo (ingest, the fallback) is Python.
• ClickHouse does the heavy lifting in SQL. A whole SMA-crossover backtest is a windowed query; the agent never pulls rows into Python to loop over them.

Prerequisites

• Docker (for ClickHouse)
• Python 3.10+
• Node.js 18+ (only to run the clickhouse_query TypeScript extension)
• An Anthropic API key
• Pi: curl -fsSL https://pi.dev/install.sh | sh (or npm i -g @earendil-works/pi-coding-agent)

Quickstart

git clone https://github.com/maruthiprithivi/quantlab_harness.git quantlab && cd quantlab
cp .env.example .env                  # ClickHouse vars for ingest.py/ch.py (auto-loaded)

make setup                            # ClickHouse up + Python deps + the Pi extension
make seed                             # load free market data (Kraken daily, ~15 coins, no key)
make smoke                            # sanity check: candles per symbol; fails if empty

export ANTHROPIC_API_KEY=sk-ant-...   # give Pi the key (or run `pi` then `/login`)
pi                                    # runs in this repo: AGENTS.md + extension auto-load
#  in Pi: press Ctrl+L (/model), pick the latest Claude Sonnet, then ask away

For the big "rows scanned" numbers, seed deeper history / minute bars:

make seed ARGS="--source binance --intervals 1d 1h"
make seed ARGS="--source binance --intervals 1m --symbols BTC ETH SOL"   # millions of rows

No make? The targets just wrap docker compose up -d --wait, python3 -m pip install -r requirements.txt, (cd .pi/extensions/clickhouse && npm install), and python3 ingest.py (the Python tools auto-load .env).

Then try the questions in demo/prompts.md, starting with:

"What's in the warehouse — how many candles per symbol, and what date range?"

How the harness is wired

Piece	What it does
AGENTS.md	Auto-loaded by Pi from the repo dir. Defines the quant-analyst persona, the ohlcv schema, and ClickHouse query craft.
.pi/extensions/clickhouse/	Native TypeScript extension (well-commented) that registers the read-only clickhouse_query tool (TypeBox params, talks to ClickHouse via @clickhouse/client with readonly=2). Auto-discovered from .pi/extensions/; edit it and /reload live.
tools/ch.py	Read-only Python fallback for a no-Node setup — same SQL-and-[speed] behaviour, called via Pi's bash tool.
skills/clickhouse-quant/	The same query craft as a portable Pi skill — copy to ~/.pi/agent/skills/ and /reload to use it in any project (then /skill:clickhouse-quant).
.pi/settings.json	Project Pi settings (Anthropic provider, dark theme).

Data sources (all free, no key)

Source	Notes
kraken (default)	Daily/hourly candles, ~720 per pair per interval. Reliable everywhere.
binance	Full history + 1m granularity → millions of rows. Geo-blocked in some regions/CI; works across most of APAC including Singapore.
coingecko	Coarse 4-day candles (free-tier auto-granularity, ignores --intervals); no volume on the OHLC endpoint. A fallback — kraken/binance cover the real demos.

Switch with --source and choose granularity with --intervals 1d 1h 1m.

Scaling the "rows scanned" number

The speed line is dramatic at any size, but for a jaw-drop load 1-minute candles:

make seed ARGS="--source binance --intervals 1m --symbols BTC ETH SOL"

That's millions of rows; queries still return in single-digit milliseconds.

Safety / scope

QuantLab is for historical research and backtesting only. The agent's query tools (the clickhouse_query extension and tools/ch.py) connect with ClickHouse's readonly=2 setting, so they can read but cannot INSERT/ALTER/DROP — the read-only guarantee is enforced by the engine, not just by the prompt. The loader (ingest.py, run by you) is the only writer. The local ClickHouse runs unauthenticated and bound to 127.0.0.1 — fine for a laptop, not a shared host.

It does not place trades, connect to any exchange account, or give financial advice or price predictions. Treat all output as analysis of past data, with the usual caveats (no fees, no slippage, limited history).

Make it yours

It's a coding agent — add a native tool by editing the TypeScript extension at .pi/extensions/clickhouse/index.ts and /reload, or write a Python helper (an ASCII price chart, a second data source) for the agent to call via bash. Bundle the extension, tools/, skills/, and AGENTS.md as a Pi package to share with your team.

Credits

Pi · ClickHouse · ClickHouse also runs free public on-chain analytics at CryptoHouse if you'd rather point an agent at real Solana/Ethereum data. MIT licensed.