Master the art of trading, one bar at a time

PivBO: Pivot BreakOutbeta

PivBO is “coffeeware”: completely FREE and open source, running purely on donated caffeine.

Study momentum setups on historical US equities. Replay any ticker one bar at a time, manage positions with full risk discipline, and challenge a friend to a timed head-to-head duel.

Download View on GitHub
What’s inside

Four tools, one workbench

A self-hosted environment for everything before you put real money on a setup: chart it, replay it, duel it, and own the data.

Chart

Browse any ticker, any timeframe. Configurable moving averages, ADR and ATR overlays, secondary chart for market context, drawing tools, log/linear scale.

Simulator

Replay charts bar-by-bar. Place market and limit orders, set stop losses, take partials, track R-multiples and batting average. Save, resume, and analyze every session.

Duel Mode

Head-to-head practice against a friend. Same ticker, same bars, synchronized countdowns. Trade blind or visible. Side-by-side comparison report at the end.

Data

Browse your local chart data. Add new tickers, download fresh bars from Yahoo Finance, bulk-update the whole library, and check coverage ranges per symbol.

Coffeeware

Free forever. Fueled by coffee.

PivBO is coffeeware: no ads, no tracking, no paywall, no subscription. Every new feature is written between sips.
If it saved you from a bad trade or taught you something new, fuel the next feature.

Buy me a coffee
Optional. No login, no subscription. One-click tip if you feel like it.

Download

Latest release: latest · Release notes
Package manager winget install PivBO

To run: type pivbo on a fresh terminal.

Update: winget upgrade PivBO

Direct download PivBO-windows.zip
  1. Extract the .zip anywhere.
  2. Double-click PivBO.exe.
  3. First launch: SmartScreen prompt → More info → Run anyway.
Package manager Homebrew cask · coming soon
Direct download PivBO-macos.zip
  1. Double-click the .zip to unzip.
  2. Drag PivBO.app into Applications.
  3. First launch: System Settings → Privacy & Security → Open Anyway. Apple's guide.
Package manager coming soon
Direct download PivBO-x86_64.AppImage
  1. Save the .AppImage anywhere.
  2. chmod +x PivBO-x86_64.AppImage (or right-click → Allow executing).
  3. Double-click it, or run ./PivBO-x86_64.AppImage.

Tip: Gear Lever adds AppImages to your app menu and keeps them updated.

Compose docker-compose.yml
  1. Save it in a folder of your choice.
  2. From that folder: docker compose up -d.
  3. Open http://localhost:5051/.

Recommended for long-running self-hosted setups (auto-restart, declarative config, easy upgrades).

One-shot run 
docker run -d \
  -p 5051:5051 \
  -v pivbo-data:/data \
  ghcr.io/mbelgin/pivbo:latest
  1. Run the command above.
  2. Open http://localhost:5051/.

Image: ghcr.io/mbelgin/pivbo · multi-arch (amd64, arm64).

Linux bind-mount? Add PUID and PGID env vars matching your host user so files aren't root-owned. Docker Desktop on Mac and Windows handles UID translation automatically, no env vars needed.

Any OS

Run from source

For developers, or anyone who'd rather run directly from the code. Requires Python 3.10+ and git. 

# Clone the repo
git clone https://github.com/mbelgin/PivBO.git
cd PivBO

# Install dependencies (a venv is recommended)
python -m venv .venv
# Windows:  .venv\Scripts\activate
# macOS/Linux:  source .venv/bin/activate
pip install -r requirements.txt

# Start the server (opens at http://localhost:5051/)
python pivbo_server.py

On first launch PivBO seeds a library of historical bars from the repo; after that it runs fully offline. Your simulations, templates, and analyses live under your user data directory and are never uploaded.

Documentation

Docs

A concise tour of what's in PivBO and how to use it. Expand any section below.

First launch

Launching PivBO opens a small control window and your default browser at http://localhost:5051/. The app runs as a local server on your own machine. Nothing ever leaves it.

On the very first launch a banner at the top of the page says One-time Download and progresses through ~930 compressed historical CSVs pulled from the project's GitHub repo. Tickers become available in the sidebar as each file lands; the whole seed takes a few minutes on a typical connection. When it finishes, PivBO offers to refresh each ticker with the most recent bars from Yahoo Finance. Skip it if you don't need today's close.

