Getting started
demo_trend and the demo_volume scanner exist to demonstrate the interface and give
quantred demo something to run. Neither is an edge, and a bare install ships nothing
else. Your own work belongs in a private package — see
your own strategies.
From nothing to a real research result with Claude driving it, in six steps. Each one works on its own, and you can stop at any of them.
You need a terminal. Steps 1–2 need nothing else — no keys, no account, no network.
1. Install it
uv tool install 'quantred[mcp,viz]'
No uv? Install it first,
or use python -m pip install 'quantred[mcp,viz]' in a virtual environment. The two extras
are the MCP server (step 5) and charts in HTML reports (step 4); the demo needs neither, and
optional extras has the rest. This gives you a quantred command.
quantred --version
That prints the version, which copy is running, and — worth noting now — where its
state lives. An installed copy keeps its research journal, trial history, and cache
in ~/.tradeflow.
2. See it work, with no keys at all
quantred demo
This runs the entire pipeline on synthetic data: it backtests every bundled
strategy, walk-forward validates demo_trend (fixed in advance, not chosen by its
in-sample result), and refuses to promote it.
The refusal is the point. The synthetic series is a seeded random walk with no edge in it, and a strategy that looks profitable in-sample gets called noise out-of-sample. If that had not happened, the tool would be broken. Watching it work on data you know is worthless is the fastest way to understand what it is for.
Nothing so far touched the network or needed an account.
3. Get keys and add them
Real market data needs free Alpaca paper-trading credentials:
- Sign up at alpaca.markets.
- Go to Paper Account → API Keys and generate a key and secret.
You want the paper keys. Paper and live credentials are different, and this tool defaults to paper for a reason.
quantred init
The wizard prompts for both (hidden — nothing lands in your shell history), checks
them against Alpaca with one cheap request, confirms paper trading is on, and offers
to warm a small local data cache. It writes ~/.tradeflow/.env.
It then asks whether to set up a model provider for research (Anthropic, OpenAI or a
local Ollama). Skipping is fine: the demo, backtest, verdict and MCP server need no
model. A key is read hidden and an existing one is never blanked; for Ollama it asks
for the endpoint, a response timeout and an optional context length. It does not test
the connection for you - it prints the init --check --for research --provider <name> --probe-model command to run when you are ready (a hosted provider bills one tiny
request). With --non-interactive --provider <name> the same choices come from that
provider's variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, or OLLAMA_BASE_URL,
OLLAMA_TIMEOUT and OLLAMA_NUM_CTX) in the environment; without --provider, model
variables are not copied.
The closing steps also say how an MCP client attaches: the client launches
quantred mcp itself over stdio, so you add it to the client's configuration rather
than running it in a terminal (AI agents).
Check it any time:
quantred init --check
That reports every setting independently — what is set, what is missing, whether optional extras are installed — and writes nothing.
4. Your first real result
quantred verdict --scanner none --symbols AAPL,MSFT,NVDA,AMZN,GOOGL,META,AVGO,JPM,XOM,UNH,COST,WMT \
--start 2024-01-01 --end 2024-12-31
Twelve names and no scanner is deliberate: a long-only book capped at 25% per name
needs at least four names to be fully invested, and a scanner may flag fewer than
that, in which case the verdict is infeasible (see
reading the verdict). The list is a usability example —
well-known, liquid names — not a validated universe.
One command runs the whole cross-sectional pipeline — scan, alphas, portfolio construction, information analysis — over one universe, one window, and one cost model, and ends in a single verdict.
Read the verdict line first, then the checks under it. You will most likely get
mixed or not promotable, and that is the normal outcome. Every check shows its
value and its threshold, so you can see exactly which part failed:
| Check | What it means when it fails |
|---|---|
ic_tstat | The signal's accuracy is not distinguishable from luck |
ir_above_noise | The realized information ratio is inside its own error band — indistinguishable from zero |
sanity_ceiling | A result too good on public data — suspect a bug or a data leak, not skill |
sample_size | Too few rebalances to measure anything with confidence |
net_of_cost_alpha | There may be an edge, but trading costs eat it |
Want it as a file you can keep or share?
quantred verdict --scanner none --symbols AAPL,MSFT,NVDA,AMZN,GOOGL,META,AVGO,JPM,XOM,UNH,COST,WMT \
--start 2024-01-01 --end 2024-12-31 --html result.html
That writes one self-contained page — charts embedded, no external requests when opened.
5. Connect Claude
The server needs the mcp extra, which step 1 installed. On a copy that lacks it,
quantred init --check --for mcp prints the one command that adds it and keeps the extras
and packs you already have (a bare uv tool install --force "quantred[mcp]" would drop them).
Check the server starts and answers discovery, then register it with your MCP client:
quantred mcp --self-test
It prints the exact block below with the absolute command for your copy (and the
TRADEFLOW_HOME it needs, when you set one). Use that block rather than typing the bare
command: a desktop client often has a smaller PATH than your terminal.
Claude Code:
claude mcp add quantred -- quantred mcp
Claude Desktop — add to claude_desktop_config.json (paste what --self-test printed;
the bare command is shown here for shape):
{
"mcpServers": {
"quantred": { "command": "quantred", "args": ["mcp"] }
}
}
Restart the client and ask it something:
What has this campaign already tried, and what was the best result?
Run a verdict on twelve large US stocks for 2024, with no scanner, and tell me honestly whether there's an edge.
Explain what the deflated Sharpe ratio is correcting for.
Claude cannot trade. The server constructs only a market-data client — no broker, no trading client — so placing an order is not a capability it has, rather than a rule it has been told to follow. There is no order tool to prompt-inject around. Promoting a strategy to live trading is a manual step you take yourself, outside the agent entirely.
Worth knowing: everything Claude runs is journaled the same way your own commands are, and counts toward the same multiple-testing total. An agent that runs fifty backtests has genuinely made your next result harder to believe, and the tool will say so.
6. Where to go next
- One-command verdict — the full flag set and how the gates work
- Backtesting and walk-forward validation — "did this ever work", the honest way
- Browsing the trial store — what you have already tried, and the leaderboard that will not lie to you about it
- The two clocks — why research and trading are kept apart, which is the idea the whole design rests on
A word about expectations
Most things you try will not work, and the tool is built to tell you that quickly rather than slowly. That is the feature. A backtest that looks fantastic is the normal result of trying many configurations, and nearly every guardrail here exists to separate that from a real edge.
If a strategy survives walk-forward validation, clears the deflated Sharpe against everything you have tried, and still has positive expected return net of trading costs — then you have something worth a longer look.
Educational software. Keep PAPER_TRADE=true unless you fully understand the
consequences. Trading carries real financial risk, and nothing here is investment
advice.