New advertisers: 50% off your first month with code FIRSTMONTHSee slots

Isolated disposable Postgres branches per Claude Code session and subagent, with real databases never touched.

GitHub stars
722

What it does

  • Adds the pgboxdb skill, 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_URL per 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/pgx

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install pgboxdb@pgrundev

Run 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) and check-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 pgboxdb binary 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:pgboxdb is not offered: claude plugin list should show the plugin enabled; restart the session after installing.
  • "PGBoxDB not found" or "too old": install or upgrade the runtime (npm i -g pgboxdb@latest or curl -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_URL still points at your real database: the project has not run pgboxdb agent setup yet, or the session started before it did. pgboxdb agent doctor reports the project's state.
  • More: skills/pgboxdb/references/troubleshooting.md and 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 2

Similar to pgboxdb

More Databases