trading-desk
A record of your trades under the strategies that allowed them. You write each strategy down as a short Markdown file with a rules block. Every trade belongs to one strategy, at one version of it, in one run. The desk stores your decisions about each trade, with your reasons and screenshots, in an append-only SQLite log. From that log it will work out how each trade ended and report performance per strategy, per version and per run.
Status: 0.5.0, the record. This release stores strategies, runs, trades and every later decision. It does not yet judge exits from price bars, check a trade against its rules, report statistics, or serve the agent interface. Those come in the releases listed under Roadmap. The Python API below is what the agent interface will wrap, one call per tool.
0.5 is a new tool, not an upgrade of 0.4. 0.4 was a portfolio book with a terminal UI. Both are gone, along with its commands (
desk,desk-migrate,desk-check,desk-mcp), its[mcp]extra and itshub.dbformat. 0.5 does not read 0.4's data, and a 0.4 book is refused rather than misread.
The model
| Thing | What it is |
|---|---|
| Strategy | A Markdown file you write: the idea, how you enter, where the target and the stop go, and one rules block the desk reads (a later release checks each trade against it). |
| Version | A strategy's text at one moment. Any change to the text makes a new version, except for spacing within a line, trailing spaces, line endings and extra blank lines. A version never changes once saved, so it tells you exactly what each of its trades was taken under. |
| Run | One version deployed over a period. Its mode is live (trading now) or replay (bar-by-bar replay of the past). It also carries free-text tags such as paper, real or GC 15m, which the desk stores and never interprets. |
| Trade | One entry in one run: ticker, side, a market or limit entry, stop, target, size, currency (CAD or USD), your reasons in your own words, and screenshots. |
| Decision | Anything you do to a trade after entering it: move the stop or target, close it by hand, correct a mistake, or void it. Each carries a reason. |
Two principles hold everything together:
- Only decisions are stored. Exits, fills, statistics and whether a trade kept its rules are worked out from your decisions and the price bars whenever they are read. Nothing derived is stored, so nothing can go stale. (The one exception, from the release that adds checks: the rule results the desk showed you when you entered a trade are kept with it, as a record of what you saw.) A correction is a new entry that is read in place of the one it corrects. Nothing is ever edited or deleted.
- One timing rule. An entry, a move and a hand close each have an
at: the moment the decision takes effect, in UTC. In a live run it defaults to now. In a replay run you must give it, as the close of the bar you acted on. A decision takes effect from the first bar that opens at or after itsat. A time without a timezone is refused, never guessed. Corrections and voids are record-keeping, not market decisions: they are dated when you make them.
A strategy
---
name: Pullback in an uptrend
---
## Idea
Buy a shallow pullback in a stock that is already rising, with the stop under the pullback low.
## Rules
```rules
timeframes: 1h, 15m
min_reward_risk: 2
max_risk_per_trade: 100 USD
size: computed
stop_required: yes
target_required: yes
max_open_trades: 2
cooldown_after_stop: 1 day, same ticker
daily_loss_limit: -2R
banned: shorts, options
```
A template ships with the package (desk/strategy.example.md). Every value is read when
the strategy is saved: an unknown rule, an unreadable value, a value in the wrong unit, or a
duplicate is refused, naming the rule and the fix. No rule is ever silently dropped.
| Rule | Meaning |
|---|---|
timeframes |
Required. The bar sizes the strategy trades on, e.g. 15m, 1h. The finest one is used to judge exits. |
min_reward_risk |
The smallest reward-to-risk you will take. Reward-to-risk is the distance from the entry to the target divided by the distance from the entry to the stop, so 2 means the target is twice as far as the stop. |
max_risk_per_trade |
The most you will lose if the stop is hit, as an amount and a currency, e.g. 100 USD. Risk is size × the stop's distance × the point value. |
size |
computed: the largest size max_risk_per_trade allows. |
stop_required, target_required |
yes or no. |
max_open_trades |
How many trades this run may hold at once. A pending limit order counts. |
cooldown_after_stop |
How long to wait after a stop-out before the next trade, e.g. 1h, optionally same ticker. |
daily_loss_limit |
The most R the run may lose in a day, e.g. -2R. One R is the amount a trade risks between its entry and its stop. |
banned |
What you will not trade, e.g. shorts, options, futures. |
stop_headroom_candles |
The least distance between entry and stop, counted in median candle ranges. |
Install
pip install trading-desk # or, in a uv project: uv add trading-desk
Install it into the Python environment you will import it from: in 0.5 the desk is used
from Python, and its only command is trading-desk integrity. Python 3.11 or later, built
with SQLite 3.38 or later, on macOS or Linux. The package has no runtime dependencies.
Use it from Python
from desk import api, config, store
store.create() # once: makes desk.db under the data root
con = store.open()
text = config.example_strategy().read_text() # or your own strategy's Markdown
api.save_strategy(con, "pullback", text)
run = api.start_run(con, "pullback", mode="live", tags=["paper"])
t = api.trade(con, run.id, ticker="ACME", side="long", entry_type="market",
entry=100.0, stop=98.5, target=103.0, size=10, currency="USD",
reasons="Held the rising trend line on the hourly; volume dried up on the dip.",
screenshots=["https://www.tradingview.com/x/AbCd1234/"])
api.move_order(con, t.id, stop=100.0, reason="Price cleared the last high; stop to breakeven.")
api.get_trade(con, t.id).decisions
| Call | Does |
|---|---|
save_strategy, get_strategy, list_strategies |
Save a strategy (a new version whenever its text changes), read one, list them. Saving over an existing strategy needs if_current, the current_hash from your last read, so two sessions can never overwrite each other's edits. A strategy can also carry a tracker_script and tracker_limit; they are stored now and run in a later release. |
start_run, stop_run, list_runs |
Deploy a version, stop it, list runs. |
trade |
Enter a trade, with your reasons and screenshots. A screenshot is a local file, copied into the store under its content hash, or an https link. |
move_order, close_trade |
Move the stop or target, or close by hand. Each needs a reason. |
correct_trade, void_trade |
Correct a mistake (a new entry, read in place of the one it corrects), or void a trade: it stays in the log, and the releases that add statistics and checks leave it out of them. |
get_trade, list_trades |
Read trades back, with their decisions folded together. |
A refusal raises api.Refused, whose message says what was wrong and how to fix it. A
refused call writes nothing.
Where your data lives
Everything lives under one folder: ~/Documents/trading-desk/ by default, or
$TRADING_DESK_HOME.
desk.db strategies, runs, trades and every decision (append-only)
attachments/ screenshots, by content hash
config.toml optional settings, e.g. db = "elsewhere.db"
$TRADING_DESK_DB moves only the database: it names one file in place of desk.db.
Screenshots still go to the root's attachments/, so to keep a session apart from your
real data, set $TRADING_DESK_HOME instead.
The database uses a rollback journal, never WAL, because ~/Documents is often synced by
iCloud, and a database synced apart from its -wal file can be corrupted. Write from one
machine at a time.
trading-desk integrity checks the log for shapes it should never hold: a trade with no
entry, a decision dated before its trade, a move after a hand close, and more. It prints
each one, and exits 1 if it found any, or if there is no desk.db to check; 0 if the log is
clean. It checks the rows, not the file: a page SQLite cannot read stops it with an error,
and a damaged page it never reads can pass. To check the file itself, run
sqlite3 -readonly desk.db 'PRAGMA integrity_check'.
Roadmap
| Release | Adds |
|---|---|
| 0.5 | The record (this release). |
| next | Bars and the judge: price bars from Yahoo for live runs and from TradingView chart exports for replay runs, and a pure function that works out every fill and exit from them. A stop hit fills at the stop, or at the open if the bar gapped through it. A target hit fills at the target. |
| then | Rule checks when you enter a trade (the results you were shown are kept with it), and statistics per run, version and strategy: win rate, average R, total R, P&L. Each can be narrowed by mode, by tags, or to the trades that kept their rules, worked out again on read. |
| then | The MCP server and a Claude Code plugin, so an agent records your trades and decisions for you. |
| then | Custom trackers: a script per strategy that records whatever you choose about each trade, stored separately. |
| 1.0 | The release, once all of the above has landed. |
Development
uv sync
uv run pytest -q
uv run ruff check .
uv run python tools/no_real_figures.py
See CONTRIBUTING.md. MIT licensed.
Metadata
Release files for trading-desk 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| trading_desk-0.5.0.tar.gz | 70.3 kB | With provenance | Details for trading_desk-0.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| trading_desk-0.5.0-py3-none-any.whl | Python 3 | none | any | Details for trading_desk-0.5.0-py3-none-any.whl |
Total release size: 113.8 kB
Release files / trading_desk-0.5.0.tar.gz
| Download URL | trading_desk-0.5.0.tar.gz |
|---|---|
| Size | 70.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5ae725b2d6d5b018deaefc57803bd5443bd6b59c39f82a4952d0a747e5746e85
|
|
BLAKE2b-256 checksum How to use checksums |
06883ea3f495eaa5a67d5107de452e3d04e1dfa9a3e2d4ca4ca2093789ff9d1b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logRelease files / trading_desk-0.5.0-py3-none-any.whl
| Download URL | trading_desk-0.5.0-py3-none-any.whl |
|---|---|
| Size | 43.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
042e909c0d677bc13eae0671be94a514463a406e8ffc6b8d2808f568f8b91cbf
|
|
BLAKE2b-256 checksum How to use checksums |
7260d88254944e5a6959fb380316e53915f8306fdf338458501ed38274e0654c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logSecurity for trading-desk 0.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for trading_desk-0.5.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.