Getting started and interface
Introduction
blunderDB is software for creating backgammon position databases. Its main strength is to provide a single place to aggregate positions that a player has encountered (online, in tournaments) and to be able to re-study these positions by filtering them according to various arbitrarily combinable filters. blunderDB can also be used to create catalogs of reference positions.
Positions are stored in a database represented by a .db file. The desktop application opens this file directly, never a network address: server mode is another mode of the same binary, and moving from one to the other means exporting or migrating the database, not pointing the application at a URL.
Main Interactions
The main interactions possible with blunderDB are:
add a new position,
modify an existing position,
copy the board image to the clipboard (PNG) via CTRL-X, or with the full analysis via CTRL-X CTRL-X,
delete an existing position,
search for one or more positions,
import matches from various sources (XG, GNUbg, BGBlitz, Jellyfish, HedgeHog), including comments from XG files,
navigate through the moves of an imported match,
organize positions into collections,
organize matches into tournaments.
The user can freely tag positions and annotate them with comments.
Description of the interface
The interface of blunderDB is composed, from top to bottom, of:
[top] the toolbar, which gathers all the main operations that can be performed on the database,
[in the middle] the main display area, which allows for displaying or editing backgammon positions,
[at the bottom] the status bar, which provides various information about the database or the current position, and integrates the command line.
Panels can be displayed to:
display the analysis data associated with the current position from eXtreme Gammon (XG), GNUbg, or BGBlitz,
display, add, or modify comments,
search and filter positions using combinable criteria,
display and manage position collections (collections panel),
display the list of imported matches and navigate through the moves of a match (match panel),
display and manage tournaments (tournaments panel),
display performance statistics (Stats panel),
compute the EPC (Effective Pip Count) of a bearoff position (Eval panel),
train on calculation exercises (Training panel),
study positions with spaced repetition (Anki panel),
transcribe a match by hand (Transcription panel),
display the database metadata (metadata panel).
The panel height is set by dragging its handle; it stays the same from one tab to another.
Modal windows can be displayed to:
display the blunderDB help, whose search field (/ puts the cursor there) selects the occurrences of the typed text, regardless of case and accents (ENTER goes to the next, SHIFT-ENTER to the previous),
display the catalogue of guided tours (see Guided tours and sample database),
configure database export settings,
configure blunderDB, in particular the interface language (see Configuration).
The main display area provides the user with:
a board to display or edit a backgammon position,
the level and owner of the cube,
the pip count of each player,
the score of each player,
the dice to play. If no values are shown on the dice, the position of the dice indicates which player is on roll and that the position is a cube decision. When the cube decision is a response to a double (take/pass), the offered cube is shown in the centre of the board, at the offered value.
The clipboard is the everyday gesture; saving is the other need — the illustration for an article, a forum post, a lesson. SVG is offered because the board is one: it is the form that survives being enlarged, the one you put in a document without blurring it. PNG derives from it, as does the clipboard copy: one rendering, three destinations, so none of them can drift from the others. This menu does not appear in the Eval panel or in the Search panel, where the right button already places the other colour’s checkers. See Bringing a position into the Eval panel for bringing a position into the Eval panel.
The status bar is structured from left to right with the following information:
the command line, accessible by pressing the SPACE key,
an informational message related to an operation performed by the user,
the index of the current position, followed by the number of positions in the current library (or move/game info when navigating a match),
the library counter — “412 positions · 38 blunders · 5 matches” — where every number opens what it counts: the positions, the
E>search at the library’s threshold (run at once, as if typed, and recorded in the search history), or the match list. When the list on screen is not the whole library (search, collection, match), the blunder figure reads “12 / 340 blunders”: the blunders of that list, then those of the library, at the same threshold; a list of more than 20,000 positions is not counted and keeps only the total. A figure you cannot follow is a decoration. The blunder threshold is the library’s own, set in the Library tab of the settings and shared with the statistics: two thresholds would make the same word mean two things. The counter promises exactly what the link opens, including for a position played several ways, which is worth its largest cost. On a very large library (over 200,000 rows) the counter does not scan the tables: a number prefixed with “≈” is an estimate (an upper bound, since deleted rows leave gaps). If the positions are estimated, the blunder count, which has no honest estimate, is the last exact count, kept as long as no write can change it. After an import or an edit it shows “?” while a new count runs in the background, then comes back on its own; a library opened read-only does not recount and keeps “?” until the instance writing it has redone the count. The link runs the search, which gives the exact count. The two blunder numbers are separate links: the first runs thess E>sub-search within the list on screen, the second the search across the whole library; when only the total is shown, there is a single link.
Note
In the case of positions resulting from a user search, the number of positions indicated in the status bar corresponds to the number of filtered positions.
The Anki tab carries a badge when cards are due, across every deck. That figure is the reason to open the tab; it has no business behind it. Zero shows nothing: a badge saying “0” is noise.
The log command opens the activity log: the last two hundred lines of the log file, a button to copy them — what it takes to attach a report to a bug — and another to open the folder holding them. The log is neither filtered nor reformatted: a log you tidy up is a log you can no longer quote.
The grid command opens the contact sheet: the browsed list — search results, library, collection — as a grid of mini-boards, drawn like the board, in pages of twenty-four. It opens on the page of the current position, whose thumbnail is outlined; a click or ENTER on a thumbnail opens its position on the board and closes the sheet, and it can be browsed entirely from the keyboard (see Contact sheet). It does not open in edit mode or in a match, which is browsed by its moves.
In the search history of the Search panel, each token of a saved command shows as a named chip — No Contact, Move Error — rather than a bare token. The exact command stays in the tooltip, since that is what gets re-run; and a token blunderDB does not recognise shows as it is rather than translated to the nearest thing.
View Tabs
Below the toolbar, a tab bar lets you work with several views in parallel. Each view is an independent workspace that keeps its own position list, the index of the current position, the displayed position, the analysis and the selected move, the active panel, the comment being edited, as well as the navigation context within a match. This makes it possible, for example, to keep a search open in one view while browsing a match in another.
Create a view: click the + button of the tab bar (named + New view as long as there is only one view) or press CTRL-T. The new view starts as a copy of the current view.
Close a view: click the cross on the tab or press CTRL-W. The last view cannot be closed.
Switching views: click a tab, press CTRL-PageUp / CTRL-PageDown (or SHIFT-J / SHIFT-K) to go to the previous / next view, or CTRL-1 to CTRL-9 to jump straight to the n-th view of the active library.
Rename a view: double-click the tab, type the new name and confirm with ENTER.
A view left in the Eval panel comes back to it as it was left: its scratch board and, on leaving the panel, the position it was studying. The last scratch board of the Eval panel also belongs to each view.
Views are saved with the database session state and restored when it is reopened.
Open libraries
Several databases can stay open at the same time. Each one forms a group of tabs: in the bar, a coloured header carries the file name, followed by the views of that library, whose top edge repeats the same colour. Only one library is active at a time: it is the one the panels, the search, the imports and the assistant read and write.
With a single library open, the bar shows no header: only the window title names the database.
Opening a library in a new group: the ⧉ Another library button at the right of the tab bar (just ⧉ once two groups are open), CTRL-SHIFT-O, or the
open_groupcommand (og). The library that was active stays open in its group. CTRL-O, on the other hand, replaces the library of the active group; the tooltip of the toolbar’s Open button recalls both shortcuts.Switching library: clicking a tab of another group activates its library and that view in a single gesture; clicking the group header brings it back to the view where it was left. CTRL-SHIFT-PageUp / CTRL-SHIFT-PageDown go to the previous / next library; CTRL-PageUp / CTRL-PageDown (or SHIFT-J / SHIFT-K) walk through the views of all groups in sequence.
Closing a group: the cross of its header closes the library and its views. Closing the active group shows its neighbour; the status bar names the library that was closed and the one now displayed.
The header of the active group shows the name in white on its colour; those of the other groups show the name on the bar background, underlined at the top in their colour. Six colours follow one another: a seventh group takes the first again. Views are numbered within their library: a database opened in a new group starts at "#1", and CTRL-1 … CTRL-9 target the views of the active group. When the tabs no longer fit in the window width, the bar scrolls (mouse wheel, or the view change that brings the displayed tab on screen) instead of shrinking them.
The switch is immediate: each group keeps in memory its views, its position list, the current position, the search criteria (even while being typed, without the search having been run), the match list, the counters and the scroll of each list of the panel, and gets them back without re-reading the database. A library opened in a new group starts from a blank search form: the matches and tournaments chosen in one group never apply in another. Work in progress follows too: a transcription draft, a lesson, an Anki review, the study queue and the open Direction are found as they were left. What may have changed during the absence is re-read right after the display: the counters always, the match list if their number changed or if a background task wrote to the library during the absence. The lists specific to each database (collections, tournaments, Anki decks, drafts, Duels, search history, saved filters) are re-read in the displayed library.
A given file is not opened in two groups: reopening it shows the group that already holds it.
Background tasks stay attached to their library: an import of match files, the watched folder and the GammonNet batch analysis continue in the group where they started when another one is displayed, and never write to the displayed library. Their progress and their report stay in their group: as long as it is not displayed, its header carries a badge, which blinks while the task is working and becomes steady when it is finished. On returning to the group, the badge disappears, the status bar says what the task did and the match list is re-read. The automatic analysis that follows an import starts in the import’s library. The watched folder belongs to the group where it was started: match files are imported there in the background, while a database to merge or a position text waits until that group is displayed again. Closing a group stops its tasks and its watching.
Copying from one library to another. A row dragged onto another group’s header is copied there, in either direction: a match from the match list, a collection from the collection list, a position from an open collection, the displayed position (grab it by its “n / N” counter in the status bar) or the lesson being read (by its name in the lesson bar). The targeted header gets a dotted outline. The copy is the one the transfer command makes: an export’s selection, merged by the native import, with analyses, comments and played moves; a collection takes its positions along, a match its transcription. What the receiving library already holds is not copied again: copying from A to B and then from B to A creates no duplicate, and nothing there says where the copy came from. The copy runs in the background, attached to the receiving group: its header carries the badge, and on return the status bar says how many positions and matches are new and how many were already there.
The basket gathers rows from several libraries to pour them in one go. SHIFT-B puts the displayed position in it, or takes it out, as b does for the Pile; a row dragged onto the basket goes in too. The basket, at the right of the tab bar, shows its count; a click opens its menu (Pour into … each group, Empty the basket), and dragging it onto a group’s header pours it there. It lives in memory, never in a database: closing a group removes its rows, and it is gone when blunderDB closes. A position still in draft must be saved first.
The padlock on a header locks its group: nothing more is poured into it, neither by dragging nor from the basket, and the status bar says so. The lock touches neither imports nor the changes made in the group; a second click lifts it.
Switching groups stays refused, by click as by keyboard, with a message in the status bar that names the cause and says where to stop it, when what is running follows the screen: a rollout, whose result is displayed on the board position (rollout stop); a tournament display, which serves the displayed library on the club network (it is stopped in the Direction); a Duel in progress, which holds the board and its views; a training session, whose timer and log follow no group; and finally, for as long as it lasts, the import of files that only the interface can read (position texts, imported one by one) or the merge of a database. When blunderDB is closed, only the session of the active library is saved, and the list of groups is not: at the next start, blunderDB reopens the last active database.
What other libraries know: the Elsewhere tab
The Elsewhere tab (CTRL-SHIFT-A) tells, for the displayed position, what the other libraries open in groups know about it. The position is found there by its board identity (its hash), not by its number: the same number designates two different positions in two databases. Each library has its own block, bordered in the colour of its group:
its analysis: the best move, or the best cube action, and the engine that found it. An analysis valued with a match equity table other than the active library’s carries the label other MET;
its comments, each with its author, or its signer and the state of the signature as in the comments panel;
the matches where the position was played: players, tournament, date, move number, move or decision played and their cost. The verdict (good, error, blunder) is given with the thresholds of the active library, not those of the other; a cost computed with another MET is not compared and stays marked other MET. Beyond 50 matches, the 50 most recently imported are listed and the total is shown;
its neighbouring positions, the five closest, as thumbnails with their distance.
A library that does not contain the position says so, and still shows its neighbours. Open there, a click on a match or on a thumbnail activates that library’s group and displays the position in it. Nothing is written to any database. The ⟳ button rereads the other libraries.
Swapping in place. The x key shows, in place of the board, at the same spot and the same size, the position of the other library, under a banner in its colour recalling its name, its best move and the number of its comments. Held down, the key brings the board back when released; pressed briefly, the swap stays displayed until the next press. Changing position or window also brings the board back. The active group, the view and the list do not change. The position shown is, by default, the same position in the first other library that contains it; the Pin button under a thumbnail of the Elsewhere tab chooses that neighbour instead, until Unpin or a change of group.
The split screen. On a large screen, the ◫ button of the tab bar (CTRL-SHIFT-X) splits the window into two panes of the same width. One holds the active group, complete; the other a read-only viewer of another open library (of the same one, if only one is open): its board, the position’s analysis and its comment. The viewer walks through the whole library, a match replayed move by move (the game, the move and what was played show above the board) or a collection, chosen from its drop-down list, with its ⏮ ◀ ▶ ⏭ buttons. It opens where that library was left. Nothing it shows is written anywhere. Clicking the viewer, outside its buttons, activates its library: the two panes trade roles and each library keeps its side; CTRL-SHIFT-PAGE UP / PAGE DOWN does the same from the keyboard. Below 1280 pixels wide, the split screen is refused and the in-place swap (x) offered instead; it closes if the window becomes too narrow.
Configuration
The settings button (gear icon) in the toolbar, to the left of the help button, opens blunderDB’s settings window. It is organised in ten tabs:
Interface — theme, language, display scale, panel position, PageUp / PageDown step (10, 50, 100, 500 or 1,000 positions, or 10% of the list), logs, update check, your name and neighbouring positions;
Colours — the board’s colours;
Library — what belongs to the open database: the error and blunder thresholds, described below;
Maintenance — the health of the database, one line per operation, described below;
Corpus — duplicates on import, player and event aliases and the search for probable duplicates (see match import);
Bearoff — the bearoff tables used by the Eval panel;
gammonNet — the settings of the embedded evaluator, described below;
Watched folder — the automatic import of matches arriving in a folder, described below;
Assistant and MCP — the local MCP server and the built-in assistant, described below;
Issuer identity — the key that signs your watermarks, described in Handing out a database: origin and password.
The Interface tab starts with a theme: follow the system, light, dark, high contrast or printable. The theme sets the interface colours and proposes a board palette — a dark interface around a light board is not a dark theme, it is half of one, since the board occupies most of the window.
You keep the last word, and the mechanism guarantees it rather than promising it: the Colours tab still sets the board directly, and a colour chosen after the theme is yours. At start-up only the interface tokens are applied, never the board palette — the one you set is already loaded, and rewriting it at every launch would erase your work one session at a time. See ADR-0038.
Follow the system is the default: it obeys the desktop’s light/dark preference, including when it changes mid-session. A tool does not impose its light or its dark on a desktop that has already decided.
The Interface tab also lets you choose the language among English, French, German, Italian, Spanish, Finnish, Japanese, Greek and Russian. The whole interface (toolbar, panels, messages, help) is translated into the selected language. The language choice is saved and kept from one session to the next.
The Library tab gathers what belongs to the open file rather than to the machine. It is empty as long as no database is open, and it says so.
It carries first the two thresholds that decide the whole application’s vocabulary: a decision is an error as soon as its cost reaches the error threshold, and that error is a blunder as soon as it reaches the blunder threshold. Every blunder is an error, so the first threshold cannot exceed the second, and blunderDB refuses the inverted pair. The values are entered in equity — “0.080” — the unit of every table; the command line, for its part, speaks millipoints, so the 0.080 threshold is written E>80 in a search.
These thresholds follow the file, not the computer: the same database counts the same blunders wherever it is opened, blunderdb info displays them, and blunderdb edit --error-threshold / --blunder-threshold sets them. They do not travel in an export: a threshold is a reading habit, not a fact of the positions.
Three presets are offered in one click, each under the name of the program that drew that line: blunderDB (0.050 / 0.100), XG (0.020 / 0.080) and gnubg (0.040 / 0.080). By default, a library reads 0.050 and 0.100.
What they change, on screen: the blunder count of the status bar’s counter and the search its link prepares, the “Errors” and “Blunders” columns of the statistics and of the players table, the marks on the moves in a match’s detail pane (Matches Panel), and the list of positions blunderDB offers to review after an import.
The Reclaimable space line of the Maintenance tab carries the Compact button, which reclaims the disk space left by deletions (matches, tournaments, purges): the database never shrinks by itself when data is deleted, so this compaction must be requested explicitly. The operation can take a while on a large database. The compacted copy is written next to the file, then replaces it: temporarily, about the size of the database in free disk space is needed on its volume, not in RAM. If another program has the database open (a second read-only instance, for example), the file is not replaced: the database is compacted in place, which requires about twice its size in free space, and a temporary file goes into the system temporary folder, or the one designated by the SQLITE_TMPDIR environment variable: on a small /tmp, point it to the database’s volume. blunderDB refuses to start, with a message saying what is missing (disk space, or less than 512 MB of available memory), rather than risk an interrupted compaction. A confirmation is requested before the operation starts. The result — the space gained, in megabytes — is then shown in the status bar. The same operation is available on the command line via blunderdb vacuum (see Command Line Interface (CLI)).
After an in-place compaction, blunderDB checks that the file did shrink. On Windows, the system refuses to shorten a file that another program keeps open in certain ways: the compaction then ends with a message saying so — close the other program and run it again — instead of announcing a gain that did not happen.
The Open the log folder button, in the Interface tab, opens the folder holding the application log — useful for attaching details to a bug report, especially when blunderDB was started from a shortcut or a double-click, with no terminal attached to show anything.
The Check for updates at startup checkbox, in the same tab, off by default, queries the GitHub repository’s releases page once per launch and shows a message in the status bar when a newer version is available — never a window that gets in the way. This check stays automatically disabled on an installation that came through a package manager (Flatpak, Homebrew, a distribution package…): that channel is the one handling updates then, not blunderDB itself.
Two settings of the Interface tab govern the ranking of neighbouring positions (the like token, see Search Panel): the number of neighbours returned, and the maximum distance beyond which a position stops being one. That distance is zero by default, that is, no ceiling: the scale depends on the game phase, and a value chosen here would read as a measurement. The like<12 token imposes its own for one search, without touching the setting.
The Board colours tab lets you customise the board’s colours. Each element has its own colour picker: the background, the border, the light and dark points, player 1’s and player 2’s checkers, the dice, the dice pips and the cube. The Reset button restores all the default colours. Like the language, the chosen colours are kept across sessions.
The Bearoff tab manages the Eval panel’s bearoff tables (see Eval Panel). They are neither embedded in the executable nor downloaded: blunderDB computes them on the machine that uses them, and the result is identical byte for byte to what gnubg produces — the SHA-256 fingerprint is checked before a table is accepted.
The two ordinary tables (TS-06-06 for the cube verdict, OS-06 for the EPC) are computed on first launch, in the background and without asking: about six seconds on one core, during which the application is used normally. The Eval panel mentions it only if a position is placed there that needs a table which is not ready yet.
The tab shows the active domain and its origin, the state of the one-sided table the EPC reads, the folder where all this lives, and the list of the tables present with their size and their verdict. Each row can be deleted individually, after confirmation.
Verified or unverified. A verified table has exactly the bytes gnubg produces for its domain: its SHA-256 fingerprint is recorded in blunderDB and was found again. The fingerprints recorded for one-sided tables (OS-06 to OS-10) are the ones produced by GNUbg 1.08’s makebearoff tool. An unverified table is well formed but its domain has no recorded fingerprint — nothing is held against it, simply nobody has compared it to the reference. A corrupt table contradicts itself and is never read; it is recomputed.
Computing a wider table. The domain is picked from a list of two families, together with the number of cores to give it (by default all but one, so the machine stays usable):
exact cube (two-sided), from TS-06-06 to TS-06-15: widens the domain where the winning probability and the cube verdict are read rather than estimated;
EPC beyond the home board (one-sided), from OS-06 to OS-10: widens how far from home a chequer may stand without the EPC block going silent. This sweep reads only positions smaller than the one it is computing, so it is sequential by construction and the core count buys it nothing — the picker says so by greying out.
Before anything starts, the tab states three figures for the chosen domain: the size on disk, the memory needed during the computation, and the time it should take on this machine. The last one starts as an estimate and becomes a measurement: every run wide enough records its own speed and keeps it. A domain the available memory cannot hold is offered greyed out, with the reason — “it would need 24 GB, 12 are left” is an answer, an absent row would not be.
As an order of magnitude, on a sixteen-thread machine: TS-06-09 weighs 191 MB and takes about ten seconds, TS-06-11 weighs 1.2 GB and a few minutes, TS-06-13 exceeds what most machines can hold in memory. On the one-sided side, on one core: OS-07 weighs 4.9 MB and takes 17 s, OS-08 15 MB and 1 min 20, OS-10 117 MB and half an hour.
Pause and resume. During the computation, the progress shows the measured remaining time and two distinct buttons: Pause and Cancel. Pausing writes the state of the computation beside the table; running it again continues where it stopped instead of starting over. Cancelling keeps nothing. Closing the configuration window interrupts nothing — the computation carries on in the background.
A paused computation is found again at the next launch, named and quantified (“TS-06-09 interrupted at 43%”), with Resume and Delete. Nothing restarts on its own: the user is the one who asked it to stop.
The tab finally allows pointing to an external two-sided .bd file, for example a database produced by gnubg itself: the table with the widest domain wins.
The Maintenance tab shows the health of the database: one line per operation, with its count, its last run (date and outcome: done, cancelled or failed) and its action. Only the computation of the matches without statistics starts by itself, on opening.
Positions without analysis — the positions that carry no analysis; the action is the gammonNet analysis described below. The positions that gammonNet refuses to evaluate (a dance, a score outside the match table) stay in this count, which therefore does not necessarily reach zero.
Stale gammonNet analyses — described below.
Matches without statistics — the matches whose statistics are not computed yet; the action computes them all. A database opened for writing that has some computes them by itself in the background, in batches: the status bar shows this line’s progress and its cancel button, the tournament badges and the Players tab of the Statistics panel wait for the computation to end, and the rest of the application stays usable. Opening another database stops it. Read-only, or on the command line, the first reading of the statistics computes them, which can be long on a large database: the Statistics panel then shows this number, which opens this tab.
Analysis columns — the columns that search and statistics query are a projection of the stored analyses, which remain untouched: the action recomputes them without re-importing anything.
Played-move errors — scores the played moves that do not have an error yet.
Legacy-format analyses — rewrites in the binary format the analyses that an earlier version stored as JSON.
Trash — the number of entries in the trash, which opens it.
Reclaimable space — the free space of the file, which the compaction described above returns to the disk.
An expensive count (it reads an entire table) waits for the Count button. A count of positions opens those positions in the list; the count of matches without statistics opens those matches in the matches panel. An operation runs in the background: its progress and a cancel button appear in the status bar, and only one operation that writes to the database runs at a time — a gammonNet analysis, a rollout or another maintenance operation in progress causes the next one to be refused, with the name of the one occupying the database. On a database opened read-only, the actions are disabled. The same operations exist on the command line (blunderdb maintenance).
The gammonNet tab configures the embedded evaluator (see ADR-0011). Two search depths can be set there, named and kept separately — lowering one never changes the other:
Display depth — the interactive comfort while editing the board; never written to the database.
Analysis depth — what the post-import analysis batch writes into a position’s Analysis.
Both default to 2-ply, the canonical configuration. The menu marks the 3-ply and 4-ply depths with a ⚠, their cost per position far exceeding that of 2-ply. The tab also offers pruning (k=12 by default) and the number of candidate moves shown (10 by default), as well as an auto-analyze after import box which, once ticked, checks after every import whether positions with no analysis at all remain (neither gammonNet, nor XG, nor GNUbg, nor BGBlitz — the rule is “an evaluation only fills a hole”, never a replacement) and, if so, starts a gammonNet analysis in the background at the configured analysis depth. The Positions without analysis line of the Maintenance tab re-runs the same catch-up manually, useful for a library built before this feature existed.
A take or a pass is evaluated by gammonNet on the doubler’s decision, before the double. A gammonNet verdict written on such an answer by an earlier version of blunderDB judged the receiver’s redouble: it is deleted when the library is opened, or when a database that carries it is imported. The take or pass becomes a position without analysis again, absent from the statistics until the Positions without analysis line of the Maintenance tab (or the auto-analysis after import) evaluates it again.
The Stale gammonNet analyses line of the Maintenance tab covers the opposite case: a position already analysed by gammonNet, but whose stored analysis was written by an engine version older than the one running, or at a depth different from the analysis depth configured above, is flagged there as stale and re-evaluated. A position that also carries an XG, GNUbg or BGBlitz analysis is never touched by this batch, whatever its gammonNet content — the protection of ADR-0013 remains unconditional. The count of stale positions reads every gammonNet analysis of the database: it waits for the Count button. The batch recomputes its own list when it starts.
Both batches are bounded, visible and cancellable, never a silent daemon: their depth, their progress (positions analysed / total, from 0 at launch) and a cancel button appear in the status bar for their whole duration, and disappear once finished in favor of a message summarizing the result — how many positions were analyzed, how many were refused (a position gammonNet declines to evaluate, such as a match score beyond its MET’s range, which is never a failure) and how many failed (retried, unchanged, on the next run). Closing the application during either loses nothing: each analyzed position is written as it goes, and the next run resumes exactly where the analysis stopped, with no journal to keep. Cancelling or closing also interrupts the position currently being computed, which stays without analysis.
Only one job writes the library at a time: a gammonNet batch, a stored rollout or a maintenance operation. A batch or an operation started from the Maintenance tab is refused while another job is running, and the status bar names that job; the batch an import, a transcription or a duel starts waits for it to finish instead, and the status bar shows it as “waiting” until it starts.
The same tab holds the setting for the rollouts started from the Analysis panel (see Rollouts), kept from one session to the next: Fast (216 games, truncated at 7 plies), Standard (1296 games, truncated at 11 plies) or Free, where every parameter can be edited — truncation, minimum and maximum games (multiples of 36), JSD limit, depth (ply), number of candidates, seed and number of processes.
Library match equity table. At the bottom of the tab, the Library match equity table (MET) list chooses the table gammonNet uses to value match scores: Kazaross-XG2, built in and the default, or a table imported from a GNUbg .xml file with the Import a .xml MET… button. The choice belongs to the database, not to the application: opening another database means getting its table back. Only explicit tables are read (not the parametric zadeh or mec tables); beyond the length of an imported table, the built-in table takes over. A table is identified by its values, not by its name: importing GNUbg’s Kazaross-XG2.xml adds nothing, it is the built-in table. Each analysis computed by gammonNet records the table it was computed with; imported analyses (XG, GNUbg, BGBlitz) are assumed to have been computed with Kazaross-XG2. A match-score analysis computed with a table other than the current one is marked Different MET in the analysis panel and left out of the statistics (average errors, PR, rankings, head-to-head); a money-game analysis never is. Changing the table rewrites no analysis: only what the comparisons keep changes.
The panel’s live evaluation and the cube matrix are valued with the database’s table, like the analyses it stores. A table travels with the analyses that cite it: exporting a database takes it along, and importing a database adds it to the receiving database, without duplicates (a table already held is recognised by its values) and without making it current. A gammonNet analysis replaced by another engine’s (XG, GNUbg) is again taken as computed with Kazaross-XG2.
A match imported without an analysis now gets a Performance Rating. That is the case of a match played online, or of a Jellyfish .mat file, that nobody ran through XG: blunderDB knew its positions and the moves played, but no analysis said what they were worth. Once the batch has run, the move actually played is compared with gammonNet’s ranking and the gap feeds the PR, the error rate, the worst decisions and every other indicator, exactly as for a match analysed by XG. The comparison invents nothing: the played move comes from the match’s own move table, written at import whether or not the file carried an analysis.
A database analysed with a version older than this one does not need to be re-evaluated: blunderdb repair recomputes the columns from the analyses and the moves already stored and gives those matches their PR back (see repair).
One honest caveat: a position is identified by its structure, so a position met twice — played well once and badly the other time — carries only one gap, that of its first recorded occurrence. This is not specific to this computation: an XG library has exactly the same shape.
Watched folder
The Watched folder tab asks blunderDB to look at a folder while it runs and import each match file that appears in it. Play a session in eXtreme Gammon, come back to blunderDB, and find the matches already there.
Nothing is guessed. Until a folder is named there is no watch: blunderDB does not start reading a directory because it supposed where your matches live. The Suggest button looks at the usual places on this machine and offers one only if it really exists; otherwise it says so, and naming the folder is up to you.
Three things are worth knowing before ticking the box:
Only files that appear are imported. Whatever the folder already holds when the watch starts is recorded as known and left alone: pointing a watch at four years of matches must not import all of them. To import what is there, use the folder import, which exists for that — and the two compose very well, the import first, the watch after.
A file is imported only once its size has settled. A match another program is writing grows from one glance to the next; importing it half-written would give a parse error nobody can act on. blunderDB therefore waits to see the same file unchanged twice.
The import is silent. You were studying a position when your matches arrived: taking the screen back from you would be the worst possible moment. The mode, the active search, the tab and the displayed position do not move; the position list is not reloaded and shows the new matches at the next reload. The import runs without a window, and the status bar shows a banner giving the count of matches imported, skipped (duplicates) and failed, with a button that opens the full report if you wish. Everything else is identical to a manual import: the same duplicates detected, the same import batch, the same automatic analysis if it is enabled.
The default interval is ten seconds; the floor is two. The folder is not walked recursively: a watched folder is where a tool drops its matches, not a tree to crawl. An unmounted network share does not stop the watch, nor does it make its contents pass for new when it comes back.
The same watch exists on the command line, with blunderdb import --type batch --dir <folder> --watch (see Command Line Interface (CLI)): it is the form a server, a scheduled task or a script can use.
Synchronising two machines
Copying your .db database from one machine to another, or keeping it in a synchronised folder (Syncthing, Dropbox…), eventually damages it: SQLite writes journal files next to the database that a file synchroniser copies in the wrong order. blunderDB instead synchronises two libraries through incremental exports dropped in a folder that the other machine watches. The transport is up to you — Syncthing, USB stick, email: there is no server and no account.
On machine A, in the export window, choose Whole library, tick Only what is new since the last export to this folder and designate the folder with Choose the folder…. Each export writes a
sync-<machine>-<date>.dbfile there that contains only what has entered the library since the previous export to that same folder; the first one contains everything.On machine B, make that folder the watched folder. Each
.dbfile that appears there is merged without a preview, as by a database import: a position already known is not duplicated, a match already known is recognised, collections and lessons are merged by name.Do the same in the other direction, with a second folder.
What you need to know:
The “last synchronisation” marker belongs to the side that exports, one per destination folder, and only advances when the file is complete. The receiving machine records nothing. An export that fails leaves the marker in place: the next one carries the same rows.
Synchronisation is append-only. A deletion does not propagate: deleting a match on A does not delete it on B. Neither does an in-place modification: a rewritten comment, a renamed match, an analysis redone on a position already sent. What goes out are the positions, matches, tournaments, collections, lessons and comments entered since the last export; a collection also goes out again when a position has been added to it, and a position when a comment has been added to it. A rewritten comment does not go out again, because the receiving machine never replaces a text it already holds: to pass on a correction, add it as a new comment. Saved filters and Anki decks are not part of it: an export of Whole library without the checkbox carries them.
What a machine has received goes back once to the other, since it is new in its library; the other recognises it without adding anything, and the next exchange is empty.
A file that arrived while blunderDB was closed is not lost: when the watching starts, each
.dbalready in the folder is merged, unlike match files. The receiving machine does not note what it has read; so at every start it merges again all the files the folder still contains, adding nothing, but at the cost of the time to read them again. Delete thesync-…files already received from time to time so that this start stays fast.The first synchronisation after the update sends every commented position once more, because the marker did not yet follow comments. The other machine recognises them without duplicating anything; only the file is larger than usual.
An incremental export never overwrites a file. The previous file may hold rows the other machine has not received yet: an export to a file name already taken is refused. Choose the folder, and each export takes a new name there.
A file rewritten under a name already seen is merged again: the watch recognises a file by its name, size and modification date.
The open library is never merged into itself: if it lies in the watched folder, the watch passes over it.
An export that had to set aside rows (reported in the log) does not advance the marker: the next one retries them, with everything that follows them.
An export is never seen half-written: it is written under a hidden name and then renamed in one step. A password-protected file (
.dbx) is not picked up by the watching, which cannot ask for the password.
On the command line, blunderdb export --type database --incremental --file <folder> on one side and blunderdb import --type batch --dir <folder> --watch on the other (see Command Line Interface (CLI)). The server accepts "incremental": true on /v1/exports.sqlite (see Headless mode (server)).
Assistant and MCP
The Assistant and MCP tab controls two things, both disabled by default.
The local MCP server offers blunderDB’s tools (search, reading a position and its analysis, a player’s statistics, quizzes…) to an assistant that speaks the Model Context Protocol, such as Claude Desktop or Claude Code, as long as the window is open. It listens only on this machine, at http://127.0.0.1:<port>/mcp (port 8765 by default), and rejects a request coming from a web page. It adds two display tools: open a view on a search and show a position. The tools only read, unless Allow writing is checked: they can then save a position, comment on it, create and fill a collection, rate an Anki card and save a rollout next to a position’s analysis; nothing is deleted. Without an open window, blunderdb mcp serves the same tools (see Command Line Interface (CLI)).
The built-in assistant is a client of these same tools. No model is embedded: it talks to an OpenAI-compatible provider — Ollama on this machine by default, or Groq, OpenRouter, Gemini, Anthropic, or another address. Any address outside this machine is remote, whatever the provider chosen: your sentences and the tool results then leave the machine, the tab says so and waits for your agreement for that precise address; another address asks again. The API key goes into the system keyring, never into the database or the settings file. The model suggested by default for Ollama, qwen2.5:7b, is a starting point, not a recommendation: no model recommendation is made without a score from the benchmark shipped with the source code.
Once enabled, the assistant is an Assistant sub-tab of the Search panel. A sentence — “my errors of more than 50 millipoints in the race” — opens a new view named after it, runs the search there and switches to it; its tokens stay in the search history. What the tools return comes from the database; what the model writes is marked Model’s free text. The assistant only proposes a change if the Let the assistant propose changes box is checked — a setting separate from writing on the local MCP server — and each change it prepares is displayed and is only made after Confirm.
The configuration window also provides interface display settings. An interface scale slider lets you enlarge or shrink all interface elements, which is useful on high-density screens or to improve readability. The shortcuts CTRL-+, CTRL– and CTRL-0 set the same scale, as in a browser. A panel position menu sets where the panels (search, matches, analysis) appear relative to the board: bottom, side or automatic (the side is then chosen on wide screens to make better use of the available space). Like the other settings, these choices are kept from one session to the next.
Guided tours and sample database
To make getting started easier, blunderDB offers guided tours of the interface. The tour catalogue opens from the toolbar or with the tutorial command (alias tour). Seven tours are available: a general tour of the interface, and tours dedicated to searching positions, reviewing matches, reviewing tournaments, the Eval panel, Anki review and statistics. Each tour highlights the relevant interface elements, step by step, opens the panel it talks about along the way, and can be replayed at any time. On first launch, the general tour is offered automatically.
The demo command loads a sample database that lets you explore the tool’s features without importing your own games: three matches (two of them grouped in a tournament) analysed by eXtreme Gammon, BGBlitz and gammonNet, three thematic collections, tagged comments (#blunder, #cube) and an Anki deck with its review log. The players, the tournament and the venue are fictional. The guided tours rely on this database when no database is open.
Editing positions
Pressing the TAB key opens the search panel and allows editing a position on the board to add it to the database or to define a position structure to search for. The distribution of checkers, the cube, the score, and the turn can be modified using the mouse (see Edit a position).
Tip
Refer to Keyboard shortcuts for available shortcuts.
The command line
The command line, integrated into the status bar, allows you to perform all the functionalities of blunderDB available in the graphical interface: general operations on the database, position navigation, displaying analysis and/or comments, searching for positions based on filters… After getting familiar with the interface, it is recommended to gradually use the command line for a powerful and smooth use of blunderDB, especially for position search functionalities.
To open the command line, press the SPACE key. To submit a query and close the command line, press the ENTER key.
blunderDB executes the queries sent by the user as long as they are valid and immediately modifies the state of the database if necessary. There are no explicit save actions required from the user.
Tip
Refer to list of commands for the list of available commands in the command line.
The command palette
The command palette (CTRL-SHIFT-P) finds, by an approximate name, what you no longer know where to look for: a command of the command line, a tab, a filter of the library or a match. The letters typed must appear in order, not necessarily next to each other, regardless of case and accents: “cbmtx” finds the cube matrix, “lyon” the matches of a tournament in Lyon.
The arrows choose, ENTER runs, ESC closes. A command runs as if it had been typed; s and ss open the command line to write the filters in it; a filter runs as from a double-click in the library; a match opens as from a double-click in the Matches panel.
When a Direction is open, the palette adds the tournament: players, tables, running matches and competitions (see quick search).