Quick start

Five-minute walkthrough

1. 1

   Initialise a workspace

   Create a new directory for your desk and run qoc init inside it. The command writes desk.toml, creates the standard subdirectories (entities/, inbox/, issues/, orders/, research/, schedules/, snapshots/), and prints a summary of what was created.

2. 2

   Connect a practice venue

   Run qoc connect paper to add a built-in paper trading venue. The connector writes a [connector.paper] block into desk.toml and creates an initial snapshot in snapshots/. No API credentials are needed for the paper venue — it simulates fills using real-time quotes.

3. 3

   Create a first task for the agent

   Open issues/ and create a file named 001-first-trade.md. Write a short brief: which ticker to research, what you are looking for, and any sizing guidance. This is the task the agent will pick up.

4. 4

   Run the agent task

   In a terminal inside your workspace directory, run qoc run issues/001-first-trade.md. This starts an agent session that reads your task, pulls research data into the workspace, writes a thesis to research/, and — if conditions meet your guards — writes a proposal to orders/proposed/.

5. 5

   Review and approve the proposal

   Run qoc status to see the proposal. Read the TOML file the agent wrote in orders/proposed/. When you are satisfied, run qoc approve <path-to-proposal>. The desk routes the order to the paper venue and records the fill.

Full command sequence

mkdir my-desk && cd my-desk
qoc init
qoc connect paper
qoc status

# Write your first issue (edit this file with your own brief)
cat > issues/001-first-trade.md << 'ISSUE'
Research NVDA earnings momentum.
Propose a small long if 20-day RSI < 60 and the thesis is intact.
Max position: 1% of NAV.
ISSUE

qoc run issues/001-first-trade.md

# After the agent finishes:
qoc status
# Read the proposal, then approve
qoc approve orders/proposed/001-first-trade.toml

What the agent writes

After qoc run completes you will find new and updated files across the workspace. entities/NVDA.toml holds the latest fundamentals and technicals the agent retrieved. research/001-nvda-thesis.md contains the agent's written rationale. orders/proposed/001-first-trade.toml is the order proposal — a structured file with symbol, side, quantity, order type, and the guard check results.

Every file is plain text. You can open it in any editor, modify the quantity or order type before approving, or delete it to reject the proposal without any further action.

Where to go from here