GemDB CodeGemDB Code installs GemDB, an object database, and lets you work with it using Python in VS Code. Unlike a SQL database, there are no tables to design and no SQL to write: your Python objects are stored as they are, and every commit is an ACID (atomic, consistent, isolated, durable) transaction. Create objects, commit transactions, and explore your data without leaving your editor. The guided walkthrough takes you from install to your first commit. GemDB Code is in beta and is not intended for production use. GemDB Code runs one GemDB database under GemDB Code runs on macOS with Apple Silicon and on Linux (x86-64 or ARM64) and needs VS Code 1.101 or later. For a complete list, see Requirements. Start here
Features to check outPython REPL: the GemDB ShellThe GemDB Shell is a Python shell (a REPL, or read-eval-print loop) that runs inside the database. For more information, see Python in the database. Jupyter notebooksGemDB Code comes with a ready-made GemDB Notebook, with an example that shows GemDB in action. The Python kernel is built into the extension, so you do not need the Jupyter extension or a local Python install. Click New GemDB Notebook (the notebook icon) at the top of the GemDB Code sidebar to open a notebook with a starter cell, ready to run.
Running the cell shows MCP server for AI agentsGemDB Code includes an MCP (Model Context Protocol) server, so AI agents such as Claude Code or Cursor can explore your data, run Python in your database, and commit changes. For more information, see Connect an AI agent. Give an AI agent context about GemDBAn AI agent does not know how GemDB stores data unless you tell it. Paste this into your agent's chat before you ask it to build or change an application, and replace the last line with what you want:
The link opens the README as plain Markdown, which agents read more efficiently than the page GitHub renders. ReferenceThe rest of this page covers the details behind each feature.
RequirementsGemDB Code is available from the VS Code Marketplace and, for VSCodium and other compatible editors, from Open VSX. You need:
Needed only for some features:
You do not need:
Platform support
GemDB Code ships its Python runtime with a native library built for each platform's database engine, so the extension is published per platform, and every supported platform is built and tested on its own architecture. On an unsupported platform, the Marketplace still lists GemDB Code but marks it as not available for that platform, and you cannot install it. Setup and permissionsHow setup runsIn a local VS Code window, setup starts on its own the first time the extension activates on a
machine. GemDB Code downloads the database engine (about 170 MB on macOS, about 470 MB on Linux) and
creates one database under You can cancel the download. Canceling keeps what has already been downloaded, and Set Up GemDB picks up from there. The first time the database starts, usually right after setup, GemDB Code installs Python support into it. This takes a few minutes and shows its progress in a notification. If the database cannot start yet, this happens the first time you open a shell or run a notebook cell instead. When a GemDB Code update ships newer Python support, GemDB Code installs it into your database the
next time the database starts or you run Python, without prompting you. What you have stored keeps
working: dates and times, decimals, tuples and sets, enum members, and instances of your own classes
keep their types, and modules you deployed into the database are rebuilt in place, so stored objects
keep their classes. Two exceptions remain. If the update changes the base classes of a class you
have stored instances of, importing its module raises an error that names the class and the
Changes that need your permissionGemDB Code automates what is inert and reversible: files under
Your shell profile and AI clientsGemDB Code never edits your shell profile. For the line to add to it, see
The AI client configuration is different: GemDB Code sets it up for you where it can, so each client
connects to the right MCP server. In VS Code, it registers the server automatically. For Claude
Code, it runs Claude Code's own Trust
|
| Call | What it does |
|---|---|
gemdb.root |
The persistent root, a dict |
gemdb.commit() |
Makes this session's changes permanent; raises ConflictError if another session got there first |
gemdb.abort() |
Discards this session's uncommitted changes |
gemdb.refresh() |
Takes a fresh view to see other sessions' commits; raises PendingChangesError if you have uncommitted changes |
gemdb.needs_commit() |
Whether this session has changes that a commit would write |
gemdb.transaction() |
A with block that commits when it finishes and aborts on an exception |
import gemdb
with gemdb.transaction():
gemdb.root["visits"] = gemdb.root.get("visits", 0) + 1
gemdb.transaction() raises an error instead of starting if the session already has uncommitted
changes. Commit or abort them first.
Each session sees other sessions' commits after its own refresh(), abort() or commit().
The gemdb command
Setup writes a shell command to ~/GemDB/bin/gemdb that behaves like CPython's command line, backed
by the database:
gemdb hello.py # like python3 hello.py
gemdb -c 'print(1+1)' # like python3 -c
gemdb -m some.module # runs a module
gemdb # the GemDB Shell
Terminals you open in VS Code already have gemdb on their PATH. GemDB Code removes it again if you
disable the extension. To use gemdb in terminals outside VS Code, add this line to your shell
profile (adjust the path if you changed gemdb.rootPath):
export PATH="$HOME/GemDB/bin:$PATH"
The command needs no environment setup, and it starts the database if the database is not running.
Exit codes work the way scripts expect: 0 on success, 1 on an uncaught exception (Python's traceback
prints), 2 for a missing file, 130 when you stop the script with Ctrl+C (only KeyboardInterrupt
prints), and sys.exit() behaves as in CPython.
input() works in scripts, the GemDB Shell, and notebooks. A script reads stdin, and the GemDB
Shell reads its own prompt line, where Ctrl+C raises KeyboardInterrupt and Ctrl+D raises
EOFError. print() streams, so output appears while the code is still running.
With no arguments, gemdb opens the GemDB Shell, the same program that the Open GemDB Shell
button opens in a terminal. Each shell is a separate session. Use exit() or Ctrl+D to leave.
To run the Python file in the active editor, use the Run button's menu (▷ with an arrow) at the top right of the editor, or GemDB: Run Python File in GemDB in the Command Palette.
To debug it, choose Debug Python File in GemDB from the same menu. The file runs as __main__
in a session of its own, with its output in a GemDB Debug terminal, and breakpoint() opens
Run and Debug on the file just as it does on a notebook cell: the call stack, each frame's locals,
the file's globals, Add to Persisted Objects… and Add Stack to Persisted Objects…. The
session lasts as long as the terminal, so Commit and Abort in Persisted Objects work after
the run ends; closing the terminal ends the session and discards what it did not commit. Ctrl+C in
the terminal stops the run.
Red dots work in .py files: click in the gutter beside a line, and a run that reaches it pauses
there and opens Run and Debug, the same as breakpoint(). That holds for Debug Python File and for a
notebook cell that calls into a .py module. A dot also works in a module the run imports, and one
added while paused stops the run later on. Not supported yet: dots with a condition, hit count or
log message (they never stop the run, and the debugger says so), dots in notebook cells, and dots
in a class defined inside a function. A line that only returns a name, like return x, has no
code to stop at, so its dot stays hollow. A dot on the first line of a for loop's body also stops
once just before the loop's first pass. Run Python File in GemDB has no debugger, so it runs straight
past them.
Build an application on GemDB
A GemDB application is a Python program that you run with gemdb. Keep your objects under
gemdb.root and commit when a change is complete. This example has two files in one folder.
tasks.py:
from dataclasses import dataclass, field
from datetime import datetime
@dataclass
class Task:
title: str
created: datetime = field(default_factory=datetime.now)
done: bool = False
class TaskList:
def __init__(self):
self.tasks = []
def add(self, title):
self.tasks.append(Task(title))
main.py:
import sys
import gemdb
gemdb.use_namespace("todo")
from tasks import TaskList
if "todo" not in gemdb.root:
gemdb.root["todo"] = TaskList()
todo = gemdb.root["todo"]
if len(sys.argv) > 1:
todo.add(sys.argv[1])
gemdb.commit()
for task in todo.tasks:
print(task.title, task.created.strftime("%Y-%m-%d"))
Run gemdb main.py "buy milk", then gemdb main.py "call James". The second run lists both tasks.
- Arguments arrive in
sys.argv, as they do withpython3. - Imports work for any
.pyfile in the same folder as the file you run. That folder is already on the import path, sofrom tasks import TaskListneeds no setup. If two programs in one database each have a differenttasks.py, see Modules and namespaces. - Changes to stored objects are picked up by the next
gemdb.commit(). Appending to a stored list needs no assignment back intogemdb.root.gemdb.needs_commit()says whether a commit has anything to write. - Uncommitted changes are lost. A program that ends without calling
gemdb.commit()orgemdb.abort()discards what it changed. - A stored object keeps its class in the database. When you edit a class and run your program, the edited file updates the class stored under the same module name, and objects you stored earlier use the new methods. The update lasts only if the program commits. Without a commit, the new code applies only while the program runs.
- An object keeps the attribute values it was saved with.
__init__runs once, when you create the object. An attribute you add to__init__later is missing from objects you stored before. Give it a default on the class (done = False) instead. An object without the attribute reads the class value, as in Python, and assigning to it gives that object its own value. - Two sessions that change the same object conflict. The second
gemdb.commit()raisesgemdb.ConflictError, and its message says thatgemdb.abort()discards your changes. To retry, put the change in awith gemdb.transaction():block, which discards a failed attempt:
for attempt in range(5):
try:
with gemdb.transaction():
gemdb.root["todo"].add("buy milk")
break
except gemdb.ConflictError:
pass
Modules and namespaces
Give each application its own namespace. Without a namespace, GemDB treats a module name as
belonging to the whole database. If you have two programs, each with a file named tasks.py, the
second program's import tasks raises ImportError, because the database already holds a different
module named tasks. A namespace gives each application its own modules and its own gemdb.root,
so two files named tasks.py do not conflict with each other, and an application in one namespace
does not see the data of another. This includes data your application stored before you added a
namespace: it stays in the default root, and the namespace starts empty.
Import gemdb, call gemdb.use_namespace("my-app"), and only then import your modules,
including tasks:
import gemdb
gemdb.use_namespace("my-app")
from tasks import TaskList
Call it at the top level of the entry file, not inside a function, where it raises an error.
The name can be any text that is not empty, and capitals matter: my-app and My-App are different
namespaces.
In Python you can run any file at any time. GemDB saves your modules in the database and keeps track
of them by name. It also associates each namespace with the entry file you run. In gemdb main.py,
main.py is the entry file, and the files it imports, such as tasks.py, are its modules. If you
run a different entry file in the same namespace, the second command raises an ImportError that
names __main__. This happens with a second program such as gemdb admin.py, and with a test
script such as gemdb check.py, even if it only reads data. Invoking gemdb -c also causes it,
because it runs your code as a separate file. Editing main.py and running it again works as
expected. Setting the namespace with the GEMDB_NAMESPACE environment variable does not let a
different file run in the same namespace.
Run your application from one entry file, such as main.py, and put everything it does behind that
file. A program that serves requests, such as a web server, already works this way. For a program
with several tasks, choose the task with a command-line argument. For example, a main.py that
reads sys.argv[1] as the task name could take these two commands:
gemdb main.py add "buy milk"
gemdb main.py list
To look at the namespace's data from the GemDB Shell or through the MCP server, call
gemdb.use_namespace("my-app") first.
Notebooks
GemDB Notebooks are ordinary .ipynb files. A notebook you create with New GemDB Notebook uses
the GemDB (Python in the database) kernel automatically. To run another .ipynb file in the
database, select that kernel from the kernel picker at the top right.
- Variables are shared between the cells of a notebook. Running GemDB: Clear Notebook Variables
from the Command Palette clears them without restarting the database. Uncommitted changes stay in
the notebook's session; run
gemdb.abort()to discard those too. print()output streams into the cell while the cell runs.input()opens an input box, and pressing Escape raisesKeyboardInterrupt.- Each notebook has its own session and its own transaction, so a commit in one notebook never commits another notebook's half-finished changes. Closing a notebook ends its session and discards anything it has not committed.
- A new notebook is untitled until you save it, and saving it for the first time starts a fresh session. Commit before you save, or save before you start work.
- Renaming a notebook from VS Code's Explorer keeps its session and variables. Renaming it outside VS Code, or using Save As, starts a new session.
Debug a notebook cell
Call breakpoint() in a notebook cell to pause it. VS Code opens its debugger on the cell with no
setup. The Call Stack lists the function calls that led to the pause, and the paused line is
highlighted. Calling breakpoint() works the same way in Debug Python File in GemDB. In the
GemDB Shell and in Run Python File in GemDB, breakpoint() prints the file and line it was on,
and the code keeps running.
- Continue resumes the cell where it paused.
- Stop ends the cell, along with any cells queued after it.
Stepping is not supported yet. Red dots, the breakpoints you set by clicking beside a line number,
do not work in a notebook cell. They do work in a .py file you run with Debug Python File in
GemDB, and when a notebook cell calls into one. See The gemdb command
section for an explanation of how to debug a .py file and what red dots do not support yet.
Look at what the cell has
When a cell pauses, open Variables in Run and Debug. It can show two groups:
- Locals are the variables of the function the pause is in. This group appears only when the pause is inside a function.
- Globals are the names your notebook has defined.
Each row shows a name, a type and a value, such as {int} 100. A container also shows its size, such
as {dict: 1} {'a': 1}. Copy Value copies the value without the type and size.
Expand a row to look inside it:
- A list or dictionary opens to its items or entries.
- Any other object opens to its attributes: the ones it has itself, the ones it gets from its class, and its properties and slots.
- Functions, including an object's methods, are under function variables. Imported modules are
under module variables. Names with double underscores, such as
__module__, are under special variables.
Change a value
To change a value while the cell is paused, right-click its row in Variables and choose Set
Value. You can change a variable, an attribute, an item in a list, or a value in a dictionary.
Type a Python expression, such as 42 or old_total + 1. The cell uses the new value when you
click Continue.
The change stays uncommitted until you commit, like a change made in a cell. In the expression you can use global variables, from any row, and local variables, from a row under Locals.
Run code at the pause
The Debug Console (in the bottom panel) runs Python while the cell is paused. So does Watch, a panel in Run and Debug where you add an expression to see its value each time the cell pauses. Type a line in the console and it runs in the function the pause is in. It can use that function's local variables, its module's globals and Python's built-in names. The result opens like a row in Variables.
- Names you create in the console last until the cell resumes.
- An error reads like a notebook traceback.
- If a line runs for a long time, a notification lets you stop it.
- A change you make to an object here stays uncommitted until you commit, as it would from a cell.
- If you paste code that starts with spaces, such as a block copied from a file, it still runs. The spaces that every line shares are removed first. This works in the Debug Console and for a Watch expression.
Right-click a row in Variables for two shortcuts:
- Show in Debug Console puts that object in the console. An object is shown with its attributes
listed, and a list or dictionary as one row that you can open. The row's name is left at the
prompt, or a single underscore (
_) for a row nested inside another, ready for your next line. - Choose Evaluate with self… to run an expression with
selfbound to that object, such aslen(self.history). The answer shows in the console.
Commands that start with %
A line in the Debug Console that starts with % is a GemDB command, not Python. Type % and the
console suggests them.
| Command | What it does |
|---|---|
%persist p |
Adds p to Persisted Objects. It is saved when the notebook commits. |
%persist expr as key |
Adds the result of any expression, under the key you give. |
%inspect expr |
Opens p, or any expression, in an Inspector (see Inspect an object). |
%pending |
Lists the persisted objects the notebook's next commit writes, each by its path under gemdb.root. Ctrl+click a link to show it in Persisted Objects. It also counts a few records that Grail keeps outside gemdb.root, which Persisted Objects does not show. |
%commit |
Commits the notebook. |
%names |
Lists the names you have bound in the console. |
%help |
Lists all of these. |
Two more things work in the console:
gemdbis always available, so a line copied from Persisted Objects, such asgemdb.root["orders"], works even if your program never imported it.- Each object in Persisted Objects is available by its key.
oisgemdb.root["o"], unless the paused code has its own nameo.persisted.oalways reaches it, whateveromeans, and a bare persisted name is labeled with where it came from. Typepersistedto list them all. While you type a name, autocomplete offerspersisted.ofor each persisted entry it starts. Press Tab to take a suggestion.
Persisted Objects
The Persisted Objects view, under GemDB and in Run and Debug, lists the objects stored under
gemdb.root.
Add an object. Right-click a row in Variables and choose Add to Persisted Objects…. The
object goes in gemdb.root under the key you give (one is suggested), and is written at the
notebook's next commit. Until then its row reads "added, not persisted yet".
Remove an object. Right-click an entry and choose Remove from Persisted Objects. For an
object you added but have not committed, this drops the addition. For an entry you have already
committed, it deletes the entry from gemdb.root and commits the removal at once.
Review entry contents. Expand an entry to see what is in it, the same way you expand a row in Variables: its attributes, or its items if it is a list or dictionary. You don't need a cell stopped at a breakpoint to do this. Variables shows values only while a cell is paused, but Persisted Objects works at any time. An entry you have committed is saved in the database, so you can open it at any time, even after you close VS Code and open it again. An entry you added but have not committed yet is not saved. It exists only in your notebook, so you can open it only while the notebook is not running a cell.
Long lists. A list or dictionary longer than 500 items opens to ranges of 500: [0 … 499],
[500 … 999], and so on. Each range opens to its items. A list longer than 250,000 items opens to
ranges of 250,000 first, and each of those opens to ranges of 500. When gemdb.root has more than
200 entries, they show as ranges of 200.
To jump to an item, right-click a list, set or dictionary (or one of its ranges) and choose Go to
Item…. Type a position (a negative one counts from the end, and [42], as the ranges write it,
also works) or a dictionary's key. The view opens down to that item and selects it. If it can't find
a key, it says so and how keys are written.
Uncommitted changes. Every notebook with uncommitted changes is listed below gemdb.root,
paused or not. Its row has Commit (✓) and Abort (↺) and a Pending changes group, which
lists the persisted objects pending the next commit. Abort discards all of the notebook's
uncommitted changes, not only the objects you added. Click an entry in Pending changes to go to it
under gemdb.root, where it is marked M. Hover over it to see what changed. Right-click it and
choose Revert to Committed Value to undo the change; VS Code asks you to confirm. If the view
still shows a change you reverted, click Refresh (↻). The view's title bar always has Commit
and Abort for the notebook you are working in.
Save a paused stack
To keep a paused cell as it is, right-click a row in the Call Stack and choose Add Stack to
Persisted Objects…. VS Code suggests a key under gemdb.root for it. The stack is saved like any
other object you add to Persisted Objects: it is written at the notebook's next commit.
After you commit, you can reopen the saved stack in the debugger: right-click it in Persisted Objects and choose Open Saved Stack in the Debugger. When nothing is running, you can also click Restore a Saved Stack… in Run and Debug.
The reopened stack has its own Debug Console, and it works on the saved objects. You can call a
method, bind a name, change an object, or %persist one. A change stays uncommitted until you run
%commit, which overwrites what was saved. When you close the stack with a change pending, VS Code
asks whether to commit it. If you click Cancel, the change is discarded and the stack stays as
it was saved.
Inspect an object
An Inspector shows one object in detail, in its own tab beside the editor. Use it when a row in Variables is too small to show what you need. The tab holds a strip of columns, one object per column.
Open one. Right-click a row in Variables, Watch or Persisted Objects and choose Inspect. Or
type %inspect and a name or expression in the Debug Console, such as %inspect p.
Tabs. Each column has tabs for what the object has, so they differ from one object to the next. A list has Items, Repr, Class and Evaluate. A dictionary has Entries instead of Items, and an integer has neither.
- Attributes: the object's attributes, grouped as in Variables.
- Items or Entries: the contents of a list or dictionary, 100 at a time, with a box to jump to a position or a key.
- Repr: the object's full text form, and its
str()when that is different. - Class: the object's class, with its module and base classes, and four sub-tabs: Methods, Attributes, MRO (the order Python searches classes for a name) and Docstring.
- Evaluate: type Python and it runs with
selfstanding for the object. Display It shows the answer, Execute It runs it without showing one, and Inspect It opens the answer in a new column. Shift+Enter does Display It. Ctrl+K D, E and I do the three (Cmd+K on macOS).
Move around. Right-click a row for Inspect, which opens its object in a new column, or
Dive Here, which opens it in the same column. ‹ and › go back and forward. The header of each
column shows the Python that reaches the object, such as self[:2][0]. Copy as Expression
copies it. The header also shows the object's OOP (its identifier in the database) and a
committed or not committed badge.
After the cell resumes. The Inspector keeps working after the cell continues, and between cells. If the notebook is busy running a cell, the Inspector tells you to refresh once it finishes. Click ↻ to read the object again.
Change something. Choose Edit Value… to change a row. Type a Python expression, as in the
Evaluate tab. A ↺ appears next to the new value, and clicking it returns the previous value. To add
the object under gemdb.root, choose Add to Persisted Objects… in a row's menu or at the top
right of a column.
An object you open from a committed entry in Persisted Objects can't be changed there, because nothing would commit the change. It offers neither Edit Value… nor Add to Persisted Objects…. Evaluate still reads the object, and anything an Evaluate line changes is thrown away. To change the object, open it from a notebook.
Connect an AI agent
GemDB Code includes an MCP server, which lets an AI agent such as Claude Code work in your database
on your behalf. Because your data is made of Python objects, the agent works with it by running
Python in the database: for example, to answer a question about your data or to add an attribute to
a class. It can also list what is stored, search for classes and methods, define classes and
methods, and commit changes. The server accepts connections only from programs on your computer
(127.0.0.1), so nothing on your network can reach your database through it.
The MCP server is off by default. Turning it on does not start anything by itself: it sets GemDB Code to run the server whenever the database is running. The server starts when the database starts, and stops when the database stops.
To connect Claude Code:
- Open the folder you want Claude Code to work in, such as the Brain Freeze demo.
- From the GemDB Code sidebar's ⋯ menu, choose Connect an AI Agent to GemDB. The first time, a dialog prompts you to turn the MCP server on. Choose Turn It On. GemDB Code starts the database, and with it the server, if they are not already running.
- From the list of clients, choose Claude Code. GemDB Code runs Claude Code's
claude mcp addcommand for that folder, and then shows you both the command it ran and the command that undoes it. - Start a new Claude Code conversation in that folder: run
claudeagain in a terminal, or start a new conversation in the Claude Code panel. Claude Code reads its list of servers only when a conversation starts, so a conversation that was already open does not see GemDB.
About the Claude Code connection:
It applies to that folder only. Claude Code conversations in other folders do not connect to GemDB. This is intentional: each connected conversation uses one of the database's limited sessions (see Sessions).
The database must be running. If you stop the database, restart it from the sidebar before you use Claude Code.
If you change the server's port (
gemdb.mcp.port), run Connect an AI Agent to GemDB again in that folder. GemDB Code prompts you before it replaces the old entry.If GemDB Code cannot run the command, because no folder is open or the
claudecommand cannot be found, it copies the command for you to run from a terminal prompt in that folder. If the folder is not trusted, it shows a warning instead: choose Manage Workspace Trust to trust the folder, then connect again, or choose Copy the Command to run it yourself.claude mcp add --transport http gemdb http://127.0.0.1:50390/mcp
Connecting other AI clients:
- Agents inside VS Code, such as GitHub Copilot in agent mode, need no setup to connect to the MCP server. Once the server is on, it appears in VS Code's MCP server list. If the database is stopped when one of these agents tries to use it, GemDB Code starts it.
- Claude Desktop and Cursor: choose that client in step 3 instead. GemDB Code copies a JSON snippet for you to merge into that client's configuration file. Like Claude Code, these clients need the database to be running.
- Any other MCP client that supports the Streamable HTTP transport: choose Something else to copy the server's URL.
Keep the following in mind:
- Each connected client gets its own session, so agents never see each other's uncommitted work. Agents take sessions from the same limited pool as your notebooks and shells (see Sessions), and the server itself holds one more.
- A client that disconnects badly keeps its session for up to 30 minutes, and reconnecting counts as a new client. An agent that repeatedly crashes and retries can use up every session and leave you unable to log in until those sessions are released. Stopping the database, or choosing Restart the MCP Server from the sidebar's ⋯ menu, releases them immediately. This is why the server is off by default.
- A connected agent can change and commit data, and define code, because running Python in your
database is most of the point. Clicking the Agent write access row in the sidebar, or running
GemDB: Toggle Read-Only Access for AI Agents, logs agents in as a database user that cannot
commit. They can still read everything and run code, but nothing they do is saved. Switching it
restarts the MCP server, which disconnects connected agents, and the first time you turn it on,
GemDB Code adds an
McpReadOnlyuser to your database.
The Brain Freeze demo
To explore a working application, choose Install Brain Freeze Demo from the ⋯ menu in the
GemDB Code sidebar. It clones brain-freeze, a Flask app
whose data, classes, and views all live in the database, into ~/GemDB/brain-freeze, opens it, and
shows its README. Running it again opens the copy you have rather than replacing it. The command
needs git.
Where things live
Everything GemDB Code creates is under one directory, ~/GemDB by default (gemdb.rootPath):
| Path | What it is |
|---|---|
db/ |
Your database, the only irreplaceable part |
GemStone64Bit<version>-<platform>/ |
The database engine |
grail/ |
The Python runtime library and native shim |
mcp/ |
The MCP server and the scripts for starting it yourself, created the first time you turn on the MCP server |
bin/ |
The gemdb command |
brain-freeze/ |
The Brain Freeze demo, if you installed it |
locks/, log/, mcp-router.json |
Bookkeeping for the engine and the MCP server |
The directory must be on a local disk. The database engine refuses to open its files on an NFS
mount, so on a machine whose home directories are NFS mounts, ~/GemDB cannot hold the database.
GemDB Code checks before setup downloads anything: if the directory is on NFS, it stops and offers
Choose a Local Folder…, which sets gemdb.rootPath to a GemDB folder inside the one you pick
and sets GemDB Code up there. To choose a location yourself, set gemdb.rootPath in your User
settings before you set up.
Avoid a folder that a sync service such as iCloud Drive, OneDrive, or Dropbox copies, too. That is
why the default is ~/GemDB rather than ~/Documents/GemDB: ~/Documents is commonly synced, and
letting a sync daemon copy a live database out from under the engine corrupts it.
GemDB Code updates and associated data
Each GemDB Code release is tied to a database engine version. A newer engine cannot open a database an older one wrote as it stands, so when an update moves to a newer engine version, GemDB Code upgrades the database in place, for the engine versions it knows how to upgrade from. Do not delete your database when the engine changes.
The first time you start the database after such an update (Start GemDB, a notebook cell, the
GemDB Shell, or running or debugging a file), GemDB Code asks before it changes anything. If you
agree, it stops the database, copies it beside itself (for example to
~/GemDB/db/data/extent0.dbf.pre-4.0.0.a5), upgrades it, and then installs Python support and the
MCP server again. The upgrade itself takes about a minute, and reinstalling Python support a few
minutes more. The copy needs about as much free disk as the database, plus 1 GB, and GemDB Code
checks for it first. If the upgrade fails, GemDB Code puts the copy back, says so, and does not start
the database. The copy is kept until you delete it; once you are happy with the upgraded database,
delete it to get the space back. If you decline, nothing changes and the database does not start
until you agree. When the database starts on its own, or for an AI agent, GemDB Code does not
upgrade it; it shows a warning with an Upgrade Database… button instead.
A database whose engine version GemDB Code cannot upgrade from, such as one created by GemDB Code 1.8.0 or earlier, still cannot be opened. GemDB Code then shows a message before it starts the database, naming the directory to remove. Removing that directory deletes everything stored in the database. VS Code updates extensions automatically, so an update can arrive without you choosing it. To decide when GemDB Code updates, clear Auto Update on its page in the Extensions view.
Changing the engine version yourself with the gemdb.engineVersion setting has the same effect: a
version GemDB Code can upgrade to is offered the upgrade, and any other is refused.
Settings
The default GemDB Code settings are designed to work on most systems, so most users do not need to change them. These include settings for locating where GemDB Code stores files, updating Python support, collecting garbage, recording statistics, and setting up the MCP server for AI agents.
If you want to review them, open VS Code's Settings (Ctrl+, on Linux, or Cmd+, on macOS) and search
for gemdb, or go to Extensions > GemDB Code in the list on the left. If you need to
customize your setup, change them in your User settings. They apply to the one GemDB database on
this computer, so a value set in a workspace or folder is ignored, and Settings Sync does not copy
them to other computers. The following table lists all of the settings and the defaults.
| Setting | Default | What it does |
|---|---|---|
gemdb.rootPath |
~/GemDB |
Where GemDB Code keeps everything; must be on a local disk |
gemdb.engineVersion |
(empty) | Advanced: override the pinned engine version |
gemdb.reinstallPythonOnUpdate |
true |
Install the Python support a GemDB Code update ships into your database by itself |
gemdb.maintenance.garbageCollectionIntervalHours |
24 |
Hours between scheduled garbage collections; 0 collects only when space runs short |
gemdb.maintenance.abortIdleSessionsAfterMinutes |
10 |
Minutes before an idle session with no uncommitted changes is refreshed |
gemdb.statistics.collect |
true |
Whether the database records its statistics for GemDB Stats |
gemdb.statistics.intervalSeconds |
20 |
Seconds between recordings |
gemdb.statistics.keepDays |
14 |
Days before a statistics file is deleted |
gemdb.mcp.enabled |
false |
Run the MCP server, so AI agents can reach your database |
gemdb.mcp.port |
50390 |
The port it listens on, always on 127.0.0.1 |
gemdb.mcp.readOnly |
false |
Log agents in as a database user that cannot commit |
gemdb.externalDatabase.gemstone |
(empty) | Advanced: use a database someone else runs, whose engine is here |
gemdb.externalDatabase.globalDirectory |
/opt/gemstone |
That database's lock directory (GEMSTONE_GLOBAL_DIR) |
gemdb.externalDatabase.stone |
gs64stone |
Its stone |
gemdb.externalDatabase.netldi |
gs64ldi |
Its NetLDI |
gemdb.externalDatabase.user |
DataCurator |
The account GemDB Code logs in as |
gemdb.externalDatabase.passwordFile |
(empty) | A file holding that account's password |
Before you change the following settings, note these important details:
gemdb.rootPath: GemDB Code does not move anything when you change it. Your existing database stays in the old directory, and the new one starts empty, so stop the database first, then run Set Up GemDB in the sidebar to set up the new location. Changing it also closes every notebook's session.gemdb.engineVersion: a database created by a different engine version cannot be opened unless GemDB Code can upgrade it in place. See GemDB Code updates and associated data before you change it.gemdb.statistics.*: changes take effect the next time the database starts.gemdb.mcp.enabled: if you turn it on here rather than with Connect an AI Agent to GemDB, the server starts the next time the database starts or you run Python.gemdb.mcp.port: after changing it, choose Restart the MCP Server from the sidebar's ⋯ menu, and update the URL in any external client you connected.gemdb.mcp.readOnly: changing it restarts the MCP server, which disconnects connected agents.gemdb.externalDatabase.*: for a machine where an administrator runs the database — a hosted or shared server. GemDB Code then installs Python support into your account and connects, and never downloads, creates, starts, stops, or removes the database. See Using a database someone else runs for what the administrator sets up.
Commands
GemDB Code includes commands to run useful functions in VS Code. The GemDB Code sidebar presents
most of these, either as a button along its top or in its ⋯ menu. To run a command, either use
the Command Palette (Ctrl+Shift+P, or Cmd+Shift+P on macOS) or run it from the sidebar. In the
Command Palette, type GemDB to list the commands. GemDB: Run Python File in GemDB and GemDB:
Debug Python File in GemDB appear only when a Python file is open, and GemDB: Keep the Database
Running After Logout appears only on Linux. The table below reviews the functions available as
commands or in the sidebar.
| Command Palette | Sidebar | What it does |
|---|---|---|
| GemDB: Start GemDB | ▷ button, or click the Stopped row | Starts the database |
| GemDB: Stop GemDB | ■ button | Stops the database (clicking GemDB in the status bar does the same) |
| GemDB: Open GemDB Shell | >_ button, or click the Running row |
Opens a Python shell inside the database |
| GemDB: New GemDB Notebook | Notebook icon button | Opens a notebook with a starter cell |
| GemDB: Refresh Status | ↻ button | Re-reads the state shown in the sidebar |
| GemDB: Connect an AI Agent to GemDB | ⋯ menu, or click the AI agent access row | Turns on the MCP server and connects Claude Code, or gives you another client's configuration |
| GemDB: Show Log | ⋯ menu | Opens GemDB Code's log |
| GemDB: Reinstall the Python Execution Engine | ⋯ menu, or click the Python row when an update is available or the install failed | Reinstalls Python support into your database |
| GemDB: Restart the MCP Server | ⋯ menu, while the database is running | Restarts the MCP server and releases agent sessions |
| GemDB: Collect Garbage Now | ⋯ menu, or click the Space row | Collects the database's garbage immediately |
| GemDB: Stop a Database Session… | ⋯ menu | Lists the sessions on the database and stops the one you pick; anything it had not committed is lost |
| GemDB: Install Brain Freeze Demo | ⋯ menu | Clones the demo application into ~/GemDB/brain-freeze and opens it |
| GemDB: Uninstall GemDB | ⋯ menu | Removes the engine, its Python support, and the MCP server, and offers the option to remove your database |
| GemDB: Set Up GemDB | Set Up GemDB button, before setup has finished | Runs or resumes setup |
| GemDB: Configure Shared Memory | Click the Shared memory row when it needs configuring | Raises the shared-memory limit (prompts you for your password in a terminal) |
| GemDB: Keep the Database Running After Logout | Click the Survives logout row, shown on Linux when RemoveIPC=no is not set |
Sets RemoveIPC=no so the database keeps running after you log out (prompts you for your password in a terminal); Linux only |
| GemDB: Toggle Read-Only Access for AI Agents | Click the Agent write access row, shown when the MCP server is on | Switches whether agents can commit, and restarts the MCP server |
| GemDB: Run Python File in GemDB | None; use the Run button's menu at the top right of a Python file | Runs the current .py file in a terminal; listed only when a Python file is open |
| GemDB: Debug Python File in GemDB | None; use the Run button's menu at the top right of a Python file | Runs the current .py file so that breakpoint() opens the debugger; listed only when a Python file is open |
| GemDB: Clear Notebook Variables | None | Clears the active notebook's variables |
| GemDB: Refresh Notebook View | ↻ button in a GemDB notebook's toolbar | Lets the active notebook see what other sessions have committed: runs gemdb.refresh() in its session |
| GemDB: Open Today's Statistics | Click the Statistics row | Opens the newest statistics file in GemDB Stats |
| GemDB: Open Statistics File… | None | Opens a statistics file you choose in GemDB Stats |
| GemDB: Copy Telemetry ID | None | Copies the ID that identifies your usage data to the clipboard, so you can ask for that data to be found or deleted |
Using GemDB Code vs. GemStone/S
GemDB Code is deliberately small. It manages the database instance that comes with it for demonstration purposes.
If you want to manage a GemStone/S server running your GemStone/S database, use
Jasper: A GemStone Smalltalk IDE.
This full-featured extension exposes the full control surface, including a version picker, a
database list, a login manager, and a process view. GemDB Code and Jasper can be installed side by
side. GemDB Code keeps its files under ~/GemDB and names its processes distinctly, so the
databases remain separately maintained and controlled.
Uninstall GemDB Code
Removing the extension from VS Code does not remove the database or anything under ~/GemDB, and
the database keeps running after VS Code closes. Uninstall in this order:
- Open the GemDB Code sidebar. Click the GemDB Code icon in the Activity Bar, on the far left of VS Code.
- Stop the database. If the top row of the sidebar says Running, click Stop GemDB (■) at the top of the sidebar. Wait until the row says Stopped. GemDB Code does not remove its files while the database is running.
- Remove the database engine and Python support. In the sidebar's ⋯ menu, choose
Uninstall GemDB. The Remove GemDB? dialog shows where your database is and offers:
- Keep my database removes the engine, Python support, and the MCP server. Choose this option
to leave your data in
~/GemDB/db. - Remove everything, including my data also deletes the database. If you choose this option, it cannot be undone.
- Cancel closes the dialog.
- Keep my database removes the engine, Python support, and the MCP server. Choose this option
to leave your data in
- Uninstall the extension. Open the Extensions view, select GemDB Code, and click
Uninstall. Then restart VS Code to finish removing it, as with any extension. After the
restart, the GemDB Code icon is gone from the Activity Bar and
gemdbis no longer on the PATH of VS Code's terminals. - Delete
~/GemDBto remove what is left: thegemdbcommand, logs and bookkeeping files, the Brain Freeze demo and any commits you made in it, and your database if you kept it. The engine's files are read-only, so make them writable first: runchmod -R u+w ~/GemDB, thenrm -rf ~/GemDB.
If you connected an AI agent outside VS Code, remove GemDB Code's entry from that client's
configuration too. For Claude Code, run claude mcp remove gemdb --scope local in the folder where
you connected it.
GemDB Code leaves the operating-system changes you approved during setup in place, because other software may rely on them. To reverse them, delete GemDB Code's files, and then restart your computer.
On Linux:
sudo rm -f /etc/sysctl.d/60-gemdb.conf /etc/systemd/logind.conf.d/gemdb.confOn macOS:
sudo launchctl bootout system /Library/LaunchDaemons/com.gemdb.shared-memory.plist 2>/dev/null sudo rm -f /Library/LaunchDaemons/com.gemdb.shared-memory.plist
After the restart, shared memory (and on Linux, RemoveIPC) returns to the system default. Delete
only these files. Files with gemstone or gemtalksystems in their names belong to Jasper, and
while they are present, Jasper's settings stay in effect.
Privacy
GemDB Code sends usage events that carry no content from your work. The events include a
pseudonymous VS Code machine ID and a coarse location, and VS Code's telemetry.telemetryLevel
setting controls them. See USAGE_DATA.md for exactly what is and is not collected.
License
MIT. See LICENSE. GemDB Code reuses code from Jasper and bundles Grail and GemTalk's MCP server, all from GemTalk Systems, plus the koffi library. See NOTICE for details. GemDB Code downloads the database engine during setup, and the engine has its own license terms.
To build GemDB Code from source, see CONTRIBUTING.md.
This README ends with a tracking pixel. Read what it does and what it collects.