Windows + winget tip: a winget install does not create a Start menu shortcut (winget portable packages can't). Open a fresh command prompt or PowerShell and type pivbo. (A pre-existing terminal will not see the new pivbo command until restarted.) When the icon appears in the taskbar, right-click it and choose Pin to taskbar. After that it's a permanent one-click launcher. Same idea works for Pin to Start.

Sharing PivBO with another machine on your Wi-Fi: the launcher window has a Listen on local network switch. Flip it on (then click Stop, then Start) and the status line shows both the loopback URL and an http://<your-LAN-IP>:5051 address. Open that on another computer on the same network and you get the same PivBO. The choice is remembered across launches. Use only on networks you trust; do not enable on public Wi-Fi.

Where your data lives and how it's organized: see the Your data section below.

Chart view

The left sidebar lists every ticker you have data for, with its first and last bar date. Click any row to chart it.

Top-of-chart controls cover the usual axes:

  • Candles / OHLC / Line mode toggle.
  • Daily / Weekly / Monthly timeframe.
  • Log / Linear price scale.
  • MAs button for moving-average overlays: add, remove, color, swap SMA/EMA, edit period per MA.
  • ADR / ATR in the crosshair info bar, with editable lookback periods.
  • Panels popover toggles optional sub-panes: a secondary chart above the main one (e.g. QQQ for market context, date-synced), a volume pane, and (during simulations) an equity curve pane.

Drawing tools are on the left edge: horizontal line, line, ray, segment, text, measure, freeform note. Drawings are per-ticker and persist across sessions.

Running a simulation

From the Simulations page click + New Simulation. Fill in a name, starting capital, and optionally the “skip to first bar with an N-period MA” warmup offset. Then pick one of two modes:

  • Pick a Ticker: type the symbol and a start date (or tick “use first available bar”).
  • Surprise Me: set a minimum years-of-history and average ADR% filter, PivBO picks a random matching ticker and a random start bar.

Click Start Simulation. The chart switches to sim mode: only bars up to the current one are visible, the right side becomes a trade panel, and playback controls appear at the bottom.

Navigate bar-by-bar with the arrow keys:

  • → advance one bar.
  • ← retreat one bar. Retreating past a trade's creation bar permanently undoes it.
  • Jump to start / end buttons on the playback bar.

A sim auto-saves after every meaningful event (trade, advance, retreat, SL move). You can close the tab and come back. The sim resumes exactly where you left it.

Placing and managing trades

Click Long or Short on the trade panel. The entry form lets you specify:

  • Entry: leave blank for market-at-close, or type a price for a limit order.
  • Stop loss: a price. Preview levels appear on the chart; drag them to adjust before submitting.
  • Size: either a Risk % of current equity (PivBO computes shares so the distance to SL equals that risk), or a Position Size % of current capital (PivBO computes shares to deploy that fraction of equity into the trade).
  • Limit toggle with an optional max gap%: the order stays live until the bar's touch matches; gaps past the limit by more than N% cancel the order rather than filling at the unrealistic open.

Flex open-bar SL. A separate toggle that solves a specific same-bar fill problem. When enabled: on the bar a trade enters, PivBO uses only the bar's close to check the stop loss, and caps any fill at the SL price. Without it, you can get impossible fills on bars that open past SL, rally to trigger entry, dip back, and close above SL. Recommended on. See the FAQ for a worked example.

Once a trade is open, the chart shows entry and SL levels as live lines. The trade panel flips to show open positions:

  • Drag the SL line on the chart to move it (use the B/E button for a one-click breakeven).
  • Partial-close buttons: ¼, ⅓, ½, ¾, ALL, or type an exact share count.
  • Flatten closes every open position at the current bar's close.

R-multiples use the risk frozen at entry, so moving your SL later doesn't skew the R stats. Analytics refresh live as you advance bars.

Saving, resuming, comparing

The Simulations page lists every sim you've started, with its name, ticker, date range, open P/L, and last-modified time. Select one to resume where you left off. Multi-select enables:

  • Rename / Save As (duplicate) / Delete.
  • Export ZIP: bundles selected sims as JSON for backup or transfer.
  • Import: restores sims from a ZIP.
  • Analysis: per-sim HTML report with the equity curve, trade timeline, win/loss distribution, and optional PDF export.
  • Compare: side-by-side report for 2-5 selected sims, with identical sections stacked.

Templates: save the current chart and indicator setup (MAs, secondary-chart symbol, volume/equity panes, etc.) as a named preset. New simulations can start from a template instead of the default layout. Manage them from the Templates button on the sim panel.

Your data: where it lives

PivBO keeps everything you generate in a single per-user folder on your own machine. No cloud sync. No accounts. No upload of any kind.

  • Windows: %LOCALAPPDATA%\PivBO\
  • macOS: ~/Library/Application Support/PivBO/
  • Linux: ~/.local/share/PivBO/
  • Container: /data inside the container, mapped to a Docker named volume by default. Bind-mount a host path to /data if you'd rather see the files on disk.

What's inside:

  • collected_stocks/: the historical ticker CSVs (around 900 daily-bar files seeded on first launch, plus anything you've downloaded since).
  • simulations/: one JSON per saved sim.
  • templates/: saved chart-and-indicator presets.
  • analyses/: saved Analysis and Compare reports.
  • preferences.json: your gear-icon settings.
  • drawings.json: per-ticker drawings.

Reinstalling or upgrading never touches this folder. Wider date ranges you've pulled for individual tickers are preserved across updates. If you ever want to start over, close PivBO and delete the folder; the next launch re-seeds from scratch.

Backup is whatever your normal disk-backup is. To move PivBO to a new machine, copy the folder over before first launch on the new machine; PivBO will skip the seeder and pick up exactly where you left off.

Duel Mode

A 1v1 remote simulation where two traders race the same ticker from their own machines. Signaling is done over a public MQTT broker; a 6-character room code scopes the match. No accounts, no servers you have to run.

From the Duel tab:

  • Host: pick the filters (ticker universe, min years of history, min average ADR%, decision timeout per bar), optionally hide the ticker until the end, share the generated room code with your opponent.
  • Join: paste the code you received.

Flow:

  1. Honor code: both players accept.
  2. Preparation: both set up their indicators, drawings, equity pane, then click READY.
  3. Active: a per-bar countdown starts. Each bar, every player either trades, modifies a position, or presses → to lock in no-action. The bar advances when both have locked in (or the timer expires). Retreating is disabled for the duration of the duel.
  4. The opponent's equity curve is visible inside the equity pane (dotted when they have an open position), but no other trade details are exposed: no entry, SL, size, or side.
  5. Either side can pause or call End Duel (forfeit).
  6. At the last bar, all open positions close at that bar's close. Both players see a Compare report side-by-side. Ticker is unmasked in the report if it was hidden during the duel.

A dropped connection triggers an auto-pause for up to 3 minutes; if the peer reconnects within that window, the duel resumes cleanly. Refreshing a tab mid-duel also restores state on reconnect.

Data: downloading and updating tickers

Click Data in the topbar to open the ticker downloader. You can:

  • Download a single ticker: type the symbol, pick a date range (or let PivBO use Yahoo's full available history), click Download. The resulting bars are written as a compressed CSV under your user data directory.
  • Update All: for every ticker already on disk, fetch any missing dates since the last local bar. Progress bar shows ticker-by-ticker status. Cancellable at any time. Typically a few minutes for the full ~930-ticker seed.
  • Import bulk: drag-drop or pick a ZIP of CSVs.

The update path only fetches missing dates from Yahoo; it never re-downloads entire histories. Existing wider date ranges are always preserved. A re-run of the first-launch seeder never overwrites a file you already have.

Preferences

Open the gear icon top-right. The main settings:

  • Profile: your email (used only for Duel Mode display names and tournament identity: the local-part before @ becomes your name, and the full email never leaves your machine).
  • Theme: dark or light.
  • Default starting capital: pre-fills the New Simulation form.
  • VS symbol: the ticker used for the benchmark overlay in analysis reports.
  • Port: the local server port. Change this if 5051 collides with something else, or to run two instances side-by-side for self-duel testing.
  • Updates: a Check for updates button (queries the GitHub Releases API and tells you whether a newer version exists), plus a Check on launch toggle (silently checks at startup and surfaces a banner if a newer version is available). PivBO does not auto-download or replace itself; if a newer version exists, the banner links you to the Download section.
Keyboard shortcuts

Sim playback (active during a simulation):

  • → or >: advance one bar.
  • ← or <: retreat one bar. Disabled in Duel mode; enabled in Self-Duel.
  • Esc: close the trade form (always wins, even from inside inputs).

Drawing tools (chart view):

  • Alt+V: pan tool
  • Alt+H: horizontal line
  • Alt+A: extended line (trendline)
  • Alt+R: arrow
  • Alt+S: segment
  • Alt+T: text label
  • Alt+N: note
  • Alt+M: measure
  • Esc: switch back to pan tool, also reverts a pending stop-loss drag.
  • Delete or Backspace: delete the selected drawing.
  • Ctrl+Z (⌘+Z on macOS): undo the last drawing change.
  • ↑ / ↓: navigate the ticker list (chart view only, not during a sim).

Modals:

  • Esc: close the Preferences page or any open modal.
  • Enter: submit code/symbol inputs (Duel join, Yahoo data dialog, etc.).

Browser-native chords (Ctrl+F find, Ctrl+R reload, etc.) are never hijacked. Typing in any input or the inline-rename field also disables the sim and drawing shortcuts so keystrokes go to the input you're focused on.

Stopping and quitting

Closing the browser tab only closes the UI. PivBO is still running in the background. Reopen the tab at http://localhost:5051/ anytime.

To actually stop the server, use the small PivBO control window that opens with the app: click Stop (pauses, keeps the launcher open) or Quit (closes everything). If you launched from a terminal, you can also Ctrl-C that terminal.

FAQ

Frequently asked questions

The short answers. For deeper detail, see the Docs.

Is PivBO really free?

Yes. MIT-licensed, open source, no ads, no tracking, no accounts. It's coffeeware: free forever, with an optional Ko-fi tip if it helped you.

Where does my data go?

Nowhere. PivBO runs as a local server on your own machine. Every simulation, trade, preference, and analysis stays in a per-user folder on your disk: %LOCALAPPDATA%\PivBO\ on Windows, ~/Library/Application Support/PivBO/ on macOS, ~/.local/share/PivBO/ on Linux, or /data inside a container (named volume by default, or bind-mount a host path if you'd rather see the files on disk). Reinstalling or upgrading never touches it. No cloud, no accounts, no tracking. See the Docs → Your data section for what's inside and how to back it up.

Why is the first launch slow?

First launch pulls a prebuilt library of historical daily bars (around 900 US tickers, ~50 MB) from the project repo so you can start trading immediately. Happens once. After that, PivBO runs fully offline unless you ask it to fetch more data.

What trading style is PivBO inspired by?

PivBO leans heavily into Qullamaggie-style momentum trading, but it works for any approach. You get the core price and volume action, plus a small set of key indicators (MAs, ATR, ADR).

What is “Flex open-bar SL” and should I leave it on?

A toggle in the trade form that fixes a specific same-bar-entry edge case. Recommended on by default.

The problem it solves. Imagine you submit a long limit at $100 with a stop at $98, mid-day on bar X. The rest of bar X then prints: open $97 (already below SL), high $103 (touches your limit so the order fills), low $96 (would retrigger SL), close $101. Without Flex, the simulator could fill you at the limit AND register the low as a stop-out on the same bar. In a real market that sequence is rarely tradable as written; you'd more likely have skipped the entry entirely once price gapped under your stop.

What Flex does on the entry bar. It checks your stop only against the bar's close, and caps any exit at the SL price. So in the example: you fill at $100, and the bar closes at $101 above your stop. Your trade is live and the SL just hasn't triggered yet. The next bar processes normally.

Cost. A small percentage of trades that the unconstrained engine would have stopped out on the entry bar stay open instead. In practice this is negligible compared to the impossible-fill artifacts it prevents.

Can you add indicator XYZ?

The indicator set is intentionally lean, so attention stays on price and volume action. I'll consider adding commonly-requested ones when caffeine levels permit. File requests on the GitHub repo. High-quality PRs for indicators are also welcome.

How can I share or back up my simulations?

The Simulations interface lets you export selected sims as a .zip bundle, and import a previously-exported zip on any other PivBO install.

What are some good tips to make the best of PivBO?

Depends on what you want from it, but three patterns I find especially useful:

  1. Controlled A/B comparisons. Re-run the same ticker and date range multiple times, changing one rule per run, then compare the analyses side-by-side (up to 5 sims).
  2. Duel a friend. Live competition surfaces the real-trading psychology that a solo echo-chamber simulation simply can't.
  3. Build a model book. Click any trade in the history list to review it. Draw, annotate, and screenshot key setups for an ever-growing reference.
How can I contact you for bugs or feature requests?

Open an issue on GitHub: github.com/mbelgin/PivBO/issues.

How can I help make PivBO better?

Thanks for asking. This is not a one-person job. A few ways to pitch in:

  • Send a pull request. Small, focused PRs with a clear description, tests where they make sense, and no unrelated churn are the easiest to review and merge. Follow the existing code style and open an issue first if the change is non-trivial.
  • Report issues, request features. Use GitHub Issues. A short repro and a screenshot go a long way.
  • Spread the word. A star on the repo and a mention to other traders on social puts PivBO in front of people who'd use it.
  • Donate caffeine. Every Ko-fi tip funds the next feature.