
pgboxdb
Isolated disposable Postgres branches per Claude Code session and subagent, with real databases never touched.
- GitHub stars
- 722
What it does
- Adds the
pgboxdbskill, giving each Claude Code session and its subagents a copy-on-write Postgres branch - Covers project detection, a schema-only template from existing PostgreSQL, and a one-time
pgboxdb agent setup - Enforces isolation through lifecycle hooks that export
DATABASE_URLper session and keep credentials out of the conversation - Designed for projects where parallel agents, migrations, and test runs must not overwrite one another's data
Give every AI coding agent its own isolated, disposable Postgres database.
Add marketplace
/plugin marketplace add pgrundev/pgxRun it inside Claude Code once, then install the plugin below.
Install
/plugin install pgboxdb@pgrundevRun it inside Claude Code after adding the marketplace.
Readme
PGBoxDB — Postgres for Agents
One plugin. Every Claude Code agent gets its own Postgres.
PGBoxDB is a local, PostgreSQL-compatible runtime built for disposable databases:
copy-on-write branches created in milliseconds and removed automatically when
their time-to-live runs out. This plugin ships the pgboxdb Agent Skill, which
gives each Claude Code session, and each of its subagents, its own branch of
your project's database, so parallel agents, migrations and test runs never
touch your real PostgreSQL and never overwrite one another.
The plugin contains instructions and integration logic only. The PGBoxDB database
runtime (the pgboxdb binary, PGBoxDB 0.2.0 or newer) is installed separately,
and a project still needs a one-time pgboxdb agent setup before its sessions
are isolated. Both steps are walked through by the skill the first time you
use it in a project.
In a repository that uses PGBoxDB Git
(pgboxdb git init: one database per Git branch and worktree), each session's
branch is cloned from the database of the Git branch it works on, and a
session that switches Git branches is moved to a branch of the new one
automatically.
Install inside Claude Code
The lightweight plugin repository, pgrundev/pgboxdb-plugin, holds only this
plugin (about 100 KB) and is the fastest way to install:
/plugin marketplace add pgrundev/pgboxdb-plugin
/plugin install pgboxdb@pgboxdb-plugin
Pick the scope in the dialog: user makes the skill available in every project on this machine, project or local limit it to one repository. From a shell, one command does both steps:
claude plugin install pgboxdb --marketplace pgrundev/pgboxdb-plugin
The same plugin is also published from the main PGBoxDB repository, which Claude Code clones in full (about 2 GB) to read its catalog:
/plugin marketplace add pgrundev/pgboxdb
/plugin install pgboxdb@pgrundev
Install from one marketplace only: pgboxdb@pgboxdb-plugin and pgboxdb@pgrundev are the
same plugin and both load the skill as /pgboxdb:pgboxdb. For Cursor and Codex, or to
keep the skill as plain files in the project, use the Agent Skills CLI:
npx skills add pgrundev/pgboxdb --skill pgboxdb.
PGBoxDB is not yet listed in Anthropic's plugin directory. Once a listing is
approved, the plugin will also appear under Discover in /plugin.
Use it
Invoke the skill explicitly:
/pgboxdb:pgboxdb Set up isolated Postgres databases for this project.
or just describe database work ("run the pending migrations and the tests", "set up Postgres for my agents"); Claude selects the skill when it is relevant.
The first activation in a project walks through detection of the existing
database setup, a check for the PGBoxDB runtime (offering npm i -g pgboxdb or the
official installer if it is missing), a schema-only template copied from your
existing PostgreSQL or a fresh PGBoxDB database, and a one-time pgboxdb agent setup.
From then on every new Claude Code session in that project starts with
DATABASE_URL pointing at its own branch, and every subagent that session
launches gets a branch of its own, with its shell commands routed to it
automatically. Nothing in the plugin needs to be configured by hand.
What it contains, and what it does not
- The skill (
skills/pgboxdb/SKILL.md), its reference documents and two helper scripts:detect-project.sh(reads the project's database configuration, never printing credentials) andcheck-pgboxdb.sh(checks the installed PGBoxDB version). About 190 tokens of context while installed. - No hooks, MCP servers, binaries or background processes. Lifecycle hooks
are installed per project, and only on request, by
pgboxdb agent setup; installing or removing this plugin never changes a project's hooks or settings. - No database engine. The
pgboxdbbinary is installed separately when the skill first needs it. The skill asks before downloading anything.
What runs on your machine
Everything is local. The skill runs the pgboxdb CLI against the PGBoxDB runtime on
127.0.0.1; it does not call any network service of its own. Database
credentials for agent branches are generated by PGBoxDB, exported into the
session's environment by the hooks that pgboxdb agent setup installs, and never
written into the conversation; your existing PostgreSQL is read with
pg_dump --schema-only to build a template, and its data is copied only when
you explicitly approve it. Branches expire on their own (idle TTL, then a
short grace period after the session ends) and the PGBoxDB supervisor removes
them. Removing the plugin (/plugin uninstall pgboxdb@pgboxdb-plugin) removes the
skill only; databases, templates, .pgboxdb.toml and the PGBoxDB runtime stay, and
pgboxdb agent uninstall removes a project's hooks when you want that. The full
rules are in skills/pgboxdb/references/security.md.
Updates
The plugin's version follows the PGBoxDB Skill release. claude plugin update pgboxdb@pgboxdb-plugin (or Update now in /plugin) fetches a new version; an
older copy keeps working until then. The plugin's source lives in
pgrundev/pgboxdb (skills/pgboxdb, packaged in
plugins/pgboxdb); the pgrundev/pgboxdb-plugin repository is generated from it by
CI on every change to main, and a daily check there fails if the two ever
differ. Report issues and send changes to pgrundev/pgboxdb.
Troubleshooting
/pgboxdb:pgboxdbis not offered:claude plugin listshould show the plugin enabled; restart the session after installing.- "PGBoxDB not found" or "too old": install or upgrade the runtime
(
npm i -g pgboxdb@latestorcurl -fsSL https://pgboxdb.com/install | sh), then run the skill again. It needs 0.1.2 or newer for subagent isolation. - A session's
DATABASE_URLstill points at your real database: the project has not runpgboxdb agent setupyet, or the session started before it did.pgboxdb agent doctorreports the project's state. - More:
skills/pgboxdb/references/troubleshooting.mdand https://github.com/pgrundev/pgboxdb/blob/main/docs/pgboxdb/local-dev/agents.md
Details
- Marketplace
- pgrundev/pgx
- Source
- plugins/pgboxdb
- Category
- Database
More from pgrundev/pgx
All 2Similar to pgboxdb
More Databases
ruflo-migrationsruvnet/ruflo82.2K starsSchema migration management — generate, validate, dry-run, and rollback database migrations
diagram-designcathrynlavery/diagram-design68K starsEditorial diagrams in your brand, as self-contained HTML and SVG. Architecture, flowcharts, sequence, state machines, ER and database schemas, timelines, swimla
googlebigquery-automationComposioHQ/awesome-claude-skills51.5K starsAutomate Google BigQuery tasks via Rube MCP (Composio): run SQL queries, explore datasets and metadata, execute MBQL queries via Metabase integration. Always se
airtableanthropics/claude-plugins-official47.9K starsAirtable is the database and operations layer for your agents — whether running product, marketing, sales, ops, HR, or a custom business app. It combines struct
payloadpayloadcms/payload45.9K starsPayload Development plugin - covers collections, fields, hooks, access control, plugins, and database adapters.
database-cloud-optimizationwshobson/agents42.8K starsDatabase query optimization, cloud cost optimization, and scalability improvements