File-based state
All Qoc state lives in plain, human-readable files. No hidden database. Every file is portable, diffable, and straightforward to back up.
A Qoc workspace is a directory of ordinary files — TOML, Markdown, JSON — managed under built-in version history, with no opaque database behind the scenes.
Why files?
Traditional trading platforms store state in proprietary databases. You cannot read them without the application, diff them to see what changed, or back them up with a standard tool.
Qoc takes the opposite approach. Every piece of state — configuration, positions, research, orders, schedules, snapshots — lives in a file you can open in any text editor. This means the workspace is inspectable without Qoc installed, portable to any machine, and naturally backed up by any file sync tool or git remote.
Workspace directory layout
| Path | Contents |
|---|---|
desk.toml | Primary configuration: venues, guards, AI provider, snapshot interval. |
entities/ | Named entities (watchlists, baskets, counterparties) as TOML files. |
inbox/ | Briefs and tasks for the agent to pick up on its next run. |
issues/ | Locally tracked issues; also synced from GitHub if configured. |
schedules/ | Cron-style schedule definitions; each schedule is one TOML file. |
snapshots/ | Point-in-time JSON snapshots of the full UTA book. |
research/ | Agent-written research notes; one Markdown file per task. |
orders/ | Pending, filled, and cancelled order records as JSON files. |
Version history
Qoc maintains an internal content-addressed history of the workspace. Every time a file changes — a new proposal lands in orders/pending/, a snapshot is written, you edit desk.toml — the change is recorded. You can view the log with qoc logs and inspect or restore any prior state.
The history is stored in a .qoc/ subdirectory inside the workspace. You can also layer a standard git repository on top of the workspace directory and commit changes to a remote for an additional off-machine backup.
Inspecting workspace history
# Show the last 20 log entries across all workspace files
qoc logs --limit 20
# Show only changes to the orders directory
qoc logs orders/
# Show what changed in a specific snapshot
qoc logs --snapshot 2026-07-04T14:32:00ZBack up with any sync tool
Because the workspace is a plain directory, you can sync it with any tool: rsync, Dropbox, iCloud Drive, a git remote, Backblaze, or a cron-scheduled tar. No special export step required — the directory is the backup.
Diffing and auditing
Because files are human-readable text, standard diff tools work on them. To see what changed between two snapshots, diff the two JSON files directly, or use qoc snapshot --diff <timestamp> which produces a structured diff against the current book.
Order files include a rationale field written by the agent that explains the reasoning behind the proposal. This means the audit trail is not just what happened — it includes why the agent proposed it. Research files linked from the order provide the supporting evidence.
Sample pending order file
{
"id": "ord_20260704_001",
"status": "pending",
"side": "buy",
"symbol": "QQQ",
"quantity": 10,
"order_type": "limit",
"limit_price": 481.50,
"venue": "equities-primary",
"rationale": "Tech sector momentum score crossed 0.72 threshold per research/2026-07-04-tech-momentum.md. Position size respects the 5% single-name guard.",
"research_ref": "research/2026-07-04-tech-momentum.md",
"proposed_at": "2026-07-04T14:00:00Z",
"proposed_by": "claude-code-session-8af3"
}Do not edit order files while they are pending
If you need to change order parameters (e.g., quantity or limit price), delete the pending file and ask the agent to regenerate the proposal with updated constraints — or write a corrected file yourself. Partial edits to a file mid-submission can produce inconsistent state.