Skip to content

Start Here

Choose the path that fits you best. Each one has a recommended reading order and a first action to take.

I'm a student

You're learning quantitative finance, systematic trading, or financial technology. You may be comfortable with Python but haven't built a full research workflow before.

Start with:

  1. Why Q-agent Exists — understand what the project is and why it's structured this way
  2. Running Notebooks — run a real research notebook in under 10 minutes, no QuantConnect account needed
  3. Architecture — learn the atomic layer pattern used in every strategy project
  4. Research Recipes — browse research ideas you can build toward

First action: Run the Election & Industry Returns notebook. It pulls live data from public APIs and renders charts immediately.

git clone https://github.com/WolfpackOfOne/Q-agent.git
cd Q-agent
python -m venv infrastructure/marimo/venv
source infrastructure/marimo/venv/bin/activate
pip install -r infrastructure/marimo/requirements.txt
marimo run infrastructure/marimo/notebooks/election_industry_returns.py --port 2719

Or skip the venv entirely with the Docker image (see Docker):

docker run --rm -it -p 2719:2719 -v "$(pwd):/workspace" \
  ghcr.io/wolfpackofone/q-agent:latest \
  marimo run --host 0.0.0.0 --port 2719 --no-token \
  infrastructure/marimo/notebooks/election_industry_returns.py

I want to build a strategy

You want to write a systematic trading strategy, backtest it with real data, and iterate on the research.

Start with:

  1. Golden Path — follow one hypothesis from raw data to a diagnosed backtest end to end
  2. LEAN & QuantConnect Setup — install the LEAN CLI and connect your QuantConnect account
  3. Architecture — understand the atomic layer pattern before writing code
  4. Data Pipelines Overview — know what local data is available
  5. Agent Workflows — use Claude Code to accelerate strategy development safely

First action: Create a project using the _template directory and run your first cloud backtest.

source ~/Documents/Q-agent/venv/bin/activate
cd ~/Documents/Q-agent/MyProjects
cp -r _template MyFirstStrategy
lean cloud push --project "MyFirstStrategy" --force
lean cloud backtest "MyFirstStrategy" --name "baseline"

Prefer a containerised LEAN CLI? Mount your QuantConnect credentials read-only into the Docker image:

docker run --rm -it \
  -v "$(pwd):/workspace" \
  -v "$HOME/.lean:/home/qagent/.lean:ro" \
  ghcr.io/wolfpackofone/q-agent:latest \
  bash -c "cd MyProjects && lean cloud push --project MyFirstStrategy --force \
                       && lean cloud backtest MyFirstStrategy --name baseline"

Note: lean backtest (local) is host-only — the container does not bundle a nested LEAN engine container. See Docker for the full workflow.

I want to add a pipeline

You have a data source — an API, a CSV feed, a database — and want to make it available for local notebooks and LEAN backtests.

Start with:

  1. Data Pipelines Overview — understand the existing pipeline conventions and output formats
  2. Look at an existing pipeline for reference: infrastructure/pipelines/crypto/ is the cleanest LEAN-ready example
  3. The new-pipeline-coder agent in .claude/agents/ will scaffold the full pipeline structure for you

First action: Ask Claude Code to scaffold a new pipeline.

claude "Create a new pipeline for [your data source] following the pattern
in infrastructure/pipelines/crypto/"

Output format: Pipelines write to data/ for raw/intermediate/research CSVs, lean-data/ for LEAN-ready outputs, or both. See Pipelines Overview for the conventions and schema notes.

I want to use agents

You want to use Claude Code or other AI agents to work on strategies, pipelines, and notebooks — safely and consistently.

Start with:

  1. Agent Workflows — see what an AI-assisted session looks like in practice
  2. Read AGENTS.md in the repo root — architecture guidelines that keep agent output safe
  3. Read claude.md — workspace-specific rules, gotchas, and memory system documentation

Key patterns: - Always activate the venv before running commands: source ~/Documents/Q-agent/venv/bin/activate - Use lean cloud push --force after agent edits to validate in the cloud - Agent memory lives in .claude/memory/ — durable learnings persist across sessions

First action: Open the project in Claude Code and ask it to explain the architecture.

cd ~/Documents/Q-agent
claude "Walk me through the architecture of this workspace"

I want to contribute

You want to improve the project — add a pipeline, write a notebook, improve documentation, or fix a bug.

Start with:

  1. Contributing — contribution workflow and standards
  2. Project Map — understand where everything lives
  3. Look at open issues on GitHub for ideas

Good first contributions: - Add a research recipe (see Research Recipes) - Write a pipeline page for a data source that isn't documented yet - Record a real terminal walkthrough to replace one of the synthetic recordings - Add a notebook that demonstrates a research idea from Research Examples

First action: Fork the repo, create a feature branch, and open a PR.

git checkout -b feature/my-contribution
# make your changes
git push origin feature/my-contribution
# open a PR on GitHub