Trading as git
Every trade is a diff; approving it is a commit. Full workspace history gives you a complete, auditable record of every decision.
Qoc models trading decisions the same way software teams model code changes: as versioned, reviewable diffs that only take effect once you explicitly approve them.
The core analogy
In a git workflow, a developer proposes a change as a diff. A reviewer looks at the diff, understands the intent, and either approves or requests changes. Only after approval does the diff land in the main branch and become canonical.
Qoc applies the same pattern to trading. The agent proposes a trade by writing an order file into orders/pending/. That file is the diff — a precise, human-readable description of what would change. You review it. If you approve it (via qoc run confirmation or the UI), it is submitted to the venue. The filled order is moved to orders/filled/ and snapshotted into workspace history. That history is the commit log.
Git concept → trading concept
| Git | Qoc equivalent |
|---|---|
| Working tree change | Agent writes a proposal file to orders/pending/ |
| Diff / patch | The order file: symbol, side, quantity, price, rationale |
| Code review | You read the proposal and the research that backs it |
| Merge / commit | You approve; the order is submitted to the venue |
| Commit hash | Workspace snapshot ID — a point-in-time hash of all state |
| Git log | Ordered list of snapshots in snapshots/ |
| Revert | Close or reverse a position; workspace records the reversal |
| Branch | A separate workspace directory for experimental strategies |
Audit trail
Every state transition — proposal created, approved, rejected, filled, cancelled — is recorded in the workspace with a timestamp and the agent session that triggered it. Because the workspace is a directory of plain files under built-in version history, you can reconstruct what the book looked like at any point in time by replaying snapshots.
The snapshots/ directory holds a chronological series of full-book snapshots. Each snapshot file is a JSON document capturing UTA state: positions, cash, open orders, and the hash of the desk.toml that was active at the time.
Reading the snapshot log
# List all snapshots, newest first
qoc snapshot --list
# Diff the current book against a past snapshot
qoc snapshot --diff 2026-07-01T09:00:00ZUse branches for strategy experiments
Create a second workspace directory (e.g., ~/qoc-experimental/) with its own desk.toml. Point it at paper-trading connectors. Run the agent there to test a new strategy. When you are satisfied, manually migrate the approved logic — or the order files themselves — into your primary workspace.
Revert strategies
In git, revert creates a new commit that undoes a prior commit without erasing history. In Qoc, the equivalent is placing an offsetting order: if you own 100 shares of a position opened by a prior decision, you close it with a new sell order. The history of both the original order and the close is preserved in orders/.
You can ask the agent to generate a reversal proposal explicitly: describe the position you want to close and why, and the agent will write the offsetting order file for your review — same flow as any other trade.
Approval is the control point
The agent cannot submit an order without your approval by default. The require_approval flag in desk.toml is true out of the box. Only set it to false for fully automated schedules you have carefully reviewed and bounded with guards.